From: Steffen Seeger <s.seeger@physik.tu-chemnitz.de>
  To  : GGI GGI <ggi-develop@eskimo.com>
  Date: Thu, 25 Feb 1999 10:39:51 +0100 (MET)

Re: RFC KGImodule register handling

Hello Jon,

Jon M. Taylor wrote:

> 	Anyway, I was thinking about how best to design such a utility for
> KGI drivers, and I came around to thinking about how to implement in the KGI
> drivers themselves the ability to dump and twiddle their own registers.  Upon
> consideration, I realized that the current state of register handling in KGI
> drivers is a real mess.

Because the underlying designs [(S)VGA] are a real mess. When doing the
Permedia driver things turned out to be rather easy, as it was _designed_
from the ground up with a register separation according to subsystems.

> Registers and register sets are defined ad hoc,
> there's too much emphasis on the [S]VGA-style register sets, and the register
> I/O methods are way too ad hoc as well. 

Not really, I think. I found it easier to use the register naming and
'subsystem' divisons given in the manual, however stupid they were.
Mainly because when 'renaming' and rearranging registers as I though 
it would be nice to have them, it turned out to be a rather bad idea,
as translation back to the 'manual blurb' was not obvious.
Sure, it's nice to write the code for the first time, but it turns 
out to be a nightmare when you have written another driver meanwhile
and have to track down a bug in existing code. Why? Because then you 
will have to _read_ your code, read the manual, compare what you do 
and what the manual tells you to do. If you have spottet the 
difference, you mostly found the bug.

Now, I made the experience that I spend more time reading my code than
writing it. That's why I tend to prefer high readability/easy understanding
(assuming you do have a manual) over easy coding. Of course one should
try to combine both.

> A chipset_io.inc file is what most
> extant KGI drivers use right now.  It will be a real PITA to wrap a good
> register-level debugging toolset around this mess without having to write
> tons of bridge code for all the special-case handling for each
> chipset/ramdac/clockchip's peculiarities.

Doesn't the debugging tool have to assume a common _internal_ structure of
the underlying hardware? E.g. presence of certain subsystems, etc.

Or are you speaking more of a register browser?
 
> It consists of the following basic underlying abstractions:
> 
> * Register I/O spaces.  This is already handled by the underlying KGI
> bus/system abstraction, which will be even better in Steffen's new KGI 0.9. 
> It needs virtualization, however.  A register I/O space is a linear chunk of
> registers and sub-I/O spaces with associated metadata.  Think of I/O spaces
> as register sets with common properties or behaviors.
> 
> * Registers, which are bitstrings of arbitrary length.  A register can be
> physical or virtual.  Physical registers are those which are directly
> adressable as a single unit by the hardware.  Virtual registers are composed
> of a set of bitstrings, each of which can come from any set of bits in any
> register(s), physical or virtual.  Virtual registers can be super-registers
> (like a PLL M value composed of 22 bits in three 8-bit registers) or
> sub-registers (like when the top four bits of an 8-bit register hold the DAC
> mode and the lower three hold clock control bits or something).  Registers
> also have associated metadata.
> 
> * I/O operations.  These are basic primitive operations that can be 
> applied to physical and virtual I/O spaces and physical and virtual 
> registers: Read, write, read-modify-write, remap, etc.  Each op has a 
> function hook associated with it, much as a kgi_display can have a 
> set_origin() hook.
> 
> * Metadata.  Registers and register I/O spaces can represent an almost
> infinite number of different data types, and furthermore each data type can
> be handled in a number of different ways.  In order for the driver to be able
> to divide the hardware resources into whatever resource abstractions it needs
> to and still be able to do everything it needs to do with those 
> resources, a matadata hook must be provided.  Same principle as the 
> private data hook in most kgi_* data structures.

I am not really sure it is worth the additional effort it adds to coding.
As an example, timing/mode select register values are computed
_once_ in the check_mode (with the new scheme) and written _once_
in the set_mode function. With the scheme proposed, I would have to
write the register/IO space definitions, write code to write/read them,
and collect them in the proper data structures. Then I would still have to
compute the correct values and finally write them.

Finally a point you brought up first: Wouldn't this make reverse
engineering/decompiling _a_lot_ easier? I mean, the driver would carry
a description of the subsystem layout in a way you can easily decode,
as know about the structures/data types used... Would vendors ever use
such a scheme?

Just to have a comparison, how would a rather complete description of
e.g. a MDA (16 CRT registers + a handful of 'misc' regs, IIRC) adapter
look like with your scheme?

			Steffen

----------------- e-mail: seeger@physik.tu-chemnitz.de -----------------