Merge master.kernel.org:/home/rmk/linux-2.6-arm

[linux-2.6] / Documentation / kbuild / modules.txt

diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt
index 87d858df4e3479bfd85b0be27f1f4b5c73a8c78a..fcccf2432f98ff48d8d87b040c92e9ab5a8ef01a 100644 (file)
--- a/Documentation/kbuild/modules.txt
+++ b/Documentation/kbuild/modules.txt
@@ -23,7 +23,10 @@ In this document you will find information about:
        === 6. Module installation
           --- 6.1 INSTALL_MOD_PATH
           --- 6.2 INSTALL_MOD_DIR
-       === 7. Module versioning
+       === 7. Module versioning & Module.symvers
+          --- 7.1 Symbols fron the kernel (vmlinux + modules)
+          --- 7.2 Symbols and external modules
+          --- 7.3 Symbols from another external module
        === 8. Tips & Tricks
           --- 8.1 Testing for CONFIG_FOO_BAR
 
@@ -89,7 +92,8 @@ when building an external module.
        make -C $KDIR M=$PWD modules_install
                Install the external module(s).
                Installation default is in /lib/modules/<kernel-version>/extra,
-               but may be prefixed with INSTALL_MOD_PATH - see separate chapter.
+               but may be prefixed with INSTALL_MOD_PATH - see separate
+               chapter.
 
        make -C $KDIR M=$PWD clean
                Remove all generated files for the module - the kernel
@@ -433,7 +437,7 @@ External modules are installed in the directory:
                => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf
 
 
-=== 7. Module versioning
+=== 7. Module versioning & Module.symvers
 
 Module versioning is enabled by the CONFIG_MODVERSIONS tag.
 
@@ -443,11 +447,80 @@ when a module is loaded/used then the CRC values contained in the kernel are
 compared with similar values in the module. If they are not equal then the
 kernel refuses to load the module.
 
-During a kernel build a file named Module.symvers will be generated. This
-file includes the symbol version of all symbols within the kernel. If the 
-Module.symvers file is saved from the last full kernel compile one does not
-have to do a full kernel compile to build a module version's compatible module.
+Module.symvers contains a list of all exported symbols from a kernel build.
 
+--- 7.1 Symbols fron the kernel (vmlinux + modules)
+
+       During a kernel build a file named Module.symvers will be generated.
+       Module.symvers contains all exported symbols from the kernel and
+       compiled modules. For each symbols the corresponding CRC value
+       is stored too.
+
+       The syntax of the Module.symvers file is:
+               <CRC>       <Symbol>           <module>
+       Sample:
+               0x2d036834  scsi_remove_host   drivers/scsi/scsi_mod
+
+       For a kernel build without CONFIG_MODVERSIONING enabled the crc
+       would read: 0x00000000
+
+       Module.symvers serve two purposes.
+       1) It list all exported symbols both from vmlinux and all modules
+       2) It list CRC if CONFIG_MODVERSION is enabled
+
+--- 7.2 Symbols and external modules
+
+       When building an external module the build system needs access to
+       the symbols from the kernel to check if all external symbols are
+       defined. This is done in the MODPOST step and to obtain all
+       symbols modpost reads Module.symvers from the kernel.
+       If a Module.symvers file is present in the directory where
+       the external module is being build this file will be read too.
+       During the MODPOST step a new Module.symvers file will be written
+       containing all exported symbols that was not defined in the kernel.
+       
+--- 7.3 Symbols from another external module
+
+       Sometimes one external module uses exported symbols from another
+       external module. Kbuild needs to have full knowledge on all symbols
+       to avoid spitting out warnings about undefined symbols.
+       Two solutions exist to let kbuild know all symbols of more than
+       one external module.
+       The method with a top-level kbuild file is recommended but may be
+       impractical in certain situations.
+
+       Use a top-level Kbuild file
+               If you have two modules: 'foo', 'bar' and 'foo' needs symbols
+               from 'bar' then one can use a common top-level kbuild file so
+               both modules are compiled in same build.
+
+               Consider following directory layout:
+               ./foo/ <= contains the foo module
+               ./bar/ <= contains the bar module
+               The top-level Kbuild file would then look like:
+               
+               #./Kbuild: (this file may also be named Makefile)
+                       obj-y := foo/ bar/
+
+               Executing:
+                       make -C $KDIR M=`pwd`
+
+               will then do the expected and compile both modules with full
+               knowledge on symbols from both modules.
+
+       Use an extra Module.symvers file
+               When an external module is build a Module.symvers file is
+               generated containing all exported symbols which are not
+               defined in the kernel.
+               To get access to symbols from module 'bar' one can copy the
+               Module.symvers file from the compilation of the 'bar' module
+               to the directory where the 'foo' module is build.
+               During the module build kbuild will read the Module.symvers
+               file in the directory of the external module and when the
+               build is finished a new Module.symvers file is created
+               containing the sum of all symbols defined and not part of the
+               kernel.
+               
 === 8. Tips & Tricks
 
 --- 8.1 Testing for CONFIG_FOO_BAR