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
312. How to define Symbol Namespaces
32==================================
33
34Symbols can be exported into namespace using different methods. All of them are
35changing the way EXPORT_SYMBOL and friends are instrumented to create ksymtab
36entries.
37
382.1 Using the EXPORT_SYMBOL macros
39==================================
40
41In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow
42exporting of kernel symbols to the kernel symbol table, variants of these are
43available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and
44EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
45Please note that due to macro expansion that argument needs to be a
46preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the
47namespace ``USB_STORAGE``, use::
48
49	EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE);
50
51The corresponding ksymtab entry struct ``kernel_symbol`` will have the member
52``namespace`` set accordingly. A symbol that is exported without a namespace will
53refer to ``NULL``. There is no default namespace if none is defined. ``modpost``
54and kernel/module/main.c make use the namespace at build time or module load
55time, respectively.
56
572.2 Using the DEFAULT_SYMBOL_NAMESPACE define
58=============================================
59
60Defining namespaces for all symbols of a subsystem can be very verbose and may
61become hard to maintain. Therefore a default define (DEFAULT_SYMBOL_NAMESPACE)
62is been provided, that, if set, will become the default for all EXPORT_SYMBOL()
63and EXPORT_SYMBOL_GPL() macro expansions that do not specify a namespace.
64
65There are multiple ways of specifying this define and it depends on the
66subsystem and the maintainer's preference, which one to use. The first option
67is to define the default namespace in the ``Makefile`` of the subsystem. E.g. to
68export all symbols defined in usb-common into the namespace USB_COMMON, add a
69line like this to drivers/usb/common/Makefile::
70
71	ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE=USB_COMMON
72
73That will affect all EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL() statements. A
74symbol exported with EXPORT_SYMBOL_NS() while this definition is present, will
75still be exported into the namespace that is passed as the namespace argument
76as this argument has preference over a default symbol namespace.
77
78A second option to define the default namespace is directly in the compilation
79unit as preprocessor statement. The above example would then read::
80
81	#undef  DEFAULT_SYMBOL_NAMESPACE
82	#define DEFAULT_SYMBOL_NAMESPACE USB_COMMON
83
84within the corresponding compilation unit before any EXPORT_SYMBOL macro is
85used.
86
873. How to use Symbols exported in Namespaces
88============================================
89
90In order to use symbols that are exported into namespaces, kernel modules need
91to explicitly import these namespaces. Otherwise the kernel might reject to
92load the module. The module code is required to use the macro MODULE_IMPORT_NS
93for the namespaces it uses symbols from. E.g. a module using the
94usb_stor_suspend symbol from above, needs to import the namespace USB_STORAGE
95using a statement like::
96
97	MODULE_IMPORT_NS(USB_STORAGE);
98
99This will create a ``modinfo`` tag in the module for each imported namespace.
100This has the side effect, that the imported namespaces of a module can be
101inspected with modinfo::
102
103	$ modinfo drivers/usb/storage/ums-karma.ko
104	[...]
105	import_ns:      USB_STORAGE
106	[...]
107
108
109It is advisable to add the MODULE_IMPORT_NS() statement close to other module
110metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE(). Refer to section
1115. for a way to create missing import statements automatically.
112
1134. Loading Modules that use namespaced Symbols
114==============================================
115
116At module loading time (e.g. ``insmod``), the kernel will check each symbol
117referenced from the module for its availability and whether the namespace it
118might be exported to has been imported by the module. The default behaviour of
119the kernel is to reject loading modules that don't specify sufficient imports.
120An error will be logged and loading will be failed with EINVAL. In order to
121allow loading of modules that don't satisfy this precondition, a configuration
122option is available: Setting MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y will
123enable loading regardless, but will emit a warning.
124
1255. Automatically creating MODULE_IMPORT_NS statements
126=====================================================
127
128Missing namespaces imports can easily be detected at build time. In fact,
129modpost will emit a warning if a module uses a symbol from a namespace
130without importing it.
131MODULE_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
133subsystem maintainers) easier, a script and make target is available to fixup
134missing imports. Fixing missing imports can be done with::
135
136	$ make nsdeps
137
138A 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
145For subsystem maintainers introducing a namespace, the steps are very similar.
146Again, ``make nsdeps`` will eventually add the missing namespace imports for
147in-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
155You can also run nsdeps for external module builds. A typical usage is::
156
157	$ make -C <path_to_kernel_src> M=$PWD nsdeps
158