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

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

===============

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

Additionally, it is possible to put symbols into a module namespace, strictly

limiting which modules are allowed to use these symbols.

2. How to define Symbol Namespaces

==================================

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

==================================

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

and kernel/module/main.c make use the namespace at build time or module load

time, respectively.

2.2 Using the DEFAULT_SYMBOL_NAMESPACE define

=============================================

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)

within the corresponding compilation unit before the #include for

<linux/export.h>. Typically it's placed before the first #include statement.

2.3 Using the EXPORT_SYMBOL_GPL_FOR_MODULES() macro

===================================================

Using the EXPORT_SYMBOL_GPL_FOR_MODULES() macro

-----------------------------------------------

Symbols exported using this macro are put into a module namespace. This

namespace cannot be imported.

will limit usage of this symbol to modules whoes name matches the given

patterns.

3. How to use Symbols exported in Namespaces

============================================

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

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.

metadata definitions like MODULE_AUTHOR() or MODULE_LICENSE().

4. Loading Modules that use namespaced Symbols

==============================================

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

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

=====================================================

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

per strutturare quello che viene esportato internamente al kernel

grazie alle macro della famiglia EXPORT_SYMBOL().

1. Introduzione

===============

Introduzione

============

Lo spazio dei nomi dei simboli è stato introdotto come mezzo per strutturare

l'API esposta internamente al kernel. Permette ai manutentori di un

della configurazione, potrebbe rifiutare di caricare il modulo o

avvisare l'utente di un'importazione mancante.

2. Come definire uno spazio dei nomi dei simboli

================================================

Come definire uno spazio dei nomi dei simboli

=============================================

I simboli possono essere esportati in spazi dei nomi usando diversi

meccanismi.  Tutti questi meccanismi cambiano il modo in cui

EXPORT_SYMBOL e simili vengono guidati verso la creazione di voci in ksymtab.

2.1 Usare le macro EXPORT_SYMBOL

================================

Usare le macro EXPORT_SYMBOL

----------------------------

In aggiunta alle macro EXPORT_SYMBOL() e EXPORT_SYMBOL_GPL(), che permettono

di esportare simboli del kernel nella rispettiva tabella, ci sono

spazio dei nomi, rispettivamente, durante la compilazione e durante il

caricamento di un modulo.

2.2 Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE

==============================================================

Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE

----------------------------------------------------------

Definire lo spazio dei nomi per tutti i simboli di un sottosistema può essere

logorante e di difficile manutenzione. Perciò è stato fornito un simbolo

Questo va messo prima di un qualsiasi uso di EXPORT_SYMBOL.

3. Come usare i simboli esportati attraverso uno spazio dei nomi

================================================================

Come usare i simboli esportati attraverso uno spazio dei nomi

=============================================================

Per usare i simboli esportati da uno spazio dei nomi, i moduli del

kernel devono esplicitamente importare il relativo spazio dei nomi; altrimenti

Si consiglia di posizionare la dichiarazione MODULE_IMPORT_NS() vicino

ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE(). Fate

riferimento alla sezione 5. per creare automaticamente le importazioni

mancanti.

ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE().

4. Caricare moduli che usano simboli provenienti da spazi dei nomi

==================================================================

Caricare moduli che usano simboli provenienti da spazi dei nomi

===============================================================

Quando un modulo viene caricato (per esempio usando ``insmod``), il kernel

verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi

MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y caricherà i moduli comunque ma

emetterà un avviso.

5. Creare automaticamente la dichiarazione MODULE_IMPORT_NS

===========================================================

Creare automaticamente la dichiarazione MODULE_IMPORT_NS

========================================================

La mancanza di un'importazione può essere individuata facilmente al momento

della compilazione. Infatti, modpost emetterà un avviso se il modulo usa

本文档描述了如何使用符号命名空间来构造通过EXPORT_SYMBOL()系列宏导出的内核内符号的导出面。

.. 目录

       === 1 简介

       === 2 如何定义符号命名空间

          --- 2.1 使用EXPORT_SYMBOL宏

          --- 2.2 使用DEFAULT_SYMBOL_NAMESPACE定义

       === 3 如何使用命名空间中导出的符号

       === 4 加载使用命名空间符号的模块

       === 5 自动创建MODULE_IMPORT_NS声明

1. 简介

=======

简介

====

符号命名空间已经被引入，作为构造内核内API的导出面的一种手段。它允许子系统维护者将

他们导出的符号划分进独立的命名空间。这对于文档的编写非常有用（想想SUBSYSTEM_DEBUG

的模块必须导入命名空间。否则，内核将根据其配置，拒绝加载该模块或警告说缺少

导入。

2. 如何定义符号命名空间

=======================

如何定义符号命名空间

====================

符号可以用不同的方法导出到命名空间。所有这些都在改变 EXPORT_SYMBOL 和与之类似的那些宏

被检测到的方式，以创建 ksymtab 条目。

2.1 使用EXPORT_SYMBOL宏

=======================

使用EXPORT_SYMBOL宏

-------------------

除了允许将内核符号导出到内核符号表的宏EXPORT_SYMBOL()和EXPORT_SYMBOL_GPL()之外，

这些宏的变体还可以将符号导出到某个命名空间：EXPORT_SYMBOL_NS() 和 EXPORT_SYMBOL_NS_GPL()。

导出时未指明命名空间的符号将指向 ``NULL`` 。如果没有定义命名空间，则默认没有。

``modpost`` 和kernel/module/main.c分别在构建时或模块加载时使用名称空间。

2.2 使用DEFAULT_SYMBOL_NAMESPACE定义

====================================

使用DEFAULT_SYMBOL_NAMESPACE定义

--------------------------------

为一个子系统的所有符号定义命名空间可能会非常冗长，并可能变得难以维护。因此，我

们提供了一个默认定义（DEFAULT_SYMBOL_NAMESPACE），如果设置了这个定义， 它将成

应置于相关编译单元中任何 EXPORT_SYMBOL 宏之前

3. 如何使用命名空间中导出的符号

===============================

如何使用命名空间中导出的符号

============================

为了使用被导出到命名空间的符号，内核模块需要明确地导入这些命名空间。

否则内核可能会拒绝加载该模块。模块代码需要使用宏MODULE_IMPORT_NS来

建议将 MODULE_IMPORT_NS() 语句添加到靠近其他模块元数据定义的地方，

如 MODULE_AUTHOR() 或 MODULE_LICENSE() 。关于自动创建缺失的导入

语句的方法，请参考第5节。

如 MODULE_AUTHOR() 或 MODULE_LICENSE() 。

4. 加载使用命名空间符号的模块

=============================

加载使用命名空间符号的模块

==========================

在模块加载时（比如 ``insmod`` ），内核将检查每个从模块中引用的符号是否可

用，以及它可能被导出到的名字空间是否被模块导入。内核的默认行为是拒绝

设置 MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y 将使加载不受影响，但会

发出警告。

5. 自动创建MODULE_IMPORT_NS声明

===============================

自动创建MODULE_IMPORT_NS声明

============================

缺少命名空间的导入可以在构建时很容易被检测到。事实上，如果一个模块

使用了一个命名空间的符号而没有导入它，modpost会发出警告。