diff options
| author | Jon Masters <jcm@jonmasters.org> | 2010-03-02 05:29:14 -0500 |
|---|---|---|
| committer | Jon Masters <jcm@jonmasters.org> | 2010-03-02 05:29:14 -0500 |
| commit | ea2b03bd564e01f2a51091a4302933a3e7589e44 (patch) | |
| tree | 77a363d41aa0bf7a32243f13ee90e302dad4c3c3 | |
| parent | bd9064ed4ad51d5c107843b0ebc07a5593204de2 (diff) | |
| download | module-init-tools-ea2b03bd564e01f2a51091a4302933a3e7589e44.tar.gz | |
doc: Further documentation updates and rewrites
The documentation has been sadly lacking. Fortunately, there is a new
wiki and some great plans for content on module design/implementation.
Until that is all done, at least get these docs in better shape.
Signed-off-by: Jon Masters <jcm@jonmasters.org>
| -rw-r--r-- | AUTHORS | 20 | ||||
| -rw-r--r-- | CODING | 24 | ||||
| -rw-r--r-- | FAQ | 27 | ||||
| -rw-r--r-- | HACKING | 13 | ||||
| -rw-r--r-- | NEWS | 15 | ||||
| -rw-r--r-- | README | 94 | ||||
| -rw-r--r-- | TODO | 5 |
7 files changed, 123 insertions, 75 deletions
@@ -1,8 +1,12 @@ -Adam J. Richter <adam@yggdrasil.com> -Alan Jenkins <alan-jenkins@tuffmail.co.uk> -Jon Masters <jcm@jonmasters.org> -Kay Sievers <kay.sievers@vrfy.org> -Marco d'Itri <md@linux.it> -Michal Marek <mmarek@suse.cz> -Robby Workman <rworkman@slackware.com> -Rusty Russell <rusty@rustcorp.com.au> +Maintainer: + Jon Masters <jcm@jonmasters.org> + +Many thanks to: + Adam J. Richter <adam@yggdrasil.com> + Alan Jenkins <alan-jenkins@tuffmail.co.uk> + Jon Masters <jcm@jonmasters.org> + Kay Sievers <kay.sievers@vrfy.org> + Marco d'Itri <md@linux.it> + Michal Marek <mmarek@suse.cz> + Robby Workman <rworkman@slackware.com> + Rusty Russell <rusty@rustcorp.com.au> @@ -1,3 +1,6 @@ +module-init-tools coding standards +---------------------------------- + Patches to module-init-tools are welcome. Please note the following design goals: @@ -5,26 +8,21 @@ design goals: 2) modprobe is designed to be a swiss-army-knife, but the config file format is designed to be as simple as possible: let the user create - complexity if they wish. + complexity if they wish. Having said that, the "install" and "remove" + commands serve as examples of what we don't want to do in the future, + due to the problems they cause with identifying module dependencies. 3) module-init-tools contains a testsuite. Patches which do not pass - the testsuite get a frowny face. - -New tests ---------- - -The following tests have been recently added: - - * Binary trie tests (test-modprobe-indexed) + the testsuite get a frowny face. It's easy to run the testsuite, + as you can see below. Please do test patches before posting. The testsuite ------------- -The testsuite is under tests/test-*: one directory for each tool. You -can run "make check" to run the testsuite: it will use valgrind (much -slower, but catches more things) if it is installed. +The testsuite is under tests/test-*: one directory for each tool. To +run the testsuite, type the following from the top level directory: -"make check" simply invokes "./tests/runtests". + ./tests/runtests To start the tests at a particular test, use that test name on the command line, eg. "./tests/runtests 26blacklist.sh". To see exactly @@ -1,28 +1,13 @@ Frequently Asked Module User Questions +-------------------------------------- + +Q) Where should I report bugs? +A) Please post to the linux-modules@vger.kernel.org mailing list, along with + a description of how to reproduce. Copy Jon Masters <jcm@jonmasters.org>. Q) I get "/usr/bin/ld: cannot find -lc" A) You need to install a development package which contains libc.a. - -Q) I'm using RedHat and modules don't autoload any more. -A) Old versions of RedHat turns module autoloading off if /proc/ksyms - isn't found. Change line 337 of /etc/rc.d/rc.sysinit from: - - if ! grep -iq nomodules /proc/cmdline 2>/dev/null && [ -f /proc/ksyms ]; then - - to - - if ! grep -iq nomodules /proc/cmdline 2>/dev/null && [ -f /proc/modules ]; then - -Q) Sound doesn't load automatically. -A) You need to set up an alias (or install command) for "sound-slot-0" in - /etc/modprobe.d/sound.conf: the ALSA sound system sometimes wants this. - -Q) What is "[unsafe]" next to the module name in lsmod? -A) It means someone used an old-style interfaces to try to control this - module: these are slowly being tracked down and eliminated. You can - use "rmmod -f" to force removal if you configured your kernel with - CONFIG_MODULE_FORCE_UNLOAD set. + For example, on Fedora systems, you would type "yum install glibc-static". Q) I'm having trouble inserting out-of-tree modules A) See kernel source tree documentation: Documentation/kbuild/modules.txt - @@ -11,6 +11,8 @@ substantial over time. Development is preferably done via git merges. automake --add-missing --copy autoconf + You can also run "autoreconf -i" to perform these three stages. + * Regression tests can be run as follows (try --help for more details): tests/runtests @@ -19,9 +21,12 @@ substantial over time. Development is preferably done via git merges. Prior to a new release: - Update configure.ac with new version - prune git tree/commit with new version in configure.ac - prep tree for tarball - push to kerneltools.org (along with GPG signed ASC signature) + Update configure.ac with new version + commit git tree to appropriate branch (dev/master/topic) + perform a final tests/runtests on the tree + push tree up to git.kernel.org + prep tree for tarball (git archive) + sign tree with GPG and save signature + push archive up to kernel.org Jon Masters <jcm@jonmasters.org> @@ -1,16 +1,5 @@ NEWS for module-init-tools -------------------------- -generate-modules.conf is now deprecated, as the old modutils is no longer - supported at all. As such, this file is no longer installed by default - (it will have to be manually installed if you need it), and all packages - should be migrated away from needing it as soon as possible. - -* New mailing list: linux-modules@vger.kernel.org -* Release 3.8 was ?? -* Release 3.7 was ?? -* Release 3.6 was a regular maintenance release. -* Release 3.5 included a lot of cleanups, new module indexing - -Please send patches (or preferably git pull requests) to: - Jon Masters <jcm@jonmasters.org> +2010-03-01 - New wiki created (http://modules.wiki.kernel.org/). Please + help to add documentation to aid other developers. @@ -1,22 +1,84 @@ -PLEASE READ INSTRUCTIONS CAREFULLY. -THERE IS NO BACKWARDS COMPATABILITY FOR PRE-2.6 KERNELS! +module-init-tools - Linux userspace module loading utilities +------------------------------------------------------------ -1a) If you want to install in /sbin: - ./configure --prefix= --mandir=/usr/share/man +Handy Resources: + - Bugs: Please send email to list + - Git: git://git.kernel.org/pub/scm/utils/kernel/module-init-tools/module-init-tools.git + - IRC: irc.freenode.org/#module-init-tools + - Mail: linux-modules@vger.kernel.org + - Web: http://modules.wiki.kernel.org/ -1b) If you want to install in /usr/local/sbin: - ./configure +The module-init-tools are used by modern 2.6 series Linux systems to provide +userspace-side assistance in loading kernel modules and their dependencies. +Originally written to replace the older "modutils", the utilities include +the "modprobe" (load modules and their dependencies), "insmod" (load just +a single module), "modinfo" (retrieve module information), and other related +module management commands. These are intended to be relatively lightweight +in their design, since 2.6 series kernels do much of the work internally. -2) Now, build it: - make - make install +You will find documentation within the man pages and in this README file, +as well as some hints on development within the HACKING file. You are +encouraged to get involved by signing up to the linux-modules@vger.kernel.org +project mailing list, and posting patches (git pull requests are welcome). +You can also find further information, including the address of the mailing +list, this git repository, and so forth on the module-init-tools wiki. -3) You will need to run "depmod" for your new kernel, eg: - depmod 2.6.29 +Development takes place against the latest upstream Linux kernels (2.6.33 +as of this writing, though kernel development moves quickly). Backward +compatibility is generally attempted, but forward compatibility (i.e. the +ability for a specific release of module-init-tools to work against data +files created by a later version as yet unreleased version) is not. In +particular, the generated data files within /lib/modules/<kernel version> +must not be assumed to have any particular format, nor should they be +parsed be any other tools. There is a specific "modinfo" utility intended +for the purposes of providing the information stored within those files. -6) If you want to hack on the source: - autoreconf -i - (or in full: aclocal -I m4 && automake --add-missing --copy && autoconf) +Recent Changes: + - There is no backwards compatibility for pre-2.6 series kernels. If + you intend to use an older kernel (wherein the module utilities + must perform various linking stages in userspace), use an older + tool such as provided in the "modutils" legacy kernel package. -If this is all too complicated, I recommend getting and installing your -distribution package or source rpm instead. + - Explicit locking of kernel modules is no longer being performed at + load time (the existing implementation required a writeable mount + in /lib/modules that is by no means assured - an alternative of + using SYSV locks was experimented with but deemed unnecessary). + The kernel will handle one modprobe instance racing with another + by denying the load and returning an error message. + +Work in progress: + - We are working on soft-dependency support that will allow modules + to provide hints as to dependencies that may not be explicit. + +Requirements: + - A 2.6 series Linux kernel with sysfs, procfs, and loadable module + support enabled in the kernel configuration. It is also required + that sysfs and procfs be mounted in their usual /proc and /sys + locations in order for certain functionality to be provided. + + - Module remove support must be enabled if removing is required. Yo + can also enable other options such as forced removal, but this is + really a bad idea for anything other than development. + + - Module versioning (MODVERSIONS) must be enabled if you would + like to try to use modules from one kernel with another, similar + one without the kernel complaining loudly at the difference. + +Quickstart: + - Make sure you have appropriate development tools (gcc, GNU autotools, + docbook2man, etc. Some distributions may require optional packages + for a static version of glibc, as an example). + + - To begin hacking on module-init-tools, you can do the following: + + 1). aclocal -I m4 && automake --add-missing --copy && autoconf + (or run "autoreconf" from an existing setup) + 2). ./configure + (optionally specify "--prefix" or "--mandir" for non /usr/local) + 3). make + 4). make install + 5). depmod + (to update /lib/modules/<kernel version> for the latest release) + +Please direct any comment/question to the linux-modules mailing list at: + linux-modules@vger.kernel.org @@ -6,8 +6,13 @@ build * Fix "make dist" to build documentation. * Fix "make distcheck" at the same time. +depmod +------ + * Kill off the "map" files. They aren't really needed any more. + modprobe -------- + * Kill off some of the legacy options. * Fix grab_elf_file_fd error handling for test-module/10alias.sh. * Enforce use of *.conf files in /etc/modprobe.d as filename extension. * Add a "depends" config file directive to obviate "install" hacks. |