1This file describes the strategy for dynamically loadable modules 2in the Linux kernel. This is not a technical description on 3the internals of module, but mostly a sample of how to compile 4and use modules. 5 6Note: You should ensure that the modutils-X.Y.Z.tar.gz you are using 7is the most up to date one for this kernel. The "X.Y.Z" will reflect 8the kernel version at the time of the release of the modules package. 9Some older modules packages aren't aware of some of the newer modular 10features that the kernel now supports. The current required version 11is listed in the file linux/Documentation/Changes. 12 13* * * NOTE * * * 14The kernel has been changed to remove kerneld support and use 15the new kmod support. Keep this in mind when reading this file. Kmod 16does the exact same thing as kerneld, but doesn't require an external 17program (see Documentation/kmod.txt) 18 19In the beginning... 20------------------- 21 22Anyway, your first step is to compile the kernel, as explained in the 23file linux/README. It generally goes like: 24 25 make config 26 make dep 27 make clean 28 make zImage or make zlilo 29 30In "make config", you select what you want to include in the "resident" 31kernel and what features you want to have available as loadable modules. 32You will generally select the minimal resident set that is needed to boot: 33 34 The filesystem of your root partition 35 A scsi driver, but see below for a list of SCSI modules! 36 Normal hard drive support 37 Net support (CONFIG_NET) 38 TCP/IP support (CONFIG_INET), but no drivers! 39 40 plus those things that you just can't live without... 41 42The set of modules is constantly increasing, and you will be able to select 43the option "m" in "make config" for those features that the current kernel 44can offer as loadable modules. 45 46You also have a possibility to create modules that are less dependent on 47the kernel version. This option can be selected during "make config", by 48enabling CONFIG_MODVERSIONS, and is most useful on "stable" kernel versions, 49such as the kernels from the 1.2 and 2.0 series. 50If you have modules that are based on sources that are not included in 51the official kernel sources, you will certainly like this option... 52 53Here is a sample of the available modules included in the kernel sources: 54 55 Most filesystems: minix, msdos, umsdos, sysv, isofs, hpfs, 56 smbfs, nfs 57 58 Mid-level SCSI support (required by top and low level scsi drivers). 59 Most low-level SCSI drivers: (i.e. aha1542, in2000) 60 All SCSI high-level drivers: disk, tape, cdrom, generic. 61 62 Most Ethernet drivers: (too many to list, please see the file 63 ./Documentation/networking/net-modules.txt) 64 65 Most CDROM drivers: 66 aztcd: Aztech,Orchid,Okano,Wearnes 67 cm206: Philips/LMS CM206 68 gscd: Goldstar GCDR-420 69 mcd, mcdx: Mitsumi LU005, FX001 70 optcd: Optics Storage Dolphin 8000AT 71 sjcd: Sanyo CDR-H94A 72 sbpcd: Matsushita/Panasonic CR52x, CR56x, CD200, 73 Longshine LCS-7260, TEAC CD-55A 74 sonycd535: Sony CDU-531/535, CDU-510/515 75 76 And a lot of misc modules, such as: 77 lp: line printer 78 binfmt_elf: elf loader 79 binfmt_java: java loader 80 isp16: cdrom interface 81 serial: the serial (tty) interface 82 83When you have made the kernel, you create the modules by doing: 84 85 make modules 86 87This will compile all modules and update the linux/modules directory. 88In this directory you will then find a bunch of symbolic links, 89pointing to the various object files in the kernel tree. 90Now, after you have created all your modules, you should also do: 91 92 make modules_install 93 94This will copy all newly made modules into subdirectories under 95"/lib/modules/kernel_release/", where "kernel_release" is something 96like 2.0.1, or whatever the current kernel version is... 97 98As soon as you have rebooted the newly made kernel, you can install 99and remove modules at will with the utilities: "insmod" and "rmmod". 100After reading the man-page for insmod, you will also know how easy 101it is to configure a module when you do "insmod" (hint: symbol=value). 102 103 104Nifty features: 105--------------- 106 107You also have access to two utilities: "modprobe" and "depmod", where 108modprobe is a "wrapper" for (or extension to) "insmod". 109These utilities use (and maintain) a set of files that describe all the 110modules that are available for the current kernel in the /lib/modules 111hierarchy as well as their interdependencies. 112 113Using the modprobe utility, you can load any module like this: 114 115 /sbin/modprobe module 116 117without paying much attention to which kernel you are running, or what 118other modules this module depends on. 119 120With the help of the modprobe configuration file: "/etc/modules.conf" 121you can tune the behaviour of modprobe in many ways, including an 122automatic setting of insmod options for each module. 123And, yes, there _are_ man-pages for all this... 124 125To use modprobe successfully, you generally place the following 126command in your /etc/rc.d/rc.S script. (Read more about this in the 127"rc.hints" file in the module utilities package, "modutils-x.y.z.tar.gz".) 128 129 /sbin/depmod -a 130 131This computes the dependencies between the different modules. 132Then if you do, for example 133 134 /sbin/modprobe umsdos 135 136you will automatically load _both_ the msdos and umsdos modules, 137since umsdos runs piggyback on msdos. 138 139 140Using modinfo: 141-------------- 142 143Sometimes you need to know what parameters are accepted by a 144module or you've found a bug and want to contact the maintainer. 145Then modinfo comes in very handy. 146 147Every module (normally) contains the author/maintainer, 148a description and a list of parameters. 149 150For example "modinfo -a eepro100" will return: 151 152 Maintainer: Andrey V. Savochkin <saw@saw.sw.com.sg> 153 154and "modinfo -d eepro100" will return a description: 155 156 Intel i82557/i82558 PCI EtherExpressPro driver 157 158and more important "modinfo -p eepro100" will return this list: 159 160 debug int 161 options int array (min = 1, max = 8) 162 full_duplex int array (min = 1, max = 8) 163 congenb int 164 txfifo int 165 rxfifo int 166 txdmacount int 167 rxdmacount int 168 rx_copybreak int 169 max_interrupt_work int 170 multicast_filter_limit int 171 172 173The "ultimate" utility: 174----------------------- 175 176OK, you have read all of the above, and feel amply impressed... 177Now, we tell you to forget all about how to install and remove 178loadable modules... 179With the kerneld daemon, all of these chores will be taken care of 180automatically. Just answer "Y" to CONFIG_KERNELD in "make config", 181and make sure that /sbin/kerneld is started as soon as possible 182after boot and that "/sbin/depmod -a" has been executed for the 183current kernel. (Read more about this in the module utilities package.) 184 185Whenever a program wants the kernel to use a feature that is only 186available as a loadable module, and if the kernel hasn't got the 187module installed yet, the kernel will ask the kerneld daemon to take 188care of the situation and make the best of it. 189 190This is what happens: 191 192 - The kernel notices that a feature is requested that is not 193 resident in the kernel. 194 - The kernel sends a message to kerneld, with a symbolic 195 description of the requested feature. 196 - The kerneld daemon asks e.g. modprobe to load a module that 197 fits this symbolic description. 198 - modprobe looks into its internal "alias" translation table 199 to see if there is a match. This table can be reconfigured 200 and expanded by having "alias" lines in "/etc/modules.conf". 201 - insmod is then asked to insert the module(s) that modprobe 202 has decided that the kernel needs. Every module will be 203 configured according to the "options" lines in "/etc/modules.conf". 204 - modprobe exits and kerneld tells the kernel that the request 205 succeeded (or failed...) 206 - The kernel uses the freshly installed feature just as if it 207 had been configured into the kernel as a "resident" part. 208 209The icing of the cake is that when an automatically installed module 210has been unused for a period of time (usually 1 minute), the module 211will be automatically removed from the kernel as well. 212 213This makes the kernel use the minimal amount of memory at any given time, 214making it available for more productive use than as just a placeholder for 215unused code. 216 217Actually, this is only a side-effect from the _real_ benefit of kerneld: 218You only have to create a minimal kernel, that is more or less independent 219of the actual hardware setup. The setup of the "virtual" kernel is 220instead controlled by a configuration file as well as the actual usage 221pattern of the current machine and its kernel. 222This should be good news for maintainers of multiple machines as well as 223for maintainers of distributions. 224 225To use kerneld with the least amount of "hassle", you need modprobe from 226a release that can be considered "recent" w.r.t. your kernel, and also 227a configuration file for modprobe ("/etc/modules.conf"). 228Since modprobe already knows about most modules, the minimal configuration 229file could look something like this: 230 231 alias scsi_hostadapter aha1542 # or whatever SCSI adapter you have 232 alias eth0 3c509 # or whatever net adapter you have 233 # you might need an "options" line for some net adapters: 234 options 3c509 io=0x300 irq=10 235 # you might also need an "options" line for some other module: 236 options cdu31a cdu31a_port=0x1f88 sony_pas_init=1 237 238You could add these lines as well, but they are only "cosmetic": 239 240 alias net-pf-3 off # no ax25 module available (yet) 241 alias net-pf-4 off # if you don't use the ipx module 242 alias net-pf-5 off # if you don't use the appletalk module 243 244 245Written by: 246 Jacques Gelinas <jacques@solucorp.qc.ca> 247 Bjorn Ekwall <bj0rn@blox.se> 248