Linux-Modules Archive on lore.kernel.org
 help / color / Atom feed
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


  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 publically 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 linux-modules@archiver.kernel.org
	public-inbox-index linux-modules


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