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