diff options
Diffstat (limited to 'Documentation/modules.txt')
| -rw-r--r-- | Documentation/modules.txt | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/Documentation/modules.txt b/Documentation/modules.txt new file mode 100644 index 000000000..9fb147ecc --- /dev/null +++ b/Documentation/modules.txt @@ -0,0 +1,215 @@ +This file describes the strategy for dynamically loadable modules +in the Linux kernel. This is not a technical description on +the internals of module, but mostly a sample of how to compile +and use modules. + +Note: You should ensure that the modules-X.Y.Z.tar.gz you are using +is the most up to date one for this kernel. The "X.Y.Z" will reflect +the kernel version at the time of the release of the modules package. +Some older modules packages aren't aware of some of the newer modular +features that the kernel now supports. (If you are unsure, you can +usually find out what the current release of the modules-X.Y.Z.tar.gz +package is by looking up the URL listed for "Bjorn Ekwall" in the +file ./linux/CREDITS) + + +In the beginning... +------------------- + +Anyway, your first step is to compile the kernel, as explained in the +file linux/README. It generally goes like: + + make config + make dep + make clean + make zImage or make zlilo + +In "make config", you select what you want to include in the "resident" +kernel and what features you want to have available as loadable modules. +You will generally select the minimal resident set that is needed to boot: + + The filesystem of your root partition + A scsi driver, but see below for a list of SCSI modules! + Normal hard drive support + Net support (CONFIG_NET) + TCP/IP support (CONFIG_INET), but no drivers! + + plus those things that you just can't live without... + +The set of modules is constantly increasing, and you will be able to select +the option "m" in "make config" for those features that the current kernel +can offer as loadable modules. + +You also have a possibility to create modules that are less dependent on +the kernel version. This option can be selected during "make config", by +enabling CONFIG_MODVERSIONS, and is most useful on "stable" kernel versions, +such as the kernels from the 1.2 and 2.0 series. +If you have modules that are based on sources that are not included in +the official kernel sources, you will certainly like this option... + +Here is a sample of the available modules included in the kernel sources: + + Most filesystems: minix, xiafs, msdos, umsdos, sysv, isofs, hpfs, + smbfs, nfs + + Mid-level SCSI support (required by top and low level scsi drivers). + Most low-level SCSI drivers: (i.e. aha1542, in2000) + All SCSI high-level drivers: disk, tape, cdrom, generic. + + Most ethernet drivers: (too many to list, please see the file + ./Documentation/networking/net-modules.txt) + + Most CDROM drivers: + aztcd: Aztech,Orchid,Okano,Wearnes + cm206: Philips/LMS CM206 + gscd: Goldstar GCDR-420 + mcd, mcdx: Mitsumi LU005, FX001 + optcd: Optics Storage Dolphin 8000AT + sjcd: Sanyo CDR-H94A + sbpcd: Matsushita/Panasonic CR52x, CR56x, CD200, + Longshine LCS-7260, TEAC CD-55A + sonycd535: Sony CDU-531/535, CDU-510/515 + + And a lot of misc modules, such as: + lp: line printer + binfmt_elf: elf loader + binfmt_java: java loader + isp16: cdrom interface + serial: the serial (tty) interface + +When you have made the kernel, you create the modules by doing: + + make modules + +This will compile all modules and update the linux/modules directory. +In this directory you will then find a bunch of symbolic links, +pointing to the various object files in the kernel tree. +Now, after you have created all your modules, you should also do: + + make modules_install + +This will copy all newly made modules into subdirectories under +"/lib/modules/kernel_release/", where "kernel_release" is something +like 2.0.1, or whatever the current kernel version is... + +As soon as you have rebooted the newly made kernel, you can install +and remove modules at will with the utilities: "insmod" and "rmmod". +After reading the man-page for insmod, you will also know how easy +it is to configure a module when you do "insmod" (hint: symbol=value). + + +Nifty features: +--------------- + +You also have access to two utilities: "modprobe" and "depmod", where +modprobe is a "wrapper" for (or extension to) "insmod". +These utilities use (and maintain) a set of files that describe all the +modules that are available for the current kernel in the /lib/modules +hierarchy as well as their interdependencies. + +Using the modprobe utility, you can load any module like this: + + /sbin/modprobe module + +without paying much attention to which kernel you are running, or what +other modules this module depends on. + +With the help of the modprobe configuration file: "/etc/conf.modules" +you can tune the behaviour of modprobe in many ways, including an +automatic setting of insmod options for each module. +And, yes, there _are_ man-pages for all this... + +To use modprobe successfully, you generally place the following +command in your /etc/rc.d/rc.S script. (Read more about this in the +"rc.hints" file in the module utilities package, "modules-x.y.z.tar.gz".) + + /sbin/depmod -a + +This computes the dependencies between the different modules. +Then if you do, for example + + /sbin/modprobe umsdos + +you will automatically load _both_ the msdos and umsdos modules, +since umsdos runs piggyback on msdos. + + +The "ultimate" utility: +----------------------- + +OK, you have read all of the above, and feel amply impressed... +Now, we tell you to forget all about how to install and remove +loadable modules... +With the kerneld daemon, all of these chores will be taken care of +automatically. Just answer "Y" to CONFIG_KERNELD in "make config", +and make sure that /sbin/kerneld is started as soon as possible +after boot and that "/sbin/depmod -a" has been executed for the +current kernel. (Read more about this in the module utilities package.) + +Whenever a program wants the kernel to use a feature that is only +available as a loadable module, and if the kernel hasn't got the +module installed yet, the kernel will ask the kerneld daemon to take +care of the situation and make the best of it. + +This is what happens: + + - The kernel notices that a feature is requested that is not + resident in the kernel. + - The kernel sends a message to kerneld, with a symbolic + description of the requested feature. + - The kerneld daemon asks e.g. modprobe to load a module that + fits this symbolic description. + - modprobe looks into its internal "alias" translation table + to see if there is a match. This table can be reconfigured + and expanded by having "alias" lines in "/etc/conf.modules". + - insmod is then asked to insert the module(s) that modprobe + has decided that the kernel needs. Every module will be + configured according to the "options" lines in "/etc/conf.modules". + - modprobe exits and kerneld tells the kernel that the request + succeeded (or failed...) + - The kernel uses the freshly installed feature just as if it + had been configured into the kernel as a "resident" part. + +The icing of the cake is that when an automatically installed module +has been unused for a period of time (usually 1 minute), the module +will be automatically removed from the kernel as well. + +This makes the kernel use the minimal amount of memory at any given time, +making it available for more productive use than as just a placeholder for +unused code. + +Actually, this is only a side-effect from the _real_ benefit of kerneld: +You only have to create a minimal kernel, that is more or less independent +of the actual hardware setup. The setup of the "virtual" kernel is +instead controlled by a configuration file as well as the actual usage +pattern of the current machine and its kernel. +This should be good news for maintainers of multiple machines as well as +for maintainers of distributions. + +To use kerneld with the least amount of "hassle", you need modprobe from +a release that can be considered "recent" w.r.t. your kernel, and also +a configuration file for modprobe ("/etc/conf.modules"). +Since modprobe already knows about most modules, the minimal configuration +file could look something like this: + + alias scsi_hostadapter aha1542 # or whatever SCSI adapter you have + alias eth0 3c509 # or whatever net adapter you have + # you might need an "options" line for some net adapters: + options 3c509 io=0x300 irq=10 + # you might also need an "options" line for some other module: + options cdu31a cdu31a_port=0x1f88 sony_pas_init=1 + +You could add these lines as well, but they are only "cosmetic": + + alias net-pf-3 off # no ax25 module available (yet) + alias net-pf-4 off # if you don't use the ipx module + alias net-pf-5 off # if you don't use the appletalk module + +Finally, for the "purists": +You can name the modprobe configuration either "/etc/conf.modules" or +"/etc/modules.conf", since modprobe knows what to do in each case... + + +Written by: + Jacques Gelinas <jacques@solucorp.qc.ca> + Bjorn Ekwall <bj0rn@blox.se> |