From: Brian Julin <bri@forcade.calyx.net>
  To  : ggi-develop@eskimo.com
  Date: Mon, 22 Feb 1999 18:58:43 -0500 (EST)

KGI restructuring and stuff

Personally I'm psyched to see a real move towards a new KGI.  We have
a lot more people on the list now than we did before, and I think
we can really make a lot of progress.  We do have a large number
of people who don't feel they are up to speed, however, and if
we want to get the most out of a willing but unable volunteer
base I propose the following -- we should write a short guide
to video hardware programming (with KGI specific examples) as we 
build the new specifications.

I say this because of some of my experiences trying to write 
KGI drivers over the past couple of years.  At times KGI was
pretty well documented just lacking in some areas that made 
it difficult to fit hardware to the API.  At other times, documentation
was sparse and some of the concepts in the code were alien to me.

What such a guide would contain is a 1) generic description (with 
diagrams) of the parts of a video device and how it works, 2) a 
categorization of the general types of each part found in the
real world, and the 3) specification of how the intraface between 
KGI modules deals with the qualities of each part.

Some of this is layed out already, but more with a focus on 3) neglecting
1) and 2).

An example of 1) would be a description of different types of RAMDACs
and how data flows through each type, explaining terms such as LCLK,
MCLK, etc.  An example of 2) would be something like this:

There are three basic types of clock chips; some chips can be of more
than one type at once:

   A) Chips that allow you to select from a list of clock frequencies,
      e.g. choose 31.5 MHz or 35.5 MHz.
   B) Chips that allow you to select from a range of clock values,
      e.g. any value between 20MHz and 60MHz in steps of 0.5MHz
   C) PLL clock chips that use a multiplier/divider to acheive 
      a large number of programmable frequencies 

And for 3) an explanation of the KGI structures used to represent
the characteristics, like Steffen's dotport concept/structure and
the intraface functions like getCLK.

After covering the basics in such a way, new developers will be
able to understand discussions/code documentation about the hairier 
parts such as checkmode negotiation.  Some of the guide will be more generic
than video focused -- e.g. how to treat PIO/MMIO.  Also (if we can
get people to read it) it will put us on the same page and avoid 
rehashing old material during list disucussions.

I have time to collate old and new material and maintain such a guide, 
and I am (or at least I consider myself to be :) a good technical writer.
And unlike a lot of people I actually _like_ writing documentation.
But even though I did get a KGI driver written and working for 
a certain duration, it was for a very simple chipset and I really only
have only amature experience (I'm especially weak on RAMDACs.)
That's a good thing though because if it gets explained to me in
a way that makes understanding dawn, it will be good text for new 
developers.

Even if it's not in the form of a programmer's guide, though,
I guess what I'm saying is I volunteer to maintain the documentation
for the KGI intraface and I believe I will have the time to do a good
job at that over the next two months (no guarantees after that.)
It will also motivate me to complete my driver code if I feel more
surefooted :).

P.S. Yes, I'll use SGML.

--
P.C.M.C.I.A. stands for "Plastic Connectors May Crack If Adjusted"
                                                             -- me
--
Brian S. Julin