| 1 | =================
|
| 2 | Symbol Namespaces
|
| 3 | =================
|
| 4 |
|
| 5 | The following document describes how to use Symbol Namespaces to structure the
|
| 6 | export surface of in-kernel symbols exported through the family of
|
| 7 | EXPORT_SYMBOL() macros.
|
| 8 |
|
| 9 | Introduction
|
| 10 | ============
|
| 11 |
|
| 12 | Symbol Namespaces have been introduced as a means to structure the export
|
| 13 | surface of the in-kernel API. It allows subsystem maintainers to partition
|
| 14 | their exported symbols into separate namespaces. That is useful for
|
| 15 | documentation purposes (think of the SUBSYSTEM_DEBUG namespace) as well as for
|
| 16 | limiting the availability of a set of symbols for use in other parts of the
|
| 17 | kernel. As of today, modules that make use of symbols exported into namespaces,
|
| 18 | are required to import the namespace. Otherwise the kernel will, depending on
|
| 19 | its configuration, reject loading the module or warn about a missing import.
|
| 20 |
|
| 21 | Additionally, it is possible to put symbols into a module namespace, strictly
|
| 22 | limiting which modules are allowed to use these symbols.
|
| 23 |
|
| 24 | How to define Symbol Namespaces
|
| 25 | ===============================
|
| 26 |
|
| 27 | Symbols can be exported into namespace using different methods. All of them are
|
| 28 | changing the way EXPORT_SYMBOL and friends are instrumented to create ksymtab
|
| 29 | entries.
|
| 30 |
|
| 31 | Using the EXPORT_SYMBOL macros
|
| 32 | ------------------------------
|
| 33 |
|
| 34 | In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow
|
| 35 | exporting of kernel symbols to the kernel symbol table, variants of these are
|
| 36 | available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and
|
| 37 | EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a
|
| 38 | string constant. Note that this string must not contain whitespaces.
|
| 39 | E.g. to export the symbol ``usb_stor_suspend`` into the
|
| 40 | namespace ``USB_STORAGE``, use::
|
| 41 |
|
| 42 | EXPORT_SYMBOL_NS(usb_stor_suspend, "USB_STORAGE");
|
| 43 |
|
| 44 | The corresponding ksymtab entry struct ``kernel_symbol`` will have the member
|
| 45 | ``namespace`` set accordingly. A symbol that is exported without a namespace will
|
| 46 | refer to ``NULL``. There is no default namespace if none is defined. ``modpost``
|
| 47 | and kernel/module/main.c make use the namespace at build time or module load
|
| 48 | time, respectively.
|
| 49 |
|
| 50 | Using the DEFAULT_SYMBOL_NAMESPACE define
|
| 51 | -----------------------------------------
|
| 52 |
|
| 53 | Defining namespaces for all symbols of a subsystem can be very verbose and may
|
| 54 | become hard to maintain. Therefore a default define (DEFAULT_SYMBOL_NAMESPACE)
|
| 55 | is been provided, that, if set, will become the default for all EXPORT_SYMBOL()
|
| 56 | and EXPORT_SYMBOL_GPL() macro expansions that do not specify a namespace.
|
| 57 |
|
| 58 | There are multiple ways of specifying this define and it depends on the
|
| 59 | subsystem and the maintainer's preference, which one to use. The first option
|
| 60 | is to define the default namespace in the ``Makefile`` of the subsystem. E.g. to
|
| 61 | export all symbols defined in usb-common into the namespace USB_COMMON, add a
|
| 62 | line like this to drivers/usb/common/Makefile::
|
| 63 |
|
| 64 | ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE='"USB_COMMON"'
|
| 65 |
|
| 66 | That will affect all EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL() statements. A
|
| 67 | symbol exported with EXPORT_SYMBOL_NS() while this definition is present, will
|
| 68 | still be exported into the namespace that is passed as the namespace argument
|
| 69 | as this argument has preference over a default symbol namespace.
|
| 70 |
|
| 71 | A second option to define the default namespace is directly in the compilation
|
| 72 | unit as preprocessor statement. The above example would then read::
|
| 73 |
|
| 74 | #define DEFAULT_SYMBOL_NAMESPACE "USB_COMMON"
|
| 75 |
|
| 76 | within the corresponding compilation unit before the #include for
|
| 77 | <linux/export.h>. Typically it's placed before the first #include statement.
|
| 78 |
|
| 79 | Using the EXPORT_SYMBOL_FOR_MODULES() macro
|
| 80 | -------------------------------------------
|
| 81 |
|
| 82 | Symbols exported using this macro are put into a module namespace. This
|
| 83 | namespace cannot be imported. These exports are GPL-only as they are only
|
| 84 | intended for in-tree modules.
|
| 85 |
|
| 86 | The macro takes a comma separated list of module names, allowing only those
|
| 87 | modules to access this symbol. Simple tail-globs are supported.
|
| 88 |
|
| 89 | For example::
|
| 90 |
|
| 91 | EXPORT_SYMBOL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-*")
|
| 92 |
|
| 93 | will limit usage of this symbol to modules whose name matches the given
|
| 94 | patterns.
|
| 95 |
|
| 96 | How to use Symbols exported in Namespaces
|
| 97 | =========================================
|
| 98 |
|
| 99 | In order to use symbols that are exported into namespaces, kernel modules need
|
| 100 | to explicitly import these namespaces. Otherwise the kernel might reject to
|
| 101 | load the module. The module code is required to use the macro MODULE_IMPORT_NS
|
| 102 | for the namespaces it uses symbols from. E.g. a module using the
|
| 103 | usb_stor_suspend symbol from above, needs to import the namespace USB_STORAGE
|
| 104 | using a statement like::
|
| 105 |
|
| 106 | MODULE_IMPORT_NS("USB_STORAGE");
|
| 107 |
|
| 108 | This will create a ``modinfo`` tag in the module for each imported namespace.
|
| 109 | This has the side effect, that the imported namespaces of a module can be
|
| 110 | inspected with modinfo::
|
| 111 |
|
| 112 | $ modinfo drivers/usb/storage/ums-karma.ko
|
| 113 | [...]
|
| 114 | import_ns: USB_STORAGE
|
| 115 | [...]
|
| 116 |
|
| 117 | For modules that are currently loaded, imported namespaces are also available
|
| 118 | via sysfs::
|
| 119 |
|
| 120 | $ cat /sys/module/ums_karma/import_ns
|
| 121 | USB_STORAGE
|
| 122 |
|
| 123 | It is advisable to add the MODULE_IMPORT_NS() statement close to other module
|
| 124 | metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE().
|
| 125 |
|
| 126 | Loading Modules that use namespaced Symbols
|
| 127 | ===========================================
|
| 128 |
|
| 129 | At module loading time (e.g. ``insmod``), the kernel will check each symbol
|
| 130 | referenced from the module for its availability and whether the namespace it
|
| 131 | might be exported to has been imported by the module. The default behaviour of
|
| 132 | the kernel is to reject loading modules that don't specify sufficient imports.
|
| 133 | An error will be logged and loading will be failed with EINVAL. In order to
|
| 134 | allow loading of modules that don't satisfy this precondition, a configuration
|
| 135 | option is available: Setting MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y will
|
| 136 | enable loading regardless, but will emit a warning.
|
| 137 |
|
| 138 | Automatically creating MODULE_IMPORT_NS statements
|
| 139 | ==================================================
|
| 140 |
|
| 141 | Missing namespaces imports can easily be detected at build time. In fact,
|
| 142 | modpost will emit a warning if a module uses a symbol from a namespace
|
| 143 | without importing it.
|
| 144 | MODULE_IMPORT_NS() statements will usually be added at a definite location
|
| 145 | (along with other module meta data). To make the life of module authors (and
|
| 146 | subsystem maintainers) easier, a script and make target is available to fixup
|
| 147 | missing imports. Fixing missing imports can be done with::
|
| 148 |
|
| 149 | $ make nsdeps
|
| 150 |
|
| 151 | A typical scenario for module authors would be::
|
| 152 |
|
| 153 | - write code that depends on a symbol from a not imported namespace
|
| 154 | - ``make``
|
| 155 | - notice the warning of modpost telling about a missing import
|
| 156 | - run ``make nsdeps`` to add the import to the correct code location
|
| 157 |
|
| 158 | For subsystem maintainers introducing a namespace, the steps are very similar.
|
| 159 | Again, ``make nsdeps`` will eventually add the missing namespace imports for
|
| 160 | in-tree modules::
|
| 161 |
|
| 162 | - move or add symbols to a namespace (e.g. with EXPORT_SYMBOL_NS())
|
| 163 | - ``make`` (preferably with an allmodconfig to cover all in-kernel
|
| 164 | modules)
|
| 165 | - notice the warning of modpost telling about a missing import
|
| 166 | - run ``make nsdeps`` to add the import to the correct code location
|
| 167 |
|
| 168 | You can also run nsdeps for external module builds. A typical usage is::
|
| 169 |
|
| 170 | $ make -C <path_to_kernel_src> M=$PWD nsdeps
|
| 171 |
|
| 172 | Note: it will happily generate an import statement for the module namespace;
|
| 173 | which will not work and generates build and runtime failures.
|