From: Qing He <qhe@ichips.intel.com>
  To  : ggi-develop@eskimo.com
  Date: Mon, 22 Feb 1999 16:11:34 -0800 (PST)

Re: KGI restructuring and stuff

This is a GREAT IDEA!!

> 
> 
> 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
>