From: Matthias Maennich <maennich@google.com> To: linux-kernel@vger.kernel.org Cc: kernel-team@android.com, maennich@google.com, arnd@arndb.de, gregkh@linuxfoundation.org, jeyu@kernel.org, joel@joelfernandes.org, lucas.de.marchi@gmail.com, maco@android.com, sspatil@google.com, will@kernel.org, yamada.masahiro@socionext.com, linux-kbuild@vger.kernel.org, linux-modules@vger.kernel.org, linux-usb@vger.kernel.org, usb-storage@lists.one-eyed-alien.net Subject: [PATCH v5 09/11] docs: Add documentation for Symbol Namespaces Date: Fri, 6 Sep 2019 11:32:33 +0100 Message-ID: <20190906103235.197072-10-maennich@google.com> (raw) In-Reply-To: <20190906103235.197072-1-maennich@google.com> Describe using Symbol Namespaces from a perspective of a user. I.e. module authors or subsystem maintainers. Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Matthias Maennich <maennich@google.com> --- Documentation/kbuild/namespaces.rst | 154 +++++++++++++++++++++++ Documentation/kernel-hacking/hacking.rst | 18 +++ 2 files changed, 172 insertions(+) create mode 100644 Documentation/kbuild/namespaces.rst diff --git a/Documentation/kbuild/namespaces.rst b/Documentation/kbuild/namespaces.rst new file mode 100644 index 000000000000..982ed7b568ac --- /dev/null +++ b/Documentation/kbuild/namespaces.rst @@ -0,0 +1,154 @@ +================= +Symbol Namespaces +================= + +The following document describes how to use Symbol Namespaces to structure the +export surface of in-kernel symbols exported through the family of +EXPORT_SYMBOL() macros. + +.. Table of Contents + + === 1 Introduction + === 2 How to define Symbol Namespaces + --- 2.1 Using the EXPORT_SYMBOL macros + --- 2.2 Using the DEFAULT_SYMBOL_NAMESPACE define + === 3 How to use Symbols exported in Namespaces + === 4 Loading Modules that use namespaced Symbols + === 5 Automatically creating MODULE_IMPORT_NS statements + +1. Introduction +=============== + +Symbol Namespaces have been introduced as a means to structure the export +surface of the in-kernel API. It allows subsystem maintainers to partition +their exported symbols into separate namespaces. That is useful for +documentation purposes (think of the SUBSYSTEM_DEBUG namespace) as well as for +limiting the availability of a set of symbols for use in other parts of the +kernel. As of today, modules that make use of symbols exported into namespaces, +are required to import the namespace. Otherwise the kernel will, depending on +its configuration, reject loading the module or warn about a missing import. + +2. How to define Symbol Namespaces +================================== + +Symbols can be exported into namespace using different methods. All of them are +changing the way EXPORT_SYMBOL and friends are instrumented to create ksymtab +entries. + +2.1 Using the EXPORT_SYMBOL macros +================================== + +In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow +exporting of kernel symbols to the kernel symbol table, variants of these are +available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and +EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace. +Please note that due to macro expansion that argument needs to be a +preprocessor symbol. E.g. to export the symbol `usb_stor_suspend` into the +namespace `USB_STORAGE`, use:: + + EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE); + +The corresponding ksymtab entry struct `kernel_symbol` will have the member +`namespace` set accordingly. A symbol that is exported without a namespace will +refer to `NULL`. There is no default namespace if none is defined. `modpost` +and kernel/module.c make use the namespace at build time or module load time, +respectively. + +2.2 Using the DEFAULT_SYMBOL_NAMESPACE define +============================================= + +Defining namespaces for all symbols of a subsystem can be very verbose and may +become hard to maintain. Therefore a default define (DEFAULT_SYMBOL_NAMESPACE) +is been provided, that, if set, will become the default for all EXPORT_SYMBOL() +and EXPORT_SYMBOL_GPL() macro expansions that do not specify a namespace. + +There are multiple ways of specifying this define and it depends on the +subsystem and the maintainer's preference, which one to use. The first option +is to define the default namespace in the `Makefile` of the subsystem. E.g. to +export all symbols defined in usb-common into the namespace USB_COMMON, add a +line like this to drivers/usb/common/Makefile:: + + ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE=USB_COMMON + +That will affect all EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL() statements. A +symbol exported with EXPORT_SYMBOL_NS() while this definition is present, will +still be exported into the namespace that is passed as the namespace argument +as this argument has preference over a default symbol namespace. + +A second option to define the default namespace is directly in the compilation +unit as preprocessor statement. The above example would then read:: + + #undef DEFAULT_SYMBOL_NAMESPACE + #define DEFAULT_SYMBOL_NAMESPACE USB_COMMON + +within the corresponding compilation unit before any EXPORT_SYMBOL macro is +used. + +3. How to use Symbols exported in Namespaces +============================================ + +In order to use symbols that are exported into namespaces, kernel modules need +to explicitly import these namespaces. Otherwise the kernel might reject to +load the module. The module code is required to use the macro MODULE_IMPORT_NS +for the namespaces it uses symbols from. E.g. a module using the +usb_stor_suspend symbol from above, needs to import the namespace USB_STORAGE +using a statement like:: + + MODULE_IMPORT_NS(USB_STORAGE); + +This will create a `modinfo` tag in the module for each imported namespace. +This has the side effect, that the imported namespaces of a module can be +inspected with modinfo:: + + $ modinfo drivers/usb/storage/ums-karma.ko + [...] + import_ns: USB_STORAGE + [...] + + +It is advisable to add the MODULE_IMPORT_NS() statement close to other module +metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE(). Refer to section +5. for a way to create missing import statements automatically. + +4. Loading Modules that use namespaced Symbols +============================================== + +At module loading time (e.g. `insmod`), the kernel will check each symbol +referenced from the module for its availability and whether the namespace it +might be exported to has been imported by the module. The default behaviour of +the kernel is to reject loading modules that don't specify sufficient imports. +An error will be logged and loading will be failed with EINVAL. In order to +allow loading of modules that don't satisfy this precondition, a configuration +option is available: Setting MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y will +enable loading regardless, but will emit a warning. + +5. Automatically creating MODULE_IMPORT_NS statements +===================================================== + +Missing namespaces imports can easily be detected at build time. In fact, +modpost will emit a warning if a module uses a symbol from a namespace +without importing it. +MODULE_IMPORT_NS() statements will usually be added at a definite location +(along with other module meta data). To make the life of module authors (and +subsystem maintainers) easier, a script and make target is available to fixup +missing imports. Fixing missing imports can be done with:: + + $ make nsdeps + +A typical scenario for module authors would be:: + + - write code that depends on a symbol from a not imported namespace + - `make` + - notice the warning of modpost telling about a missing import + - run `make nsdeps` to add the import to the correct code location + +For subsystem maintainers introducing a namespace, the steps are very similar. +Again, `make nsdeps` will eventually add the missing namespace imports for +in-tree modules:: + + - move or add symbols to a namespace (e.g. with EXPORT_SYMBOL_NS()) + - `make` (preferably with an allmodconfig to cover all in-kernel + modules) + - notice the warning of modpost telling about a missing import + - run `make nsdeps` to add the import to the correct code location + diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index 5891a701a159..a3ddb213a5e1 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -594,6 +594,24 @@ internal implementation issue, and not really an interface. Some maintainers and developers may however require EXPORT_SYMBOL_GPL() when adding any new APIs or functionality. +:c:func:`EXPORT_SYMBOL_NS()` +---------------------------- + +Defined in ``include/linux/export.h`` + +This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol +namespace. Symbol Namespaces are documented in +``Documentation/kbuild/namespaces.rst``. + +:c:func:`EXPORT_SYMBOL_NS_GPL()` +-------------------------------- + +Defined in ``include/linux/export.h`` + +This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol +namespace. Symbol Namespaces are documented in +``Documentation/kbuild/namespaces.rst``. + Routines and Conventions ======================== -- 2.23.0.187.g17f5b7556c-goog
next prev parent reply index Thread overview: 107+ messages / expand[flat|nested] mbox.gz Atom feed top [not found] <20180716122125.175792-1-maco@android.com> [not found] ` <20180716122125.175792-3-maco@android.com> [not found] ` <CAB0TPYEOVHcFGFLTjVvk7R0VSgSnXZRi1PjSYXONJSjqd4NewQ@mail.gmail.com> [not found] ` <20180725155507.umb5oatduquxwlmt@linux-8ccs> 2018-07-25 16:48 ` [PATCH 2/6] module: add support for symbol namespaces Lucas De Marchi 2018-07-26 7:44 ` Martijn Coenen 2019-08-13 12:16 ` [PATCH v2 0/10] Symbol namespaces - RFC Matthias Maennich 2019-08-13 12:16 ` [PATCH v2 01/10] module: support reading multiple values per modinfo tag Matthias Maennich 2019-08-13 12:40 ` Greg KH 2019-08-13 12:16 ` [PATCH v2 02/10] export: explicitly align struct kernel_symbol Matthias Maennich 2019-08-13 12:41 ` Greg KH 2019-08-13 12:17 ` [PATCH v2 03/10] module: add support for symbol namespaces Matthias Maennich 2019-08-13 15:26 ` Greg KH 2019-08-13 12:17 ` [PATCH v2 04/10] modpost: " Matthias Maennich 2019-08-13 15:27 ` Greg KH 2019-08-13 12:17 ` [PATCH v2 05/10] module: add config option MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS Matthias Maennich 2019-08-13 18:17 ` Greg KH 2019-08-13 20:15 ` Saravana Kannan 2019-08-14 12:54 ` Matthias Maennich 2019-08-14 17:34 ` Saravana Kannan 2019-08-13 12:17 ` [PATCH v2 06/10] export: allow definition default namespaces in Makefiles or sources Matthias Maennich 2019-08-13 18:16 ` Greg KH 2019-08-13 18:16 ` Greg KH 2019-08-13 12:17 ` [PATCH v2 07/10] modpost: add support for generating namespace dependencies Matthias Maennich 2019-08-13 18:21 ` Greg KH 2019-08-13 12:17 ` [PATCH v2 08/10] scripts: Coccinelle script for " Matthias Maennich 2019-08-13 12:31 ` Julia Lawall 2019-08-13 12:44 ` Greg KH 2019-08-14 6:36 ` [Cocci] " Himanshu Jha 2019-08-14 8:03 ` Matthias Maennich 2019-08-14 12:00 ` [v2 " Markus Elfring 2019-08-15 13:50 ` Markus Elfring 2019-08-22 9:18 ` Matthias Maennich 2019-08-22 11:00 ` Markus Elfring 2019-08-13 12:17 ` [PATCH v2 09/10] usb-storage: remove single-use define for debugging Matthias Maennich 2019-08-13 12:42 ` Greg KH 2019-08-13 13:12 ` Greg KH 2019-08-13 12:17 ` [PATCH v2 10/10] RFC: usb-storage: export symbols in USB_STORAGE namespace Matthias Maennich 2019-08-13 12:45 ` Greg KH 2019-08-13 12:47 ` Greg KH 2019-08-13 15:02 ` Matthias Maennich [not found] ` <20190821114955.12788-1-maennich@google.com> 2019-08-21 11:49 ` [PATCH v3 01/11] module: support reading multiple values per modinfo tag Matthias Maennich 2019-08-21 11:49 ` [PATCH v3 02/11] export: explicitly align struct kernel_symbol Matthias Maennich 2019-08-21 11:49 ` [PATCH v3 03/11] module: add support for symbol namespaces Matthias Maennich 2019-08-27 15:37 ` Jessica Yu 2019-08-27 16:04 ` Matthias Maennich 2019-08-21 11:49 ` [PATCH v3 04/11] modpost: " Matthias Maennich 2019-08-26 16:21 ` Jessica Yu 2019-08-27 14:41 ` Matthias Maennich 2019-08-28 9:43 ` Jessica Yu 2019-08-28 9:55 ` Matthias Maennich 2019-08-28 10:16 ` Jessica Yu 2019-08-21 11:49 ` [PATCH v3 05/11] module: add config option MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS Matthias Maennich 2019-08-21 11:49 ` [PATCH v3 06/11] export: allow definition default namespaces in Makefiles or sources Matthias Maennich 2019-08-28 10:49 ` Jessica Yu 2019-08-28 10:56 ` Matthias Maennich 2019-08-21 11:49 ` [PATCH v3 07/11] modpost: add support for generating namespace dependencies Matthias Maennich 2019-08-21 11:49 ` [PATCH v3 08/11] scripts: Coccinelle script for " Matthias Maennich 2019-08-22 6:09 ` [v3 " Markus Elfring 2019-08-29 12:13 ` [PATCH v3 " Jessica Yu 2019-08-21 11:49 ` [PATCH v3 09/11] usb-storage: remove single-use define for debugging Matthias Maennich 2019-08-21 12:37 ` Greg KH 2019-08-21 13:21 ` Thomas Gleixner 2019-08-21 13:32 ` Greg KH 2019-08-21 11:49 ` [PATCH v3 10/11] RFC: usb-storage: export symbols in USB_STORAGE namespace Matthias Maennich 2019-08-21 12:38 ` Greg KH 2019-08-21 14:36 ` Jessica Yu 2019-08-21 23:13 ` Christoph Hellwig 2019-08-22 8:32 ` Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 00/12] Symbol Namespaces Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 01/12] module: support reading multiple values per modinfo tag Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 02/12] export: explicitly align struct kernel_symbol Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 03/12] module: add support for symbol namespaces Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 04/12] modpost: " Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 05/12] module: add config option MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 06/12] export: allow definition default namespaces in Makefiles or sources Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 07/12] modpost: add support for generating namespace dependencies Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 08/12] scripts: Coccinelle script for " Matthias Maennich 2019-09-04 9:53 ` Masahiro Yamada 2019-09-05 14:46 ` Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 09/12] docs: Add documentation for Symbol Namespaces Matthias Maennich 2019-09-04 7:16 ` Greg KH 2019-09-03 15:06 ` [PATCH v4 10/12] usb-storage: remove single-use define for debugging Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 11/12] RFC: usb-storage: export symbols in USB_STORAGE namespace Matthias Maennich 2019-09-03 15:06 ` [PATCH v4 12/12] RFC: watchdog: export core symbols in WATCHDOG_CORE namespace Matthias Maennich 2019-09-03 16:10 ` Guenter Roeck 2019-09-04 8:45 ` Masahiro Yamada 2019-09-04 12:12 ` Guenter Roeck 2019-09-04 16:16 ` [usb-storage] " Matthew Dharm 2019-09-05 10:41 ` Jessica Yu 2019-09-05 10:52 ` Arnd Bergmann 2019-09-05 11:16 ` Jessica Yu 2019-09-05 11:25 ` Masahiro Yamada 2019-09-05 12:00 ` Greg Kroah-Hartman 2019-09-05 11:25 ` Matthias Maennich 2019-09-04 9:37 ` [PATCH v4 00/12] Symbol Namespaces Masahiro Yamada 2019-09-06 10:32 ` [PATCH v5 00/11] " Matthias Maennich 2019-09-06 10:32 ` [PATCH v5 01/11] module: support reading multiple values per modinfo tag Matthias Maennich 2019-09-06 10:32 ` [PATCH v5 02/11] export: explicitly align struct kernel_symbol Matthias Maennich 2019-09-06 10:32 ` [PATCH v5 03/11] module: add support for symbol namespaces Matthias Maennich 2019-09-06 10:32 ` [PATCH v5 04/11] modpost: " Matthias Maennich 2019-09-06 10:32 ` [PATCH v5 05/11] module: add config option MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS Matthias Maennich 2019-09-06 10:32 ` [PATCH v5 06/11] export: allow definition default namespaces in Makefiles or sources Matthias Maennich 2019-09-06 10:32 ` [PATCH v5 07/11] modpost: add support for generating namespace dependencies Matthias Maennich 2019-09-06 10:32 ` [PATCH v5 08/11] scripts: Coccinelle script for " Matthias Maennich 2019-09-06 10:32 ` Matthias Maennich [this message] 2019-09-06 10:32 ` [PATCH v5 10/11] usb-storage: remove single-use define for debugging Matthias Maennich 2019-09-06 12:59 ` Jessica Yu 2019-09-06 13:22 ` Greg KH 2019-09-06 10:32 ` [PATCH v5 11/11] usb-storage: export symbols in USB_STORAGE namespace Matthias Maennich 2019-09-09 8:35 ` [PATCH v5 00/11] Symbol Namespaces Jessica Yu
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20190906103235.197072-10-maennich@google.com \ --to=maennich@google.com \ --cc=arnd@arndb.de \ --cc=gregkh@linuxfoundation.org \ --cc=jeyu@kernel.org \ --cc=joel@joelfernandes.org \ --cc=kernel-team@android.com \ --cc=linux-kbuild@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-modules@vger.kernel.org \ --cc=linux-usb@vger.kernel.org \ --cc=lucas.de.marchi@gmail.com \ --cc=maco@android.com \ --cc=sspatil@google.com \ --cc=usb-storage@lists.one-eyed-alien.net \ --cc=will@kernel.org \ --cc=yamada.masahiro@socionext.com \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Linux-Modules Archive on lore.kernel.org Archives are clonable: git clone --mirror https://lore.kernel.org/linux-modules/0 linux-modules/git/0.git # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V2 linux-modules linux-modules/ https://lore.kernel.org/linux-modules \ linux-modules@vger.kernel.org public-inbox-index linux-modules Example config snippet for mirrors Newsgroup available over NNTP: nntp://nntp.lore.kernel.org/org.kernel.vger.linux-modules AGPL code for this site: git clone https://public-inbox.org/public-inbox.git