  Writing ggi drivers
  several
  (ed. 98/6/29)

  This is intended to become a collection of useful bits and pieces
  about how to write drivers for the GGI system. The first piece is the
  Makefile-Howto.

  1.  Integration of new KGI drivers into the source tree

  ("The makefile howto", by Matthias Grimrath)

  All kgi drivers are stored in a subtree of the GGI source tree.  To
  ease programming the drivers needn't and practically cannot be
  compiled by hand but by makefiles. This document describes how to
  properly insert a new driver.

  It is written for programmers who wants to hack a the driver and not
  mess around with makefiles.  Therefore it is not a description of the
  makefiles system by itself but rather a add-a-new-driver-howto.



  1.1.  A new chipset/clock/graphic/ramdac/kernel module


  Sometimes a vendor sells a new revision of a graphics board with (for
  example) a new ramdac while the rest (from a programming point of
  view) stays the same.  Or a port to a new architecture is on the way.
  Or a brand new gfx board is thrown on the market.

  In either cases, you need to edit the following lines in the makefiles
  <subsys>/<vendor|os>/Makefile.

  For example, TI has developed a new ramdac that is put on the latest
  S3 boards.  First, you need to find a name for your driver.  To stick
  with the example maybe something like 'ti12345'.

  Please note that the example below not only applies to RAMDACs, but
  also to a new chipset, clock, graphic or kernel module.

  Let's have a look at the important lines in ramdac/TI/Makefile:


  ______________________________________________________________________
  ALL_DRIVERS = tvp3026

  tvp3026_SRC = tvp3026.c
  ______________________________________________________________________



  There already is a driver for a different ramdac called 'tvp3026'.
  Since this is (so far) the only driver, the variable 'ALL_DRIVERS'
  only contains this name.

  Next there is the variable 'tvp3026_SRC'.  This variable holds all the
  source files that need to be compiled to form this driver.  As you can
  see, the name of the variable that holds all sources files is the name
  of the driver appended a '_SRC' to it.  Therefore, you must avoid
  chars in the driver name that cannot be part of a makefile variable.

  It is not necessary that the source file names are same than the
  drivername.


  Let's assume the new driver is simple, and only needs one source file.
  Then change the makefile as desribed below:


  ______________________________________________________________________
  ALL_DRIVERS = tvp3026 ti12345

  tvp3026_SRC = tvp3026.c
  ti12345_SRC = ti12345.c
  ______________________________________________________________________



  Now you have done all the necessary steps to integrate a new driver.
  That's it!  Easy, eh?  But the makefile system has more to offer, so
  you probably want to read on.



  1.2.  A new module from multiple source files


  The example in the previous chapter is perfect for situations if it is
  a totally different ramdac.  However, usually a new chip flavour
  shares common parts with others.

  In the example above, let's say the ramdac 'ti12345' is the same chip
  than 'tvp3026' except it can operate only in MMIO mode while the old
  one only with Intel IO.

  A natural thing to do is to separate the access to the registers and
  doing the RAMDAC calculations.  So the sources are split up:


     tvp3026.c
        Intel IO access functions

     ti12345.c
        MMIO access functions

     ti_tvp_common.c
        core functionality

  Then the makefile would look like:


  ______________________________________________________________________
  ALL_DRIVERS = tvp3026 ti12345

  tvp3026_SRC = tvp3026.c ti_tvp_common.c
  ti12345_SRC = ti12345.c ti_tvp_common.c
  ______________________________________________________________________



  Still, there's one little thing left, so you better read on.



  1.3.  Predefined constants


  Now let's assume the new ramdac not only operates in MMIO only mode,
  but also has a higher DAC speed.


  As the driver gets compiled with a constant 'DRIVER_<drivername>', you
  may insert the following to 'ti_tvp_common.c':


  ______________________________________________________________________
  #ifdef DRIVER_tvp3026
  #define DACSPEED 250
  #elif defined(DRIVER_ti12345)
  #define DACSPEED 280
  #else
  #error unknown TI RAMDAC!!!
  #endif
  ______________________________________________________________________





  1.4.  Making the driver available


  As the last step, you need to modify the '.configure' script and add
  your driver there.


  ______________________________________________________________________
  #!/bin/sh
  dialog \
  --title " Select RAMDAC type " \
  --menu "Please choose the DAC driver for your card.\n(current: $1)" \
  21 60 10 \
  \
  "tvp3026"           "TVP 3026" \
  \
  2> /tmp/.dactype
  ______________________________________________________________________



  To make the new driver selectable, add the line

  "ti12345"               "TI 12345"  \

  to it.



  1.5.  Templates

  If you need to create a new subdirectory for a new vendor of a
  chipset, clock, graphic or ramdac circuit, there is a template
  makefile and configure script in kgi/driver/chipset/stubs.



  1.6.  Adding a monitor driver


  FIXME.  Not written yet.







