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

Source file repositories/reference/linux-study-clean/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst

File Facts

System
Linux kernel
Corpus path
Documentation/translations/zh_CN/core-api/symbol-namespaces.rst
Extension
.rst
Size
6240 bytes
Lines
134
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: exported/initcall integration point
Status
integration implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. include:: ../disclaimer-zh_CN.rst

:Original: Documentation/core-api/symbol-namespaces.rst

:翻译:

 司延腾 Yanteng Si <siyanteng@loongson.cn>

.. _cn_symbol-namespaces.rst:

=================================
符号命名空间（Symbol Namespaces）
=================================

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

简介
====

符号命名空间已经被引入，作为构造内核内API的导出面的一种手段。它允许子系统维护者将
他们导出的符号划分进独立的命名空间。这对于文档的编写非常有用（想想SUBSYSTEM_DEBUG
命名空间），也可以限制一组符号在内核其他部分的使用。今后，使用导出到命名空间的符号
的模块必须导入命名空间。否则，内核将根据其配置，拒绝加载该模块或警告说缺少
导入。

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

符号可以用不同的方法导出到命名空间。所有这些都在改变 EXPORT_SYMBOL 和与之类似的那些宏
被检测到的方式，以创建 ksymtab 条目。

使用EXPORT_SYMBOL宏
-------------------

除了允许将内核符号导出到内核符号表的宏EXPORT_SYMBOL()和EXPORT_SYMBOL_GPL()之外，
这些宏的变体还可以将符号导出到某个命名空间：EXPORT_SYMBOL_NS() 和 EXPORT_SYMBOL_NS_GPL()。
它们需要一个额外的参数：命名空间（the namespace）。请注意，由于宏扩展，该参数需
要是一个预处理器符号。例如，要把符号 ``usb_stor_suspend`` 导出到命名空间 ``USB_STORAGE``，
请使用::

       EXPORT_SYMBOL_NS(usb_stor_suspend, "USB_STORAGE");

相应的 ksymtab 条目结构体 ``kernel_symbol`` 将有相应的成员 ``命名空间`` 集。
导出时未指明命名空间的符号将指向 ``NULL`` 。如果没有定义命名空间，则默认没有。
``modpost`` 和kernel/module/main.c分别在构建时或模块加载时使用名称空间。

使用DEFAULT_SYMBOL_NAMESPACE定义
--------------------------------

为一个子系统的所有符号定义命名空间可能会非常冗长，并可能变得难以维护。因此，我
们提供了一个默认定义（DEFAULT_SYMBOL_NAMESPACE），如果设置了这个定义， 它将成
为所有没有指定命名空间的 EXPORT_SYMBOL() 和 EXPORT_SYMBOL_GPL() 宏扩展的默认
定义。

有多种方法来指定这个定义，使用哪种方法取决于子系统和维护者的喜好。第一种方法是在
子系统的 ``Makefile`` 中定义默认命名空间。例如，如果要将usb-common中定义的所有符号导
出到USB_COMMON命名空间，可以在drivers/usb/common/Makefile中添加这样一行::

       ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE='"USB_COMMON"'

这将影响所有 EXPORT_SYMBOL() 和 EXPORT_SYMBOL_GPL() 语句。当这个定义存在时，
用EXPORT_SYMBOL_NS()导出的符号仍然会被导出到作为命名空间参数传递的命名空间中，
因为这个参数优先于默认的符号命名空间。

定义默认命名空间的第二个选项是直接在编译单元中作为预处理声明。上面的例子就会变
成::

       #undef  DEFAULT_SYMBOL_NAMESPACE
       #define DEFAULT_SYMBOL_NAMESPACE "USB_COMMON"

Annotation

Implementation Notes