Linux 内核 ABI 稳定接口机制解析：abi-stable 文档、2 年兼容承诺与 ABI 文档体系

Linux 内核为内核态与用户态之间的接口定义了一套明确的 ABI 稳定性分级体系，其中 abi-stable.rst 是管理员指南中专门描述“稳定级”接口的文档。本文围绕该文档展开，讲解 stable 接口的兼容承诺、Documentation/ABI/stable/ 目录下的实际内容、ABI 文档的字段规范，以及接口在各稳定性等级之间的迁移规则，帮助你在开发用户态程序时正确评估可依赖的内核接口及其保障边界。

稳定接口的核心承诺

abi-stable.rst 原文非常凝练，但它承载了两条对应用开发者至关重要的承诺：

1. 无限制使用 + 至少 2 年的向后兼容保证：用户态程序可以自由使用被标记为 stable 的接口，开发者必须至少为其保留 2 年的向后兼容性。
2. 绝大多数接口预期永不改变：以系统调用（syscall）为代表的接口，预期是“永不改变、始终可用”的。

该文档通过 kernel-abi:: stable 指令把 Documentation/ABI/stable 目录下的所有条目聚合进文档树渲染（附带 :no-files: 选项，表示不单独生成每个文件的页面）。它位于 Documentation/admin-guide/abi.rst 定义的“ABI symbols” toctree 中，与 abi-testing.rst、abi-obsolete.rst、abi-removed.rst 共同构成四级 ABI 稳定性文档的入口。

四级稳定性体系：stable 处于什么位置

Documentation/ABI/README 是理解 stable 文档的前提，它定义了内核 ABI 的四个等级，对应 Documentation/ABI 下的四个子目录：

等级	目录	语义
stable	Documentation/ABI/stable	开发者明确定义为稳定，可无限制使用，向后兼容至少保证 2 年；多数接口（如 syscall）预期永不改变
testing	Documentation/ABI/testing	主体开发已完成、被认为趋于稳定；仍可加新特性，除非发现严重错误或安全问题，否则不会破坏现有接口；使用者应登记自己以便变更时被通知
obsolete	Documentation/ABI/obsolete	仍保留在内核中，但已标记为将来某时点移除；文档中说明废弃原因和预计移除时间
removed	Documentation/ABI/removed	已经从内核中移除的旧接口清单

从当前仓库的实际规模看，四个目录的文件数分别为：stable 52 个、testing 602 个、obsolete 26 个、removed 17 个。这直观说明 stable 是最小的、经过时间检验的集合——大量接口长期停留在 testing 状态，只有被确认“不会再动”的接口才会晋升到 stable，这也正是 2 年兼容承诺含金量高的原因。

stable 接口的实际内容与命名约定

Documentation/ABI/stable 目录下的 52 个条目覆盖了内核当前承诺稳定的全部用户态可见接口，从源码目录命名可以归纳出几类典型形态：

