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