("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.
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.
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:
Intel IO access functions
MMIO access functions
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.
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
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.
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.
FIXME. Not written yet.