1. 课程导入
在 Android 系统开发与长期维护中，内核与上层模块之间的接口稳定性，直接决定了设备能否低成本地完成版本升级、安全补丁合入与厂商功能迭代。很多团队在从 Android 11 迈向 Android 12、13、14 甚至更高版本时，都会遇到同一个痛点：内核接口一变，供应商模块、驱动、HAL 乃至 GKI 镜像之间的兼容关系就被打破，导致大量重复适配。KMI（Kernel Module Interface，内核模块接口）与 ABI（Application Binary Interface，应用二进制接口）兼容工程，正是为解决这一问题而建立的一套工程化方法。
本课程的目标不是让你死记某个符号列表，而是让你建立一套可复用的判断与操作能力：能看懂 KMI 的边界在哪里，能识别哪些改动会破坏 ABI，能使用工具生成和比对符号清单，能通过配置与构建手段把兼容性约束固化到工程流程中，最终让内核升级从“每次大改”变成“可控演进”。
一、核心概念：KMI、ABI 与 GKI 的关系
KMI 可以理解为内核对外暴露给可加载模块使用的一组符号、类型、结构布局与调用约定的集合。它既是源码层面的接口，也是二进制层面的契约。ABI 则更偏向二进制层面的兼容性：函数签名、结构体大小与对齐、枚举值、符号版本、调用约定等，只要有一处变化，就可能让已经编译好的模块无法加载或运行异常。
GKI（Generic Kernel Image）是 Google 推动的内核统一化方案：核心内核由 Google 维护并保证 KMI 稳定，厂商功能尽量以模块形式存在。这样，同一 GKI 内核可以配合不同厂商模块工作，减少碎片化。理解这三者的关系，是后续所有工程实践的基础。
一句话理解：GKI 提供稳定内核底座，KMI 定义模块可用接口，ABI 保证二进制层面不破裂。三者共同构成 Android 内核长期兼容的工程基础。
二、整体知识框架：从符号到流程的五个层次
本课程的知识框架可以分成五个层次，建议按顺序建立认知：
- 概念层：KMI、ABI、GKI、符号版本、模块签名、稳定接口等术语的准确定义。
- 符号层：哪些符号被导出、如何生成符号清单、如何比对差异、如何判断新增/删除/修改的影响。
- 构建层：内核配置、模块编译、KMI 检查、ABI 监控、构建产物与符号文件的生成关系。
- 工程层：如何把兼容性检查接入 CI，如何在代码评审中拦截破坏性改动，如何管理白名单与例外。
- 实战层：面对真实升级场景，如何定位不兼容点、如何修复、如何验证、如何复盘。
下面这张图展示了从 GKI 内核到厂商模块、再到 ABI 检查与 CI 拦截的整体关系，建议先建立这张“全局地图”，再进入后续章节的细节。
三、方法流程：兼容工程的基本工作流
在实际项目中，KMI/ABI 兼容工程通常遵循以下流程：
- 建立基线：选定一个 GKI 内核版本，生成标准符号清单与 ABI 描述文件，作为后续比对的基准。
- 修改代码：厂商或平台团队在内核或模块中新增功能、修复缺陷。
- 生成新清单：重新编译内核与模块，导出新的符号与类型信息。
- 差异比对：使用工具对比新旧清单，识别新增、删除、修改的符号与结构。
- 判断影响：区分“兼容性新增”与“破坏性修改”，对破坏性修改进行拦截或走例外流程。
- 修复与验证：调整代码或接口设计，重新编译并验证模块加载与功能运行。
- 固化流程：把检查步骤接入 CI，形成自动化拦截，减少人工遗漏。
提示：兼容工程的核心不是“禁止一切变化”，而是“让变化可见、可控、可追溯”。新增符号通常是安全的，删除或修改已有符号才需要重点审查。
四、案例场景：一次典型的升级适配
假设某厂商设备从 Android 13 升级到 Android 14，GKI 内核版本随之更新。厂商的 Wi-Fi 驱动模块在旧内核上编译运行正常，但在新内核上加载失败，日志提示“Unknown symbol”或“disagrees about version of symbol”。
# 典型错误日志
[ 12.345678] wifi_drv: Unknown symbol cfg80211_register_wiphy (err -2)
[ 12.345679] wifi_drv: disagrees about version of symbol mac80211_alloc_hw
[ 12.345680] wifi_drv: module verification failed: signature and/or required key missing
此时需要按以下思路排查：先确认该符号是否仍在 KMI 导出列表中；再检查符号版本或结构体布局是否发生变化；最后确认模块签名与内核配置是否匹配。若符号被移除，则需要推动内核侧重新导出，或调整模块实现方式，避免直接依赖非稳定接口。
常见误区：很多团队只关注“编译是否通过”，却忽略了“二进制是否兼容”。编译通过不代表模块能在目标内核上加载运行，ABI 层面的变化往往在运行时才暴露，因此必须把符号与 ABI 检查前移到构建阶段。
五、学习目标与检查清单
完成本课程后，你应当能够独立完成以下任务：
| 能力项 | 具体目标 | 对应实践 |
|---|---|---|
| 概念理解 | 准确区分 KMI、ABI、GKI 的含义与边界 | 能用自己的话解释三者关系 |
| 符号识别 | 能读懂符号清单与 ABI 描述文件 | 能找出新增、删除、修改的符号 |
| 工具使用 | 掌握符号生成与差异比对工具 | 能独立生成并比对两份清单 |
| 流程固化 | 能把兼容性检查接入 CI | 能配置自动拦截规则 |
| 实战排障 | 能定位模块加载失败原因 | 能根据日志判断符号或版本问题 |
| 复盘改进 | 能总结兼容性问题的根因与改进措施 | 能输出复盘报告与预防方案 |
建议你在学习过程中，每遇到一个符号或一次比对结果，都问自己三个问题：这个变化属于哪一类？它会影响谁？我如何在流程中提前发现它？当这三个问题成为习惯，KMI 与 ABI 兼容工程就不再是抽象概念，而是一套可以落地的工程能力。