diff options
Diffstat (limited to 'Documentation/kbuild')
| -rw-r--r-- | Documentation/kbuild/makefiles.rst | 5 | ||||
| -rw-r--r-- | Documentation/kbuild/modules.rst | 7 | ||||
| -rw-r--r-- | Documentation/kbuild/namespaces.rst | 154 | ||||
| -rw-r--r-- | Documentation/kbuild/reproducible-builds.rst | 13 |
4 files changed, 13 insertions, 166 deletions
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 6ba9d5365ff3..b89c88168d6a 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -954,11 +954,6 @@ When kbuild executes, the following steps are followed (roughly): From commandline LDFLAGS_MODULE shall be used (see kbuild.txt). - KBUILD_ARFLAGS Options for $(AR) when creating archives - - $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic - mode) if this option is supported by $(AR). - KBUILD_LDS The linker script with full path. Assigned by the top-level Makefile. diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst index d2ae799237fd..774a998dcf37 100644 --- a/Documentation/kbuild/modules.rst +++ b/Documentation/kbuild/modules.rst @@ -498,10 +498,11 @@ build. will be written containing all exported symbols that were not defined in the kernel. ---- 6.3 Symbols From Another External Module +6.3 Symbols From Another External Module +---------------------------------------- Sometimes, an external module uses exported symbols from - another external module. kbuild needs to have full knowledge of + another external module. Kbuild needs to have full knowledge of all symbols to avoid spitting out warnings about undefined symbols. Three solutions exist for this situation. @@ -521,7 +522,7 @@ build. The top-level kbuild file would then look like:: #./Kbuild (or ./Makefile): - obj-y := foo/ bar/ + obj-m := foo/ bar/ And executing:: diff --git a/Documentation/kbuild/namespaces.rst b/Documentation/kbuild/namespaces.rst deleted file mode 100644 index 982ed7b568ac..000000000000 --- a/Documentation/kbuild/namespaces.rst +++ /dev/null @@ -1,154 +0,0 @@ -================= -Symbol Namespaces -================= - -The following document describes how to use Symbol Namespaces to structure the -export surface of in-kernel symbols exported through the family of -EXPORT_SYMBOL() macros. - -.. Table of Contents - - === 1 Introduction - === 2 How to define Symbol Namespaces - --- 2.1 Using the EXPORT_SYMBOL macros - --- 2.2 Using the DEFAULT_SYMBOL_NAMESPACE define - === 3 How to use Symbols exported in Namespaces - === 4 Loading Modules that use namespaced Symbols - === 5 Automatically creating MODULE_IMPORT_NS statements - -1. Introduction -=============== - -Symbol Namespaces have been introduced as a means to structure the export -surface of the in-kernel API. It allows subsystem maintainers to partition -their exported symbols into separate namespaces. That is useful for -documentation purposes (think of the SUBSYSTEM_DEBUG namespace) as well as for -limiting the availability of a set of symbols for use in other parts of the -kernel. As of today, modules that make use of symbols exported into namespaces, -are required to import the namespace. Otherwise the kernel will, depending on -its configuration, reject loading the module or warn about a missing import. - -2. How to define Symbol Namespaces -================================== - -Symbols can be exported into namespace using different methods. All of them are -changing the way EXPORT_SYMBOL and friends are instrumented to create ksymtab -entries. - -2.1 Using the EXPORT_SYMBOL macros -================================== - -In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow -exporting of kernel symbols to the kernel symbol table, variants of these are -available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and -EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace. -Please note that due to macro expansion that argument needs to be a -preprocessor symbol. E.g. to export the symbol `usb_stor_suspend` into the -namespace `USB_STORAGE`, use:: - - EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE); - -The corresponding ksymtab entry struct `kernel_symbol` will have the member -`namespace` set accordingly. A symbol that is exported without a namespace will -refer to `NULL`. There is no default namespace if none is defined. `modpost` -and kernel/module.c make use the namespace at build time or module load time, -respectively. - -2.2 Using the DEFAULT_SYMBOL_NAMESPACE define -============================================= - -Defining namespaces for all symbols of a subsystem can be very verbose and may -become hard to maintain. Therefore a default define (DEFAULT_SYMBOL_NAMESPACE) -is been provided, that, if set, will become the default for all EXPORT_SYMBOL() -and EXPORT_SYMBOL_GPL() macro expansions that do not specify a namespace. - -There are multiple ways of specifying this define and it depends on the -subsystem and the maintainer's preference, which one to use. The first option -is to define the default namespace in the `Makefile` of the subsystem. E.g. to -export all symbols defined in usb-common into the namespace USB_COMMON, add a -line like this to drivers/usb/common/Makefile:: - - ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE=USB_COMMON - -That will affect all EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL() statements. A -symbol exported with EXPORT_SYMBOL_NS() while this definition is present, will -still be exported into the namespace that is passed as the namespace argument -as this argument has preference over a default symbol namespace. - -A second option to define the default namespace is directly in the compilation -unit as preprocessor statement. The above example would then read:: - - #undef DEFAULT_SYMBOL_NAMESPACE - #define DEFAULT_SYMBOL_NAMESPACE USB_COMMON - -within the corresponding compilation unit before any EXPORT_SYMBOL macro is -used. - -3. How to use Symbols exported in Namespaces -============================================ - -In order to use symbols that are exported into namespaces, kernel modules need -to explicitly import these namespaces. Otherwise the kernel might reject to -load the module. The module code is required to use the macro MODULE_IMPORT_NS -for the namespaces it uses symbols from. E.g. a module using the -usb_stor_suspend symbol from above, needs to import the namespace USB_STORAGE -using a statement like:: - - MODULE_IMPORT_NS(USB_STORAGE); - -This will create a `modinfo` tag in the module for each imported namespace. -This has the side effect, that the imported namespaces of a module can be -inspected with modinfo:: - - $ modinfo drivers/usb/storage/ums-karma.ko - [...] - import_ns: USB_STORAGE - [...] - - -It is advisable to add the MODULE_IMPORT_NS() statement close to other module -metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE(). Refer to section -5. for a way to create missing import statements automatically. - -4. Loading Modules that use namespaced Symbols -============================================== - -At module loading time (e.g. `insmod`), the kernel will check each symbol -referenced from the module for its availability and whether the namespace it -might be exported to has been imported by the module. The default behaviour of -the kernel is to reject loading modules that don't specify sufficient imports. -An error will be logged and loading will be failed with EINVAL. In order to -allow loading of modules that don't satisfy this precondition, a configuration -option is available: Setting MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y will -enable loading regardless, but will emit a warning. - -5. Automatically creating MODULE_IMPORT_NS statements -===================================================== - -Missing namespaces imports can easily be detected at build time. In fact, -modpost will emit a warning if a module uses a symbol from a namespace -without importing it. -MODULE_IMPORT_NS() statements will usually be added at a definite location -(along with other module meta data). To make the life of module authors (and -subsystem maintainers) easier, a script and make target is available to fixup -missing imports. Fixing missing imports can be done with:: - - $ make nsdeps - -A typical scenario for module authors would be:: - - - write code that depends on a symbol from a not imported namespace - - `make` - - notice the warning of modpost telling about a missing import - - run `make nsdeps` to add the import to the correct code location - -For subsystem maintainers introducing a namespace, the steps are very similar. -Again, `make nsdeps` will eventually add the missing namespace imports for -in-tree modules:: - - - move or add symbols to a namespace (e.g. with EXPORT_SYMBOL_NS()) - - `make` (preferably with an allmodconfig to cover all in-kernel - modules) - - notice the warning of modpost telling about a missing import - - run `make nsdeps` to add the import to the correct code location - diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst index ab92e98c89c8..503393854e2e 100644 --- a/Documentation/kbuild/reproducible-builds.rst +++ b/Documentation/kbuild/reproducible-builds.rst @@ -16,16 +16,21 @@ the kernel may be unreproducible, and how to avoid them. Timestamps ---------- -The kernel embeds a timestamp in two places: +The kernel embeds timestamps in three places: * The version string exposed by ``uname()`` and included in ``/proc/version`` * File timestamps in the embedded initramfs -By default the timestamp is the current time. This must be overridden -using the `KBUILD_BUILD_TIMESTAMP`_ variable. If you are building -from a git commit, you could use its commit date. +* If enabled via ``CONFIG_IKHEADERS``, file timestamps of kernel + headers embedded in the kernel or respective module, + exposed via ``/sys/kernel/kheaders.tar.xz`` + +By default the timestamp is the current time and in the case of +``kheaders`` the various files' modification times. This must +be overridden using the `KBUILD_BUILD_TIMESTAMP`_ variable. +If you are building from a git commit, you could use its commit date. The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, and enables warnings if they are used. If you incorporate external |