Gentoo Forums
Gentoo Forums
Gentoo Forums
Quick Search: in
[FAQ]KC7: What kernel module do I need for my hardware/card?
View unanswered posts
View posts from last 24 hours

 
Reply to topic    Gentoo Forums Forum Index Documentation, Tips & Tricks
View previous topic :: View next topic  
Author Message
keratos68
Guru
Guru


Joined: 27 Dec 2002
Posts: 561
Location: Blackpool, Lancashire, UK.

PostPosted: Mon Jun 16, 2003 11:47 am    Post subject: [FAQ]KC7: What kernel module do I need for my hardware/card? Reply with quote

KC7: Gentoo doesn't recognise my hardware/cards. What is the procedure/process I need to follow in order to get my hardware working assuming I'm working with Kernel Loadable Modules "KLM"s for driver support.

(1) Symptoms:
    * My peripheral and/or card just doesn't work or is not recognised.
    * System cannot start services at boot (e.g. eth0)
    * Applications cannot be started due to unrecognised hardware (e.g. sound/video)
    * Daemons do not start/generate errors due to lack of hardware support (e.g. CUPS and printer).


(2) What's the problem?:
    * The linux kernel does not know how to communicate with your hardware. You need to generate "KLM"s for the hardware and configure your system.


(3) Solution - Summary:

For a SINGLE item of hardware , a special kind of file called a linux Loadable Kernel Module or "LKM" is usually required.

The LKM is an object-code file that is compiled and linked in such a way , as to provide the necessary hooks'n'handles to facilitate driver-to-kernel communication and interfacing.

The basic process is as follows, detailed breakdown next section...

    * Identify the name of the hardware as Gentoo might recongnise.
    * Identify the card's unique Vendor ID and Product ID numbers.
    * Identify which LKM supports the hardware.
    * Create the LKM via the kernel build process.
    * Install the LKM.
    * Invite the kernel to load the KLM and all its dependencies.
    * Verify KLM load success.
    * Test the hardware.


(4) Solution - Detail:

The following subsections define, in more detail, the summary process above.


(4.a) Identify the name of the hardware as Gentoo might recognise.

The first process is to identify what the hardware is/card name etc. There are a variety of sources for this data:

1) The Manual !!

2) The BIOS startup/poweron screen.

3) Gentoo commands:
Code:
cat /proc/pci
## -or
dmesg
somewhere here, you should be able to pick up a text-string name of the hardware/product/card.


(4.b) Identify the card's unique Vendor ID and Product ID numbers.

Whilst the text string representation of the hardware should suffice, better still is the Vendor ID and Product ID which (I would hope) are unique.

These take the form of two 32 bit hexadecimal strings of the form:
Code:
0xVVVV/0xPPPP
- where:
- VVVV = 32bit hex Vendor-ID number/string.
- PPPP = 32bit hex Product-ID number/string.
again, these numbers might be available from the same sources above.

Additionally, you might wish to examine...
**TBD**


(4.c) Identify which LKM supports the hardware.

So , you have either (or maybe both) the text-string or the Vendor/Product IDs. So , which KLM might support this device?

Well , one might examine the various online databases but this runs the risk that obselecence (out-of-date) data may be presented. Better to examine YOUR specific box and determine what is actually on YOUR machine.

One way to do this, is to search the kernel source code to find a module that looks like it could support your hardware. To seach the source code, the following is useful:
Code:
find /usr/src/linux -name "*.c" -exec \
grep -iHR "MODULE_DESCRIPTION.*<<device-string>>" {} \;
## where <<device-string>> is the text string you have identifed. E.G:
find /usr/src/linux -name "*.c" -exec \
grep -iHR "MODULE_DESCRIPTION.*realtek" {} \;
## would find LKMs source files supporting the Real-Tek eth NICs!

For this to work, you need to have a kernel source tree installed and the /usr/src/linux directory needs to be a symlink to the kernel source tree you are using. Gentoo usually sets this up when you emerge some kernel sources, but anyone tinkering with this needs to be aware of the above.


(4.d) Identify which LKM supports the hardware.

So , hopefully this has displayed one (or more) 'C' source filenames containing the matched strings. Usually the name of the file (minus the .c) equates to the module name you must use - usually. There may be instances where a number of .c files are compiled and the resultant object code linked to form a single module which may not match/equate/resemble the original .c filename. In such a case , **TBD**


(4.e) Create the LKM via the kernel build process.

Now its time to create the modules. To do this , you need to amend the kernel configuration then perform a rebuild. This sounds graduate kind of stuff, but it is relatively simple, painless and yields the "Feel Good Factor" to oneself , in that you can claim to have built your first (and one of many!) linux kernels and modules. Of course, if you've already done this - then the novelty will probably be wearing off by now :P

Before doing this , it may be useful to read the latest documentation shipped with the kernel sources, pertaining to the module you wish to include. Documentation is held in the /usr/src/linux/Documentation directory, but you may wish to use the command:
Code:
find /usr/src/linux/Documentation -name "*.txt" -exec grep -iq <<module-name>> {} \; -print
## where "<<module-name>>" should be replaced by the module name (minus the .o or .c) from 4.d above.
## e.g. find /usr/src/linux/Documentation -name "*.txt" -exec grep -iq "8139too" > {} \; -print

as this should display the name of a text file containing further up-to-ate info on the module.

