Documentation/modules.txt

   1 This file describes the strategy for dynamically loadable modules
   2 in the Linux kernel. This is not a technical description on
   3 the internals of module, but mostly a sample of how to compile
   4 and use modules.
   5
   6 Note: You should ensure that the modutils-X.Y.Z.tar.gz you are using
   7 is the most up to date one for this kernel. The "X.Y.Z" will reflect
   8 the kernel version at the time of the release of the modules package.
   9 Some older modules packages aren't aware of some of the newer modular
  10 features that the kernel now supports.  The current required version
  11 is listed in the file linux/Documentation/Changes.
  12
  13 * * * NOTE * * *
  14 The kernel has been changed to remove kerneld support and use
  15 the new kmod support.  Keep this in mind when reading this file.  Kmod
  16 does the exact same thing as kerneld, but doesn't require an external
  17 program (see Documentation/kmod.txt)
  18
  19 In the beginning...
  20 -------------------
  21
  22 Anyway, your first step is to compile the kernel, as explained in the
  23 file linux/README.  It generally goes like:
  24
  25         make config
  26         make dep
  27         make clean
  28         make zImage or make zlilo
  29
  30 In "make config", you select what you want to include in the "resident"
  31 kernel and what features you want to have available as loadable modules.
  32 You 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
  42 The set of modules is constantly increasing, and you will be able to select
  43 the option "m" in "make config" for those features that the current kernel
  44 can offer as loadable modules.
  45
  46 You also have a possibility to create modules that are less dependent on
  47 the kernel version.  This option can be selected during "make config", by
  48 enabling CONFIG_MODVERSIONS, and is most useful on "stable" kernel versions,
  49 such as the kernels from the 1.2 and 2.0 series.
  50 If you have modules that are based on sources that are not included in
  51 the official kernel sources, you will certainly like this option...
  52
  53 Here 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
  83 When you have made the kernel, you create the modules by doing:
  84
  85         make modules
  86
  87 This will compile all modules and update the linux/modules directory.
  88 In this directory you will then find a bunch of symbolic links,
  89 pointing to the various object files in the kernel tree.
  90 Now, after you have created all your modules, you should also do:
  91
  92         make modules_install
  93
  94 This will copy all newly made modules into subdirectories under
  95 "/lib/modules/kernel_release/", where "kernel_release" is something
  96 like 2.0.1, or whatever the current kernel version is...
  97
  98 As soon as you have rebooted the newly made kernel, you can install
  99 and remove modules at will with the utilities: "insmod" and "rmmod".
 100 After reading the man-page for insmod, you will also know how easy
 101 it is to configure a module when you do "insmod" (hint: symbol=value).
 102
 103
 104 Nifty features:
 105 ---------------
 106
 107 You also have access to two utilities: "modprobe" and "depmod", where
 108 modprobe is a "wrapper" for (or extension to) "insmod".
 109 These utilities use (and maintain) a set of files that describe all the
 110 modules that are available for the current kernel in the /lib/modules
 111 hierarchy as well as their interdependencies.
 112
 113 Using the modprobe utility, you can load any module like this:
 114
 115         /sbin/modprobe module
 116
 117 without paying much attention to which kernel you are running, or what
 118 other modules this module depends on.
 119
 120 With the help of the modprobe configuration file: "/etc/modules.conf"
 121 you can tune the behaviour of modprobe in many ways, including an
 122 automatic setting of insmod options for each module.
 123 And, yes, there _are_ man-pages for all this...
 124
 125 To use modprobe successfully, you generally place the following
 126 command 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
 131 This computes the dependencies between the different modules.
 132 Then if you do, for example
 133
 134         /sbin/modprobe umsdos
 135
 136 you will automatically load _both_ the msdos and umsdos modules,
 137 since umsdos runs piggyback on msdos.
 138
 139
 140 Using modinfo:
 141 --------------
 142
 143 Sometimes you need to know what parameters are accepted by a
 144 module or you've found a bug and want to contact the maintainer.
 145 Then modinfo comes in very handy.
 146
 147 Every module (normally) contains the author/maintainer,
 148 a description and a list of parameters.
 149
 150 For example "modinfo -a eepro100" will return:
 151
 152         Maintainer: Andrey V. Savochkin <saw@saw.sw.com.sg>
 153
 154 and "modinfo -d eepro100" will return a description:
 155
 156         Intel i82557/i82558 PCI EtherExpressPro driver
 157
 158 and 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
 173 The "ultimate" utility:
 174 -----------------------
 175
 176 OK, you have read all of the above, and feel amply impressed...
 177 Now, we tell you to forget all about how to install and remove
 178 loadable modules...
 179 With the kerneld daemon, all of these chores will be taken care of
 180 automatically.  Just answer "Y" to CONFIG_KERNELD in "make config",
 181 and make sure that /sbin/kerneld is started as soon as possible
 182 after boot and that "/sbin/depmod -a" has been executed for the
 183 current kernel. (Read more about this in the module utilities package.)
 184
 185 Whenever a program wants the kernel to use a feature that is only
 186 available as a loadable module, and if the kernel hasn't got the
 187 module installed yet, the kernel will ask the kerneld daemon to take
 188 care of the situation and make the best of it.
 189
 190 This 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
 209 The icing of the cake is that when an automatically installed module
 210 has been unused for a period of time (usually 1 minute), the module
 211 will be automatically removed from the kernel as well.
 212
 213 This makes the kernel use the minimal amount of memory at any given time,
 214 making it available for more productive use than as just a placeholder for
 215 unused code.
 216
 217 Actually, this is only a side-effect from the _real_ benefit of kerneld:
 218 You only have to create a minimal kernel, that is more or less independent
 219 of the actual hardware setup.  The setup of the "virtual" kernel is
 220 instead controlled by a configuration file as well as the actual usage
 221 pattern of the current machine and its kernel.
 222 This should be good news for maintainers of multiple machines as well as
 223 for maintainers of distributions.
 224
 225 To use kerneld with the least amount of "hassle", you need modprobe from
 226 a release that can be considered "recent" w.r.t. your kernel, and also
 227 a configuration file for modprobe ("/etc/modules.conf").
 228 Since modprobe already knows about most modules, the minimal configuration
 229 file 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
 238 You 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
 245 Written by:
 246         Jacques Gelinas <jacques@solucorp.qc.ca>
 247         Bjorn Ekwall <bj0rn@blox.se>