docs/core-api/symbol-namespaces: drop table of contents and section numbering

+17 -28

Documentation/core-api/symbol-namespaces.rst

··· 6 6 export surface of in-kernel symbols exported through the family of 7 7 EXPORT_SYMBOL() macros. 8 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 - =============== 9 + Introduction 10 + ============ 21 11 22 12 Symbol Namespaces have been introduced as a means to structure the export 23 13 surface of the in-kernel API. It allows subsystem maintainers to partition ··· 21 31 Additionally, it is possible to put symbols into a module namespace, strictly 22 32 limiting which modules are allowed to use these symbols. 23 33 24 - 2. How to define Symbol Namespaces 25 - ================================== 34 + How to define Symbol Namespaces 35 + =============================== 26 36 27 37 Symbols can be exported into namespace using different methods. All of them are 28 38 changing the way EXPORT_SYMBOL and friends are instrumented to create ksymtab 29 39 entries. 30 40 31 - 2.1 Using the EXPORT_SYMBOL macros 32 - ================================== 41 + Using the EXPORT_SYMBOL macros 42 + ------------------------------ 33 43 34 44 In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow 35 45 exporting of kernel symbols to the kernel symbol table, variants of these are ··· 47 57 and kernel/module/main.c make use the namespace at build time or module load 48 58 time, respectively. 49 59 50 - 2.2 Using the DEFAULT_SYMBOL_NAMESPACE define 51 - ============================================= 60 + Using the DEFAULT_SYMBOL_NAMESPACE define 61 + ----------------------------------------- 52 62 53 63 Defining namespaces for all symbols of a subsystem can be very verbose and may 54 64 become hard to maintain. Therefore a default define (DEFAULT_SYMBOL_NAMESPACE) ··· 76 86 within the corresponding compilation unit before the #include for 77 87 <linux/export.h>. Typically it's placed before the first #include statement. 78 88 79 - 2.3 Using the EXPORT_SYMBOL_GPL_FOR_MODULES() macro 80 - =================================================== 89 + Using the EXPORT_SYMBOL_GPL_FOR_MODULES() macro 90 + ----------------------------------------------- 81 91 82 92 Symbols exported using this macro are put into a module namespace. This 83 93 namespace cannot be imported. ··· 92 102 will limit usage of this symbol to modules whoes name matches the given 93 103 patterns. 94 104 95 - 3. How to use Symbols exported in Namespaces 96 - ============================================ 105 + How to use Symbols exported in Namespaces 106 + ========================================= 97 107 98 108 In order to use symbols that are exported into namespaces, kernel modules need 99 109 to explicitly import these namespaces. Otherwise the kernel might reject to ··· 115 125 116 126 117 127 It is advisable to add the MODULE_IMPORT_NS() statement close to other module 118 - metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE(). Refer to section 119 - 5. for a way to create missing import statements automatically. 128 + metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE(). 120 129 121 - 4. Loading Modules that use namespaced Symbols 122 - ============================================== 130 + Loading Modules that use namespaced Symbols 131 + =========================================== 123 132 124 133 At module loading time (e.g. ``insmod``), the kernel will check each symbol 125 134 referenced from the module for its availability and whether the namespace it ··· 129 140 option is available: Setting MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y will 130 141 enable loading regardless, but will emit a warning. 131 142 132 - 5. Automatically creating MODULE_IMPORT_NS statements 133 - ===================================================== 143 + Automatically creating MODULE_IMPORT_NS statements 144 + ================================================== 134 145 135 146 Missing namespaces imports can easily be detected at build time. In fact, 136 147 modpost will emit a warning if a module uses a symbol from a namespace

+15 -17

Documentation/translations/it_IT/core-api/symbol-namespaces.rst

