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