尧图网站建设 
Linux 内核 ABI 文档体系:Removed ABI Files 文档页的生成机制与已移除接口溯源【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linuxDocumentation/admin-guide/abi-removed-files.rst是 Linux 内核管理指南(Admin Guide)中专门收录“已从内核中移除的用户空间 ABI 接口”的文档页,它仅由一条kernel-abireST 指令驱动,却在 Sphinx 构建时被自动渲染为Documentation/ABI/removed/目录下全部已移除接口文档的聚合页。读完本文,你将理解 Linux 内核四级 ABI 稳定性体系的运作规则、ABI 文档文件的字段规范、该文档页背后的 Sphinx 指令与解析器实现,并掌握如何在当前仓库中定位与考证某个已移除内核接口(如/sys/fs/selinux/disable、/sys/kernel/uids/uid/cpu_shares)的完整移除历史。一、文档页本体:一条指令,一个渲染入口abi-removed-files.rst全文只有 7 行:.. SPDX-License-Identifier: GPL-2.0 Removed ABI Files .. kernel-abi:: removed :no-symbols:它没有正文,真正的“正文”由构建系统生成:.. kernel-abi:: removed表示“解析Documentation/ABI/removed/目录下的全部 ABI 文件,并把它们渲染成文档内容”;:no-symbols:选项表示只列出文件级条目,不渲染符号索引部分(对比Documentation/admin-guide/abi-removed.rst,后者用:no-files:只列出符号)。两条指令互为镜像,分别对应“按文件看”和“按符号看”两种检索视角。该页挂在内核 ABI 总入口 abi.rst 的 toctree 下,与abi-stable-files、abi-testing-files、abi-obsolete-files并列,构成“ABI files”子树;而abi.rst顶部还内嵌了.. kernel-abi:: README,把 Documentation/ABI/README 的总述直接渲染进总入口页。二、四级 ABI 稳定性体系:removed 是生命周期的终点Documentation/ABI/README把内核与用户空间之间的接口按稳定性划分为四个目录、四个等级,removed/正是这个体系中的“讣告区”:目录含义稳定性承诺stable/开发者定义为稳定的接口用户空间可无限制使用,向后兼容至少保证 2 年;大多数接口(如系统调用)预期永不改变testing/主要开发已完成、基本稳定可加新特性但不得破坏现有接口(除非发现严重错误或安全问题);使用方强烈建议把自己加入Users:字段以便变更通知obsolete/仍在内核中但已被标记将来移除文档需写明废弃原因与预期移除时间removed/已从内核中移除的旧接口清单纯历史记录,用于溯源README 同时规定了接口在等级之间流动的规则,其中与removed/直接相关的是:obsolete/中的接口,在文档承诺的时间窗过后,可以从obsolete/目录和内核中一并移除;处于testing/状态的接口不能跳过obsolete/直接从内核树中删除。因此,Documentation/ABI/removed/中的每一份文件,都代表一个“曾废弃、后移除”的完整闭环。当前仓库中该目录共有 17 个条目,例如:sysfs-selinux-disable:/sys/fs/selinux/disable。文档保留了 2005 年的原始弃用公告,并补充了一条“REMOVAL UPDATE”:SELinux 运行时禁用功能于 2023 年 3 月被移除,原因是允许运行时禁用 SELinux 使内核无法用__ro_after_init特性保护 LSM 钩子,且默认 Kconfig 已关闭该节点、主要发行版(文中点名 Fedora)也不再支持运行时禁用。替代方案是启动参数selinux0,详见CONFIG_SECURITY_SELINUX_DISABLEKconfig 选项;sysfs-kernel-uids:/sys/kernel/uids/uid/cpu_shares,用户级 CPU 带宽比例分配接口,2007 年 12 月文档化,最终在 v2.6.34-rc1 被移除,文档指向了其后继设计Documentation/scheduler/sched-design-CFS.rst;o2cb:/sys/o2cb符号链接(3.0 引入),在新版 ocfs2-tools 普遍改用/sys/fs/o2cb后被移除,文档明确提醒“不要编写新软件去访问旧路径”;sysfs-mce:/sys/devices/system/machinecheck/machinecheckX/tolerant,2021 年 12 月标记移除,理由是 2010 年(Nehalem)起可恢复机器检查机制出现后该节点已无实际用途。除上述四类典型样本外,目录中还包含devfs、ip_queue、net_dma、raw1394、video1394、dv1394等随 1394 子系统退场而移除的接口,以及sysfs-class-cxl、sysfs-class-rfkill、sysfs-kernel-fadump_release_opalcore、sysfs-firmware-efi-vars、sysfs-selinux-checkreqprot、sysfs-selinux-user等 sysfs 节点。这个目录本身即是一份可全文检索的“内核用户态接口移除史”。三、文件格式规范:五个标准字段Documentation/ABI/README规定,stable/、testing/、obsolete/、removed/四个目录中的每个文件都包含如下字段:What: 接口的简短描述(通常是路径或符号名) Date: 文档创建日期 KernelVersion:(可选)该特性首次出现的内核版本;git 历史通常更准,可省略 Contact: 接口的主要联系人(可以是邮件列表) Description: 接口的长描述及用法 Users: 希望在接口变更时收到通知的使用方其中Users:字段对testing/状态接口尤其重要:内核开发者据此在改动前联系用户空间开发者,避免破坏性变更。README 还给出两条书写纪律:字段值需使用与 reST 兼容的简单记法;文件不应自带形式的顶级标题(标题由渲染管线统一生成)。四、渲染管线源码剖析:kernel-abi 指令与 AbiParser文档页之所以“只有 7 行却能渲染出完整目录内容”,靠的是 Sphinx 自定义扩展 Documentation/sphinx/kernel_abi.py。关键实现有三处:指令注册与单例解析:setup(app)调用app.add_directive(kernel-abi, KernelCmd)注册指令;get_kernel_abi()全局只初始化一次AbiParser(源码注释说明这是为了避免 Sphinx 模块初始化期间产生警告),并对Documentation/ABI执行parse_abi()与check_issues()。选项语义(见 kernel_abi.py 的option_spec):debug:把生成的原始 reST 以 code-block 形式输出,用于调试;no-symbols:关闭符号列表输出——abi-removed-files.rst用的正是它;no-files:关闭文件列表输出——abi-removed.rst(符号视角)用它。逐条渲染与依赖跟踪:KernelCmd.run()遍历kernel_abi.doc(show_file..., show_symbols..., filter_pathabi_type)产出的每个条目,按 ABI 文件分组;每当遇到新文件就调用env.note_dependency(fname)把该文件登记为 Sphinx 构建依赖——这意味着修改Documentation/ABI/removed/下任一文件都会触发文档重建。源码中还有一处工程细节:“Sphinx 不喜欢解析巨型消息”,因此内容被逐符号分块do_parse,而不是整页一次塞入。解析器本体是 tools/lib/python/abi/abi_parser.py 中的AbiParser类(Sphinx 插件通过把tools/lib/python插入sys.path来复用同一套解析逻辑,保证文档构建与命令行工具看到一致的结果)。值得注意的两个常量:TAGS r(what|where|date|kernelversion|contact|description|users):即上文五个标准字段的正则识别集;解析器还会主动拦截历史遗留错误——若遇到Where:标签会发出 “tag Where is invalid. Should be What: instead” 的告警并归一为What(见_parse_line中对new_tag where的处理);XREF:匹配/sys/...、/proc/...、/config/...、/dev/...、/kvd/...等路径形态,为已移除接口文档中的路径自动生成交叉引用,使读者从渲染后的文档页能直接跳转到对应接口说明。此外,AbiParser.__init__中定义了ignore_suffixes (.rej, .org, .orig, .bak, ~),即合并冲突残留、备份类文件不会被误认为 ABI 文档;_parse_line还会对重复 key 做确定性加盐去重(固定seed(42)),保证相同 ABI 符号集合下生成的命名空间稳定。五、实践:如何考证一个已移除的内核接口基于以上机制,在当前仓库中考证“某接口为何被移除、何时移除、替代方案是什么”的标准路径是:按路径名检索文档:Documentation/ABI/removed/下的文件名高度规律(sysfs 节点通常为sysfs-前缀加节点名,设备类为裸名),直接用 ripgrep 在目录内搜节点路径即可,例如搜索/sys/fs/selinux/disable可命中 sysfs-selinux-disable 的What:字段;读Description与Date:移除类文档惯例是在Description开头插入 “REMOVAL UPDATE” 段落,同时保留原始弃用公告,两者对照即可还原从“宣布废弃”到“真正移除”的完整时间线(SELinux disable 一例从 2005 年前弃用通告到 2023 年 3 月移除,间隔近 18 年);对照obsolete/目录:尚未移除但已被标记的接口(当前共 26 个文件)位于Documentation/ABI/obsolete/,其文档按 README 要求写明移除原因与预期时间,是预判下一个进入removed/的接口最可靠的位置;结合 git 历史:README明确提示“git history often provides more accurate version info”,KernelVersion:字段可省略,精确的首现/移除版本应以 git 日志为准;区分文件视角与符号视角:若已知接口符号名(而非文档文件名),使用Documentation/admin-guide/abi-removed.rst对应的符号索引页(线上文档中为 “ABI removed symbols” 页)检索更直接——两页由同一份Documentation/ABI/removed/数据渲染,只是no-files/no-symbols选项不同。六、边界说明:什么不属于内核 ABIREADME 末尾专门列出了“不应被视为稳定的非 ABI 项”,使用与考证接口时应牢记:Kconfig 不是 ABI:用户空间不得依赖任何 Kconfig 符号在/proc/config.gz、/boot下.config副本或构建过程中的存在与否;内核内部符号不是 ABI:不得依赖System.map或内核二进制中任何符号的存在、缺失、位置或类型(详见Documentation/process/stable-api-nonsense.rst)。这一点同样适用于removed/目录本身:它记录的是“曾经存在的用户空间接口”的归档,目录里某个条目的存在,既不意味着对应代码仍可在内核中找到,也不构成任何向后兼容承诺——它存在的唯一目的,就是让下游用户空间开发者在排查“某节点为何消失”时有据可查。【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Linux 内核 ABI 文档体系:Removed ABI Files 文档页的生成机制与已移除接口溯源
Linux 内核 ABI 文档体系:Removed ABI Files 文档页的生成机制与已移除接口溯源【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linuxDocumentation/admin-guide/abi-removed-files.rst是 Linux 内核管理指南(Admin Guide)中专门收录“已从内核中移除的用户空间 ABI 接口”的文档页,它仅由一条kernel-abireST 指令驱动,却在 Sphinx 构建时被自动渲染为Documentation/ABI/removed/目录下全部已移除接口文档的聚合页。读完本文,你将理解 Linux 内核四级 ABI 稳定性体系的运作规则、ABI 文档文件的字段规范、该文档页背后的 Sphinx 指令与解析器实现,并掌握如何在当前仓库中定位与考证某个已移除内核接口(如/sys/fs/selinux/disable、/sys/kernel/uids/uid/cpu_shares)的完整移除历史。一、文档页本体:一条指令,一个渲染入口abi-removed-files.rst全文只有 7 行:.. SPDX-License-Identifier: GPL-2.0 Removed ABI Files .. kernel-abi:: removed :no-symbols:它没有正文,真正的“正文”由构建系统生成:.. kernel-abi:: removed表示“解析Documentation/ABI/removed/目录下的全部 ABI 文件,并把它们渲染成文档内容”;:no-symbols:选项表示只列出文件级条目,不渲染符号索引部分(对比Documentation/admin-guide/abi-removed.rst,后者用:no-files:只列出符号)。两条指令互为镜像,分别对应“按文件看”和“按符号看”两种检索视角。该页挂在内核 ABI 总入口 abi.rst 的 toctree 下,与abi-stable-files、abi-testing-files、abi-obsolete-files并列,构成“ABI files”子树;而abi.rst顶部还内嵌了.. kernel-abi:: README,把 Documentation/ABI/README 的总述直接渲染进总入口页。二、四级 ABI 稳定性体系:removed 是生命周期的终点Documentation/ABI/README把内核与用户空间之间的接口按稳定性划分为四个目录、四个等级,removed/正是这个体系中的“讣告区”:目录含义稳定性承诺stable/开发者定义为稳定的接口用户空间可无限制使用,向后兼容至少保证 2 年;大多数接口(如系统调用)预期永不改变testing/主要开发已完成、基本稳定可加新特性但不得破坏现有接口(除非发现严重错误或安全问题);使用方强烈建议把自己加入Users:字段以便变更通知obsolete/仍在内核中但已被标记将来移除文档需写明废弃原因与预期移除时间removed/已从内核中移除的旧接口清单纯历史记录,用于溯源README 同时规定了接口在等级之间流动的规则,其中与removed/直接相关的是:obsolete/中的接口,在文档承诺的时间窗过后,可以从obsolete/目录和内核中一并移除;处于testing/状态的接口不能跳过obsolete/直接从内核树中删除。因此,Documentation/ABI/removed/中的每一份文件,都代表一个“曾废弃、后移除”的完整闭环。当前仓库中该目录共有 17 个条目,例如:sysfs-selinux-disable:/sys/fs/selinux/disable。文档保留了 2005 年的原始弃用公告,并补充了一条“REMOVAL UPDATE”:SELinux 运行时禁用功能于 2023 年 3 月被移除,原因是允许运行时禁用 SELinux 使内核无法用__ro_after_init特性保护 LSM 钩子,且默认 Kconfig 已关闭该节点、主要发行版(文中点名 Fedora)也不再支持运行时禁用。替代方案是启动参数selinux0,详见CONFIG_SECURITY_SELINUX_DISABLEKconfig 选项;sysfs-kernel-uids:/sys/kernel/uids/uid/cpu_shares,用户级 CPU 带宽比例分配接口,2007 年 12 月文档化,最终在 v2.6.34-rc1 被移除,文档指向了其后继设计Documentation/scheduler/sched-design-CFS.rst;o2cb:/sys/o2cb符号链接(3.0 引入),在新版 ocfs2-tools 普遍改用/sys/fs/o2cb后被移除,文档明确提醒“不要编写新软件去访问旧路径”;sysfs-mce:/sys/devices/system/machinecheck/machinecheckX/tolerant,2021 年 12 月标记移除,理由是 2010 年(Nehalem)起可恢复机器检查机制出现后该节点已无实际用途。除上述四类典型样本外,目录中还包含devfs、ip_queue、net_dma、raw1394、video1394、dv1394等随 1394 子系统退场而移除的接口,以及sysfs-class-cxl、sysfs-class-rfkill、sysfs-kernel-fadump_release_opalcore、sysfs-firmware-efi-vars、sysfs-selinux-checkreqprot、sysfs-selinux-user等 sysfs 节点。这个目录本身即是一份可全文检索的“内核用户态接口移除史”。三、文件格式规范:五个标准字段Documentation/ABI/README规定,stable/、testing/、obsolete/、removed/四个目录中的每个文件都包含如下字段:What: 接口的简短描述(通常是路径或符号名) Date: 文档创建日期 KernelVersion:(可选)该特性首次出现的内核版本;git 历史通常更准,可省略 Contact: 接口的主要联系人(可以是邮件列表) Description: 接口的长描述及用法 Users: 希望在接口变更时收到通知的使用方其中Users:字段对testing/状态接口尤其重要:内核开发者据此在改动前联系用户空间开发者,避免破坏性变更。README 还给出两条书写纪律:字段值需使用与 reST 兼容的简单记法;文件不应自带形式的顶级标题(标题由渲染管线统一生成)。四、渲染管线源码剖析:kernel-abi 指令与 AbiParser文档页之所以“只有 7 行却能渲染出完整目录内容”,靠的是 Sphinx 自定义扩展 Documentation/sphinx/kernel_abi.py。关键实现有三处:指令注册与单例解析:setup(app)调用app.add_directive(kernel-abi, KernelCmd)注册指令;get_kernel_abi()全局只初始化一次AbiParser(源码注释说明这是为了避免 Sphinx 模块初始化期间产生警告),并对Documentation/ABI执行parse_abi()与check_issues()。选项语义(见 kernel_abi.py 的option_spec):debug:把生成的原始 reST 以 code-block 形式输出,用于调试;no-symbols:关闭符号列表输出——abi-removed-files.rst用的正是它;no-files:关闭文件列表输出——abi-removed.rst(符号视角)用它。逐条渲染与依赖跟踪:KernelCmd.run()遍历kernel_abi.doc(show_file..., show_symbols..., filter_pathabi_type)产出的每个条目,按 ABI 文件分组;每当遇到新文件就调用env.note_dependency(fname)把该文件登记为 Sphinx 构建依赖——这意味着修改Documentation/ABI/removed/下任一文件都会触发文档重建。源码中还有一处工程细节:“Sphinx 不喜欢解析巨型消息”,因此内容被逐符号分块do_parse,而不是整页一次塞入。解析器本体是 tools/lib/python/abi/abi_parser.py 中的AbiParser类(Sphinx 插件通过把tools/lib/python插入sys.path来复用同一套解析逻辑,保证文档构建与命令行工具看到一致的结果)。值得注意的两个常量:TAGS r(what|where|date|kernelversion|contact|description|users):即上文五个标准字段的正则识别集;解析器还会主动拦截历史遗留错误——若遇到Where:标签会发出 “tag Where is invalid. Should be What: instead” 的告警并归一为What(见_parse_line中对new_tag where的处理);XREF:匹配/sys/...、/proc/...、/config/...、/dev/...、/kvd/...等路径形态,为已移除接口文档中的路径自动生成交叉引用,使读者从渲染后的文档页能直接跳转到对应接口说明。此外,AbiParser.__init__中定义了ignore_suffixes (.rej, .org, .orig, .bak, ~),即合并冲突残留、备份类文件不会被误认为 ABI 文档;_parse_line还会对重复 key 做确定性加盐去重(固定seed(42)),保证相同 ABI 符号集合下生成的命名空间稳定。五、实践:如何考证一个已移除的内核接口基于以上机制,在当前仓库中考证“某接口为何被移除、何时移除、替代方案是什么”的标准路径是:按路径名检索文档:Documentation/ABI/removed/下的文件名高度规律(sysfs 节点通常为sysfs-前缀加节点名,设备类为裸名),直接用 ripgrep 在目录内搜节点路径即可,例如搜索/sys/fs/selinux/disable可命中 sysfs-selinux-disable 的What:字段;读Description与Date:移除类文档惯例是在Description开头插入 “REMOVAL UPDATE” 段落,同时保留原始弃用公告,两者对照即可还原从“宣布废弃”到“真正移除”的完整时间线(SELinux disable 一例从 2005 年前弃用通告到 2023 年 3 月移除,间隔近 18 年);对照obsolete/目录:尚未移除但已被标记的接口(当前共 26 个文件)位于Documentation/ABI/obsolete/,其文档按 README 要求写明移除原因与预期时间,是预判下一个进入removed/的接口最可靠的位置;结合 git 历史:README明确提示“git history often provides more accurate version info”,KernelVersion:字段可省略,精确的首现/移除版本应以 git 日志为准;区分文件视角与符号视角:若已知接口符号名(而非文档文件名),使用Documentation/admin-guide/abi-removed.rst对应的符号索引页(线上文档中为 “ABI removed symbols” 页)检索更直接——两页由同一份Documentation/ABI/removed/数据渲染,只是no-files/no-symbols选项不同。六、边界说明:什么不属于内核 ABIREADME 末尾专门列出了“不应被视为稳定的非 ABI 项”,使用与考证接口时应牢记:Kconfig 不是 ABI:用户空间不得依赖任何 Kconfig 符号在/proc/config.gz、/boot下.config副本或构建过程中的存在与否;内核内部符号不是 ABI:不得依赖System.map或内核二进制中任何符号的存在、缺失、位置或类型(详见Documentation/process/stable-api-nonsense.rst)。这一点同样适用于removed/目录本身:它记录的是“曾经存在的用户空间接口”的归档,目录里某个条目的存在,既不意味着对应代码仍可在内核中找到,也不构成任何向后兼容承诺——它存在的唯一目的,就是让下游用户空间开发者在排查“某节点为何消失”时有据可查。【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考