• 系统调用整体：Documentation/ABI/stable/syscalls 是整个 syscall 接口的稳定声明。该文件明确说明这一接口“大部分匹配 POSIX 接口并基于它和其他 Unix 接口构建，只会随时间增加，不会移除已有内容”，同时提醒该接口在每个 Linux 支持的架构上各不相同，syscall 编号映射需查阅架构相关文档。这就是 abi-stable.rst 所说“多数接口预期永不改变”的典型代表。
• vDSO：Documentation/ABI/stable/vdso（KernelVersion 3.0，2011 年建立）记录了 vDSO 的调用约定、符号版本化（symbol versioning）要求，以及如何通过辅助向量中的 AT_SYSINFO_EHDR 定位 DSO，并指向参考解析器 tools/testing/selftests/vDSO/parse_vdso.c。
• sysfs 属性文件：这是 stable 目录的主体，按命名前缀可区分为：
  • sysfs-block（如 sysfs-block，941 行，逐条记录 /sys/block/<disk>/alignment_offset、discard_alignment、atomic_write_max_bytes 等块设备属性的含义、引入日期和联系人）；
  • sysfs-devices*（如 sysfs-devices，记录 /sys/devices/*/dev、of_node 等通用设备属性）；
  • sysfs-bus-*、sysfs-class-*、sysfs-driver-*（按总线/类/驱动划分，如 sysfs-bus-usb、sysfs-class-tpm、sysfs-driver-qla2xxx）；
  • procfs-*、configfs-*（如 procfs-audit_loginuid、configfs-nvmet）。

从源码结构看，文件名基本与内核中对应接口的导出位置一一对应（/sys 路径前缀决定 sysfs- 命名），因此用户态开发者定位一个接口是否受 2 年承诺保护，最直接的方法就是查这个目录中是否存在对应条目。

ABI 文档条目的字段规范

Documentation/ABI/README 规定了每个 ABI 文件必须包含的字段，stable 目录中的条目全部遵循这一格式。以 Documentation/ABI/stable/vdso 为例：

What:		vDSO
Date:		July 2011
KernelVersion:	3.0
Contact:	Andy Lutomirski <[e-mail]>
Description:
	On some architectures, when the kernel loads any userspace
	program it maps an ELF DSO into that program's address space.
	...

各字段含义如下：

• What：接口的简短描述（一个文件可含多条 What，逐条记录同一接口族下的多个属性，如 sysfs-block 就是多条目聚合）；
• Date：条目创建日期；
• KernelVersion（可选）：该特性首次出现的内核版本。README 特别说明 git 历史往往能提供更准确的版本信息，因此该字段可省略；
• Contact：接口主要联系人，可以是邮件列表；
• Description：接口的详细说明和使用方式；
• Users：希望在接口变更时收到通知的使用方名单。README 强调这对 testing 阶段接口尤其重要，便于内核开发者与用户态开发者协同避免破坏性变更；对 stable 接口虽已承诺兼容，保留用户登记同样有助于问题反馈。

README 还要求字段使用兼容 ReST 标记的简单记法，且文件不应带顶层索引标题。这一格式规范使得条目既适合人工阅读，也便于工具按 What:/Contact: 等锚点解析。

接口在稳定性等级之间的迁移规则

stable 不是终点，也不是起点。Documentation/ABI/README 定义了清晰的迁移路径：

• testing → stable：当开发者认为接口开发完成、不再需要修改时，条目从 Documentation/ABI/testing 移入 Documentation/ABI/stable。testing 状态的接口不允许跳过 obsolete 直接从内核移除，必须先经过 obsolete 流程。
• stable → obsolete：stable 接口可以降级为 obsolete，但“必须给予正式通知”（即通知 Users 字段登记的依赖方），这是 2 年承诺的兑现方式——移除前先标记、说明原因与预计移除时间（对应 Documentation/ABI/obsolete 中的条目约定）。
• obsolete → removed：文档中声明的时间窗口过后，接口可以从内核和 obsolete 目录中删除，条目移入 Documentation/ABI/removed 留档。例如 removed 目录中保留了 devfs、raw1394、net_dma 等历史上被移除的接口名。

接口初始放在哪个等级由开发者自行决定，README 对此留有自主权。

不属于稳定 ABI 的东西

理解 stable 承诺的边界同样重要。Documentation/ABI/README 末尾专门列出“在任何情况下都不应被视为稳定”的内容：

1. Kconfig 符号：用户态不得依赖 /proc/config.gz、安装在 /boot 的 .config 副本或内核构建过程中任何特定 Kconfig 符号的有无。
2. 内核内部符号：不得依赖 System.map 文件或内核二进制中任何内核符号的存在、缺失、位置或类型。README 指向 Documentation/process/stable-api-nonsense.rst 进一步说明为何内核内部接口不应被当作“稳定 API”对待——这正解释了为什么 abi-stable.rst 的 2 年承诺只覆盖 Documentation/ABI/stable/ 中登记的用户态可见接口，而非内核全部符号表。

小结

abi-stable.rst 用不到 20 行定义了 Linux 内核 ABI 承诺的最高等级：无限制使用、至少 2 年向后兼容、且多数接口（如 syscall）预期永不改变。结合 Documentation/ABI/README 的分级规则与字段规范，以及 Documentation/ABI/stable 目录下 52 个实际条目（syscalls、vdso、sysfs-block 等），可以得出实践结论：

• 评估某接口是否受稳定承诺保护，直接查 Documentation/ABI/stable/ 是否有对应条目；
• testing 接口可用，但需在 Users 字段登记并接受变更通知义务；
• 看到 obsolete 标记应开始迁移，removed 目录则是历史接口的存档；
• Kconfig 符号和内核内部符号永远不在任何稳定承诺之内。

按这套体系使用内核接口，就能在兼容性与功能先进性之间做出有据可依的取舍。