
Third-Party Kernel Source Module Support, or
an easy way to add modules to your kernel build.



Vendors quite often add additional drivers and features to the kernel
which require nothing more than modifying Config.in, Makefile, and
adding one or more files to a sub-directory.  As a single discrete task,
this is not a problem.  However, using patches to add modules to the
kernel very often results in patch conflicts, resulting in needless time
wastage as developers regenerate an otherwise working kernel patch.

This is designed as a solution to these problems.  It is NOT designed as
a replacement for the kernel build system, but merely as a tool for
vendors and system administrators to ease the pain of patch management.

The key feature of this system is the distinct lack of patches.  Drivers
are installed via copying a file, and/or unpacking a tarball.



Adding a single-file kernel module to the build
-----------------------------------------------
Command summary:

	cd /usr/src/linux-2.4.3/3rdparty
	cp /tmp/my-driver.c .
	./mkbuild.pl -f my-driver.c

Notice the lack of CONFIG_xxx information.  This is all taken from
the .c file itself, using a system found in Donald Becker's device
drivers.  The format is self-documenting if you are familiar with the
makefile system.  Here is an example, from drivers/net/winbond-840.c:

/* Automatically extracted configuration info:
probe-func: winbond840_probe
config-in: tristate 'Winbond W89c840 Ethernet support' CONFIG_WINBOND_840

c-help-name: Winbond W89c840 PCI Ethernet support
c-help-symbol: CONFIG_WINBOND_840
c-help: This driver is for the Winbond W89c840 chip.  It also works with
c-help: the TX9882 chip on the Compex RL100-ATX board.
c-help: More specific information and updates are available from 
c-help: http://www.scyld.com/network/drivers.html
*/

NOTE that mkbuild.pl only uses "config-in" and "c-help-symbol" tokens
at this time.



Adding a single-file kernel module to the build
(without inline source info)
-----------------------------------------------
If the source file does not include inline source configuration info,
you must supply it on the mkbuild.pl command line.

	cd /usr/src/linux-2.4.3/3rdparty
	cp /tmp/my-driver.c .
	./mkbuild.pl -f my-driver.c -s my_driver \
		-D "Support for Foo Wizbang Hardware 4001"

The -s option creates the CONFIG_xxx variable, in this example
CONFIG_MY_DRIVER.  The -D option supplies the description that appears
in the Config.in file.



Adding a directory to the build (usually from a tarball)
--------------------------------------------------------
If a directory exists inside the 3rdparty sub-directory that contains a
proper Makefile, it can be added to the build.  It is highly recommended
that a Config.in file is supplied as well, but this is not necessary.

	cd /usr/src/linux-2.4.3/3rdparty
	bzcat /tmp/my-driver2.tar.bz2 | tar xf - # creates "my2" dir
	./mkbuild.pl -d my2

If a Config.in is not available, then you should use the -s and -D
mkbuild.pl options to create a Config.in entry.




Limitations
-----------
There are some limitations to this system.  This system is only
designed to support a very common case.  If you find yourself running
into limitations (kernel build experts can spot them right off),
then you should probably be patching the kernel instead of using
mkbuild.pl for that particular module.

FIXME: actually list the limitations



Other notes
-----------
Link order is controlled by the order of mkbuild.pl executions.

"make mrproper" will erase Makefile.meta, and empty Config.in, Makefile,
and Makefile.drivers.

IMPORTANT NOTE: Because this feature modifies the kernel's makefiles and
configuration system, you MUST complete all mkbuild.pl runs before
running any "make" command.

Building in the 3rdparty dir
----------------------------

If you use modules that:
	- are contained in one subdir with the name of the module
	- has a Makefile
	- has a Config.in file
The system calls the ./mkbuild.pl script with the correct arguments at
the correct times (a.k.a it is handled automagically) for the script
search_modules.pl.  It will be enhanced to autodetec normal files once that
I integrate a driver with only one file. 