··· 10 10 per strutturare quello che viene esportato internamente al kernel 11 11 grazie alle macro della famiglia EXPORT_SYMBOL(). 12 12 13 - 1. Introduzione 14 - =============== 13 + Introduzione 14 + ============ 15 15 16 16 Lo spazio dei nomi dei simboli è stato introdotto come mezzo per strutturare 17 17 l'API esposta internamente al kernel. Permette ai manutentori di un ··· 24 24 della configurazione, potrebbe rifiutare di caricare il modulo o 25 25 avvisare l'utente di un'importazione mancante. 26 26 27 - 2. Come definire uno spazio dei nomi dei simboli 28 - ================================================ 27 + Come definire uno spazio dei nomi dei simboli 28 + ============================================= 29 29 30 30 I simboli possono essere esportati in spazi dei nomi usando diversi 31 31 meccanismi. Tutti questi meccanismi cambiano il modo in cui 32 32 EXPORT_SYMBOL e simili vengono guidati verso la creazione di voci in ksymtab. 33 33 34 - 2.1 Usare le macro EXPORT_SYMBOL 35 - ================================ 34 + Usare le macro EXPORT_SYMBOL 35 + ---------------------------- 36 36 37 37 In aggiunta alle macro EXPORT_SYMBOL() e EXPORT_SYMBOL_GPL(), che permettono 38 38 di esportare simboli del kernel nella rispettiva tabella, ci sono ··· 53 53 spazio dei nomi, rispettivamente, durante la compilazione e durante il 54 54 caricamento di un modulo. 55 55 56 - 2.2 Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE 57 - ============================================================== 56 + Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE 57 + ---------------------------------------------------------- 58 58 59 59 Definire lo spazio dei nomi per tutti i simboli di un sottosistema può essere 60 60 logorante e di difficile manutenzione. Perciò è stato fornito un simbolo ··· 83 83 84 84 Questo va messo prima di un qualsiasi uso di EXPORT_SYMBOL. 85 85 86 - 3. Come usare i simboli esportati attraverso uno spazio dei nomi 87 - ================================================================ 86 + Come usare i simboli esportati attraverso uno spazio dei nomi 87 + ============================================================= 88 88 89 89 Per usare i simboli esportati da uno spazio dei nomi, i moduli del 90 90 kernel devono esplicitamente importare il relativo spazio dei nomi; altrimenti ··· 108 108 109 109 110 110 Si consiglia di posizionare la dichiarazione MODULE_IMPORT_NS() vicino 111 - ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE(). Fate 112 - riferimento alla sezione 5. per creare automaticamente le importazioni 113 - mancanti. 111 + ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE(). 114 112 115 - 4. Caricare moduli che usano simboli provenienti da spazi dei nomi 116 - ================================================================== 113 + Caricare moduli che usano simboli provenienti da spazi dei nomi 114 + =============================================================== 117 115 118 116 Quando un modulo viene caricato (per esempio usando ``insmod``), il kernel 119 117 verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi ··· 123 125 MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y caricherà i moduli comunque ma 124 126 emetterà un avviso. 125 127 126 - 5. Creare automaticamente la dichiarazione MODULE_IMPORT_NS 127 - =========================================================== 128 + Creare automaticamente la dichiarazione MODULE_IMPORT_NS 129 + ======================================================== 128 130 129 131 La mancanza di un'importazione può essere individuata facilmente al momento 130 132 della compilazione. Infatti, modpost emetterà un avviso se il modulo usa

+15 -26

Documentation/translations/zh_CN/core-api/symbol-namespaces.rst