Next , amend the kernel config by editing the file /usr/src/linux/.config and setting the appropriate CONFIG_ line. Alternatively, newbies may wish to use the ncurses application:
Code:
cd /usr/src/linux
cp .config config.old
make menuconfig
... find and change the appropriate driver/module then save (to same file i.e. ".config" and exit.

Next , we need to clean out all remnants of any previous kernel/module build for the current kernel, and recompile the kernel + LKMs. If you already have a working functional kernel + an array of LKMs , then it would probably be a good idea to backup your kernel tree at this point.

So, to build the 'new' kernel + LKMs (including the one just enabled)..
Code:
cd /usr/src/linux
cp .config myconfig
make mrproper
cp myconfig .config
make dep
make bzImage && make modules

It IS important the kernel is recompiled when we compile LKMs as there are certain "artifacts" that are included/excluded when building driver support either into the kernel , or within a LKM.

So, assuming no errors , we should now have a kernel ready and respective LKMs ready.


(4.f) Install the LKM.

The previous process of compiling kernel + LKMs has completed successfully. Now we install the LKMs into the modules library for utilisation at boot time.

The command
Code:
uname -r
will tell you the name of the module library that LKMs are installed into. This library name is of the form /lib/modules/XXX/... where XXX represents the output of the uname -r command.

So, to install the modules use
Code:
make modules_install
and the modules (the .o files) should be installed into /lib/modules/XXX/...

For example if the uname -r command reported 2.4.20-r1 then issuing the command:
Code:
find /lib/modules/2.4.20-r1 -print
would show all the modules (.o) files installed.


(4.g) Invite the kernel to load the KLM and all its dependencies.

At this stage its probably a good idea to install the new kernel into your /boot directory/partition - for the latter , don't forget to ensure you mount it first :wink: For i386 PC users, the kernel will be in /usr/src/linux/arch/i386/boot/bzImage. Other users (PPC) should look in the relevant directory under /usr/src/linux/arch/....

A /usr/src/linux/System.map file will have also been created and should be retained for future kernel debugging by the brave!! but this is not necessary to have installed in /boot for now.

Next update your LILO and/or GRUB configs. Run /sbin/lilo -v if LILO using installed.

Reboot and select your new kernel. If the system boots fine , then well done. Half the job done!

Next , use the modprobe command to probe and load your module. Dependencies will also be probed and loaded:
Code:
lsmod
##...outputs a list of current modules
modprobe <<module-name>>
##...replace <<module-name>> with your module (no .o or .c !)
lsmod
hopefully your module and its dependencies have been loaded.

There are a number of possible falures that could occur as this stage and perhaps if you are unlucky to get an error at this point , then post it to the forums , there is simply too many drivers and too many errors for all to be documented here.

(4.h) Verify KLM load success.
**TBD**
#<<lsmod>>
#<<dmesg>>
#<<devfs>>
#<</proc fs>>


(4.i) Test the hardware.

**TBD**


(5) Resources:

**TBD**

(c)2003,Gentoo and the Gentoo Forums
GPL - Limited rights reserved.
No liability accepted for actions resulting from incorrect application , unauthorised inclusion outside Gentoo Linux GPL , unagreed modification and/or distribution.
Contact GDF Site Admin or Author to lodge RFCs.

CHANGE HISTORY
    Date: 16-06-03
    Author: keratos68
    - Created and entered into Forum.
    - Missing sections to be completed in conjunction with overall/specific comments received from members.
    - **TBD** sections to be completed during "work-breaks"!
    - URL links to other FAQs supporting above process to be embedded.

    Date: 17-06-03
    Author: keratos68
    - Expanded 4.e.
    - Expanded 4.f.
    - Expanded 4.g.

_________________
Someone told me that "..they only ever made one mistake...."

...and that's when they said they were wrong!!


Last edited by keratos68 on Tue Jun 17, 2003 10:39 am; edited 3 times in total
Back to top
View user's profile Send private message
dberkholz
Developer
Developer


Joined: 18 Mar 2003
Posts: 1008
Location: Minneapolis, MN, USA

PostPosted: Mon Jun 16, 2003 6:54 pm    Post subject: Re: [FAQ]KC7: What kernel module do I need for my hardware/c Reply with quote

keratos68 wrote:

(4.d) Identify which LKM supports the hardware.

So , hopefully this has displayed one (or more) 'C' source filenames containing the matched strings. Usually the name of the file (minus the .c) equates to the module name you must use - usually. There may be instances where a number of .c files are compiled and the resultant object code linked to form a single module which may not match/equate/resemble the original .c filename. In such a case , **TBD**

If I have no idea what the module is named, this is my preferred solution:
Code:
# find /lib/modules/`uname -r`/ -name *.o

That lists all available modules (loaded and unloaded) in the running kernel. From that output, it's usually fairly easy to discern which module is desired.
Back to top
View user's profile Send private message
keratos68
Guru
Guru


Joined: 27 Dec 2002
Posts: 561
Location: Blackpool, Lancashire, UK.

PostPosted: Tue Jun 17, 2003 5:51 am    Post subject: Re: [FAQ]KC7: What kernel module do I need for my hardware/c Reply with quote

spyderous wrote:
If I have no idea what the module is named, this is my preferred solution:
Code:
# find /lib/modules/`uname -r`/ -name *.o

That lists all available modules (loaded and unloaded) in the running kernel. From that output, it's usually fairly easy to discern which module is desired.


Ah , yes my friend , but our command presupposes that one has built the module in the first case , and does not indicate what H/W the module drives. You solution is acceptable in cases where one does not know which module (INCLUDING the name thereof) supports ones H/W.

The code above will coax, eventually, a module name, out of the totality of kernel source tree code. :wink:
_________________
Someone told me that "..they only ever made one mistake...."

...and that's when they said they were wrong!!
Back to top
View user's profile Send private message
Display posts from previous:   
Reply to topic    Gentoo Forums Forum Index Documentation, Tips & Tricks All times are GMT
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum