155 lines
6.6 KiB
ReStructuredText
155 lines
6.6 KiB
ReStructuredText
=================
|
|
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
|
|
|