symbol-namespaces.rst 6.8 KB

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