··· 14 14 15 15 本文档描述了如何使用符号命名空间来构造通过EXPORT_SYMBOL()系列宏导出的内核内符号的导出面。 16 16 17 - .. 目录 18 - 19 - === 1 简介 20 - === 2 如何定义符号命名空间 21 - --- 2.1 使用EXPORT_SYMBOL宏 22 - --- 2.2 使用DEFAULT_SYMBOL_NAMESPACE定义 23 - === 3 如何使用命名空间中导出的符号 24 - === 4 加载使用命名空间符号的模块 25 - === 5 自动创建MODULE_IMPORT_NS声明 26 - 27 - 1. 简介 28 - ======= 17 + 简介 18 + ==== 29 19 30 20 符号命名空间已经被引入，作为构造内核内API的导出面的一种手段。它允许子系统维护者将 31 21 他们导出的符号划分进独立的命名空间。这对于文档的编写非常有用（想想SUBSYSTEM_DEBUG ··· 23 33 的模块必须导入命名空间。否则，内核将根据其配置，拒绝加载该模块或警告说缺少 24 34 导入。 25 35 26 - 2. 如何定义符号命名空间 27 - ======================= 36 + 如何定义符号命名空间 37 + ==================== 28 38 29 39 符号可以用不同的方法导出到命名空间。所有这些都在改变 EXPORT_SYMBOL 和与之类似的那些宏 30 40 被检测到的方式，以创建 ksymtab 条目。 31 41 32 - 2.1 使用EXPORT_SYMBOL宏 33 - ======================= 42 + 使用EXPORT_SYMBOL宏 43 + ------------------- 34 44 35 45 除了允许将内核符号导出到内核符号表的宏EXPORT_SYMBOL()和EXPORT_SYMBOL_GPL()之外， 36 46 这些宏的变体还可以将符号导出到某个命名空间：EXPORT_SYMBOL_NS() 和 EXPORT_SYMBOL_NS_GPL()。 ··· 44 54 导出时未指明命名空间的符号将指向 ``NULL`` 。如果没有定义命名空间，则默认没有。 45 55 ``modpost`` 和kernel/module/main.c分别在构建时或模块加载时使用名称空间。 46 56 47 - 2.2 使用DEFAULT_SYMBOL_NAMESPACE定义 48 - ==================================== 57 + 使用DEFAULT_SYMBOL_NAMESPACE定义 58 + -------------------------------- 49 59 50 60 为一个子系统的所有符号定义命名空间可能会非常冗长，并可能变得难以维护。因此，我 51 61 们提供了一个默认定义（DEFAULT_SYMBOL_NAMESPACE），如果设置了这个定义，它将成 ··· 70 80 71 81 应置于相关编译单元中任何 EXPORT_SYMBOL 宏之前 72 82 73 - 3. 如何使用命名空间中导出的符号 74 - =============================== 83 + 如何使用命名空间中导出的符号 84 + ============================ 75 85 76 86 为了使用被导出到命名空间的符号，内核模块需要明确地导入这些命名空间。 77 87 否则内核可能会拒绝加载该模块。模块代码需要使用宏MODULE_IMPORT_NS来 ··· 90 100 91 101 92 102 建议将 MODULE_IMPORT_NS() 语句添加到靠近其他模块元数据定义的地方， 93 - 如 MODULE_AUTHOR() 或 MODULE_LICENSE() 。关于自动创建缺失的导入 94 - 语句的方法，请参考第5节。 103 + 如 MODULE_AUTHOR() 或 MODULE_LICENSE() 。 95 104 96 - 4. 加载使用命名空间符号的模块 97 - ============================= 105 + 加载使用命名空间符号的模块 106 + ========================== 98 107 99 108 在模块加载时（比如 ``insmod`` ），内核将检查每个从模块中引用的符号是否可 100 109 用，以及它可能被导出到的名字空间是否被模块导入。内核的默认行为是拒绝 ··· 102 113 设置 MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y 将使加载不受影响，但会 103 114 发出警告。 104 115 105 - 5. 自动创建MODULE_IMPORT_NS声明 106 - =============================== 116 + 自动创建MODULE_IMPORT_NS声明 117 + ============================ 107 118 108 119 缺少命名空间的导入可以在构建时很容易被检测到。事实上，如果一个模块 109 120 使用了一个命名空间的符号而没有导入它，modpost会发出警告。

Configure Feed

Configure Feed