3. Configuring the software

3.1. What kind of driver do you have ?

I'll prefix all commands that need to be run as root with a '#', since that's the default prompt when you login as root.

Easy case: the driver is included in the kernel distribution. The magic word is:

# modconf

Browse through the menus until you find the right module, then press enter and say 'Yes' when asked if you want the modules loaded in the kernel.

if you need to pass arguments to the module, see the syntax below. If not, just press ENTER.

Medium case: you need to recompile your kernel. Usually that's because you're not using a standard kernel, or because your hardware is a bit too 'exotic'. You need to recompile your kernel (no big deal, usually). Since we at Newbiedoc think things ahead :-), there is a Kernel Compiling Doc.

Patching a kernel: sometimes patches are available that modify your kernel source. To apply a patch:

cd /usr/src/kernel-source-xx.yy.zz cat my_patch | patch -p0

(CHECK!! I can't seem to remember if it's -p0 or -p1 , but try the other if one doesn't work :-)

Hard case: You got the driver from elsewhere. Don't worry, it's not that bad if you have the source. You need first to compile it, then to try and load it, and then have it done automatically at boot-time. Section "Compiling a driver" is for you. The problem almost goes away (almost) if the driver's source is packaged as a Debian package, because most of the hard work will be done automatically for you. See Compiling a Debian-packaged module, below.

Evil case: Your driver is precompiled. Usually it is compiled against a given kernel ( say 2.2.15 , 2.2.16, and 2.2.17). In this case, either you run the right kernel, and in that case it should work well. Or you don't run the right kernel, and you have to consider switching kernel, getting a different driver, or getting similar hardware from a more linux-friendly vendor. In all cases, read the docs that comes with the driver since some stuff will be very specific, I can't help you there.

3.2. Compiling a driver

For those whose driver is not included in the standard kernel

3.2.2. Compiling a Debian-packaged module

For your convenience, some modules are packaged as Debian packages, specifically tailored to run well on a Debian system.

Those packages are usually of the form foobar-src-xx.yy.deb. To download one:

# apt-get install foobar-src

Apt will put the tarballs in /usr/src.

Uncompress the tarball: it will find its way to /usr/src/modules/foobar.

To compile the module, you either need the kernel source, or more simply the kernel-headers if you don't want to compile your kernel: it only contains the basic files.

The headers must be the exact ones for your kernel version. dpkg -l kernel-image will tell you which kernel-image you use

Once you're done, you should have a new directory: /usr/src/kernel-source-xx.yy.zz Go into that directory and do (as root):

# make-kpkg modules

It will compile all modules in /usr/src/modules and produce .debs for each: foobar-xx.yy.zz_i386.deb, for example, for module foobar compiled against kernel xx.yy.zz on an i386 platform.

Then you simply dpkg each .deb:

# dpkg -i foobar-xx.yy.zz_i386.deb

And each module will be installed in the correct place.

3.2.3. Testing the driver

The driver is compiled and ready for testing.

First of all, the dependencies between all modules need to be computed:

depmod

Then load the module:

# modprobe my_new_driver

It might need arguments, consult the README and see below the section about passing options to a module. To test if the module was correctly loaded:

# lsmod

will list all loaded modules. And to remove a module:

#rmmod my_new_driver

Some modules can't be removed because others depend on them. The names in brackets in an 'lsmod' are the modules dependencies.

3.3. Passing Options to a module...

3.3.1. ...at loadtime

Modules concerned by this are mostly those that talk to non Plug-and-Play devices, and some modules (PnP or not) that need a lot of info.

Usually (for non-PnP stuff) you need at least to tell the module the IRQ of the device it's talking to, and possibly some other stuff. This should load a good ol'SoundBlaster:

#modprobe sb irq=7 io=0x220 dma=1 dma16=6

Check if the modprobe succeeded by doing

#lsmod

there are dependencies for modules, so a module may request that others are loaded, and will load them by itself if they are available. For example, the 'sb' module might need the 'sound' module, etc.

Most settings are documented in the README file that came with the driver. For standard kernel drivers, see /usr/src/kernel-source-XX.YY.ZZ/Documentation. You may also want to check out the vendor's website for some FAQs and HOW-TOs.

3.4. Automatic Module Loading

There are two ways for modules to be loaded:

1. If they are needed by another module, or by a program that needs access to a device (graphics board, sound card,...). In that case there's nothing to worry about. The modules know which other fellow modules they need thanks to 'depmod', and the programs actually use /dev/* files, which are linked to corresponding modules by the 'alias' keyword in /etc/modules.conf

2. If they appear in /etc/modules

If arguments are needed, the module will know by itself to look for them in /etc/modules.conf. See paragraph about passing options ...Automatically

3.5. Summary

To summarize:

• Standard Modules on a stock kernel

  1. as root do

     #modconf

     provide the correct options (if needed) and have fun...

• Non Standard Modules

  1. Compile the driver

  2. Find the correct settings using

     #modprobe my_module irq XX dma YY other_option ZZ

  3. Add a file in /etc/modutils containing these settings (if no setting is needed, then you may skip this step). And run

     #update-modules

  4. Try to load the module with

     #modprobe my_module

     This shouldn't fail if the previous step was correctly done.

  5. If you want (or need), reference your module in /etc/modules.

  6. Have fun...