Skip to content

Translation pending. This page is currently available in Chinese.

驱动框架维护与扩展

面向修改公共接口、核心对象、生命周期或通用执行机制的开发者。只增加一个硬件实现时,先走第一个驱动;理解整体结构从核心模型开始。本文说明扩展应放在哪里、必须保持哪些契约,以及怎样验证它确实能被驱动使用。

1. 设计边界

A20 的内部模型围绕设备身份、当次绑定、显式存储和执行所有权组织。Linux ABI 与 Native ABI 适配共同消费内部机制;Linux file/ioctl 结构不成为新内核机制的基础对象。内核协议 ID、功能 capability 和用户访问 rights 含义不同,不能用“支持某功能”代替授权。

总线是硬件发现/枚举的唯一来源。endpoint 复用当次绑定的 publication,传统设备类作为其 primary protocol/adapter 存在。新增能力复用这些身份和引用,不再建立一套 device registry、owner 槽或随重绑自动转向的新 getter。

核心负责准入、所有权和生命周期;具体驱动负责寄存器协议、DMA/cache 交接和停止证明。资源 claim 约束参与该模型的访问者,不能约束任意 raw MMIO。内核模块仍是受信任代码;用户服务另经 capability/broker 和可用的硬件隔离后端。

2. 源码地图与阅读顺序

关注点 实现与声明 配套文档
注册、匹配、probe/退出、devres、依赖 kernel/drivers/core/driver_core.c 与同目录 driver_core.h 核心模型
publication、class registry、devfs 桥 driver_class.c、driver_class_mcu.c、driver_class.h 设备类
协议快照、版本/大小检查、active call driver_protocol.c、私有 driver_protocol_internal.h、公共 protocol.h 原生协议
请求状态、依赖、完成/退休、执行停止 queue.c、公共 queue.h 请求与队列
完成通知、任务工作、IRQ 排空 fence.c、workqueue.c、driver_hwapi.c 及相应声明 运行时契约、锁顺序
native 存储、映射和失败清理句柄 driver_hwapi.c、dma_mapping.c、dma_vmo.c;kernel/mm/vmo.c 原生运行时
总线/固件、板级来源 kernel/drivers/bus/、kernel/firmware/、kernel/include/drivers/bus/ 总线与平台
模块 exports、descriptor、包与部署 kernel/drvmod/framework.c、kernel/include/drivers/driver_descriptor.h、tools/mk/driver-*.mk 内核模块、部署配置

表中未写全路径的 .c 位于 kernel/drivers/core/;公共 protocol/queue/fence/workqueue/DMA 头位于 kernel/include/drivers/core/。先顺读一次 probe→publication→access→stop→remove,再看所扩展机制;不必先读所有平台后端。

3. 把改动放在合适的层

新需求 推荐落点
单芯片的寄存器、quirk、descriptor、复位步骤 驱动私有实现/头文件
已有功能的一种新硬件实现 既有总线和 class/protocol 后端
同一绑定上的可选统计或设备能力 独立原生协议,声明 ID/version/实际 ops_size/capabilities
多种驱动共用的内存、完成或执行机制 native core 公共接口,配合实际 provider/consumer 接入
必须改变所有该类 consumer 的单位或操作语义 子系统接口与 adapter;评估 class 表及 ABI 的影响
仅为兼容现有 Linux 程序的线格式/命令 ABI/subsystem adapter,翻译到原生机制
新硬件连接方式或新板 总线/固件/平台层;功能驱动不复制枚举

先完成一个实际使用场景,再确认哪些语义值得抽成通用机制。保留既有同步、批量/SG 等合理路径;通用 request 并不要求每个网络包或每个简单寄存器读取都分配新对象。借鉴上游硬件协议时,也按上述边界映射到 A20 的对象和生命周期。

4. 公共接口必须说明的契约

项目 需要给出的答案
身份与有效期 对象属于设备、某次绑定、某个 open、请求还是独立 backing?重绑后旧对象怎样表现?
引用与所有权 输入是借用还是转移?成功和失败各由谁持有?最后 put 能否执行模块代码?
上下文 probe-only、task、早期 boot 或 IRQ?是否分配、等待、执行回调或最终析构?
锁与重入 哪把锁保护状态?回调前释放哪些锁?允许并发、inline completion 或回调重入吗?
失败输出 errno、输出清零、部分初始化句柄、容量占用与显式重试如何处理?
硬件/存储 谁确认 DMA 结束和映射失效?超时返回后哪些页面/上下文仍须保留?
限制与权限 数量/长度/溢出检查、背压、能力协商及用户 rights 在哪一层验证?

声明位于公共头;仅核心内部共享的布局留在私有头。文档用状态图、所有权表和一条真实使用路径解释约定,不靠复制结构体字段维护另一份定义。字段和原型以当前头文件为准;上下文/分配行为同时核对实际调用路径。

例如,queue submit 与 IRQ complete 不分配 request 存储,但 task progress 初次为 pending dependency 建立 watch 时可以分配,provider prepare/retire 也按各自约定工作。不能把整个执行路径笼统称为“无分配”。fence 完成、native backing 引用和 DMA 权限也不能互相替代。

5. 生命周期与失败路径

完整退出顺序是:可选 pre-consumer prepare → consumer/child → offline → execution stop → quiesce → active-call drain → remove → devres。详细状态见核心生命周期。

修改时保持三条性质:停止/失效未确认就保留硬件可达资源;需要唤醒请求的停止工作发生在调用排空之前;成功停止也不提前释放仍被 CPU 调用使用的实例。execution action 自动选择受管 failed-probe 清理,登记成功才转移 context;其元数据 OOM 仍保留已选择的 managed rollback。

prepare 用于 consumer 仍借用硬件存储时提前冻结,execution stop 用于排空调用前停止执行,remove 用于最终交还资源。三个阶段不能合并成一个无错误返回的回调。各阶段成功项可以 checkpoint;失败是部分进度保留,不能假设整个设备图会自动回滚。

registry spinlock 只保护短元数据操作。lifecycle mutex 可以覆盖绑定退出,但完成路径不能等待它;provider 回调、fence signal、native owner 最后 put 的锁要求逐项检查。新引用不自动授予在线调用许可;active access 不自动保留异步数据。

6. 协议演进、模块与适用配置

新增可选功能优先发布独立协议。同一协议 ID 的语义版本必须匹配,consumer 声明实际需要的 ops 前缀和能力位;描述符被复制,ops/code 必须覆盖绑定生命周期。同版本兼容尾部增长仍需正确上报实际大小;改变语义则使用新版本,当前不在一个绑定下为同一 ID 同时发布多个版本。

协议版本与模块 ABI 是两件事。新独立协议或函数导出不自动改变既有布局;改变共享的 device/driver/class/HCD/GPU 表布局或调用约定时,按模块 ABI 策略更新并重建相应包。当前版本从 A20_DRIVER_ABI 读取,不在新指南里复制一份版本常量。模块 imports 必须能从 framework 导出表解析,内建成功不能代替 generic 包验证。

明确声明 hosted/MCU、MMU/NOMMU、架构和硬件后端的适用范围。MCU 使用轻量 publication 后端,不依赖完整 VFS/class registry;hosted queue/fence/workqueue 不等于 MCU 已具备同一异步运行时。平台未实现的 DMA/消息中断能力应显式拒绝或按驱动声明的路径回退。

7. 按改动选择验证

修改范围 最小验证方向
仅文档、API 注释 链接/导航、代码引用、完整 C 骨架语法检查;保持注释与实现一致
协议与 publication test_driver_protocol,包含 hosted/MCU、旧引用、active call 与失败清理
请求、fence、worker、停止顺序 test_driver_queue、test_driver_fence、test_driver_workqueue,加真实 kernel worker/lifecycle 的运行用例
DMA/VMO 对应 mapping、buffer、resident/VMO 工作流;验证失败句柄、最后 owner 和失效后真实访问行为
class/模块公共面 consumer 回归、test_pc_module_boundary、generic 模块加载与 embedded 接入
总线/驱动核心 check-firmware-model、生命周期启动回归和受影响平台构建;平台范围按改动选择

快速运行示例(仓库根目录):

python3 -m unittest tools.tests.test_driver_protocol tools.tests.test_driver_queue
python3 -m unittest tools.tests.test_driver_fence tools.tests.test_driver_workqueue
python3 -m unittest tools.tests.test_pc_module_boundary

需要实际内核执行时,tools/a20 test smoke-driver-gpu-stop-x86_64 覆盖 native worker、请求停止重试、调用排空及真实 VirtIO GPU 退出;make PYTHON=python3 smoke-gpu-access-x86_64 覆盖 generic GPU 模块接入。它们不替代实体 GPU 的停止/故障证据。完整门禁选择见测试与提交。

8. 让下一位维护者接得上

一次公共机制变更应同时交付接口契约、实际调用者、适用配置、关键失败工作流和可复现命令。更新本目录入口、相关运行时/锁契约与实现状态;把已实现、仅编译通过、模型验证和实机验证分开记录。

提交以完整使用场景组织:描述触发条件、最终行为和验证边界。新增原生机制若没有 provider/consumer,或只能靠绕过框架的私有 getter 工作,应先把接入路径做实,再扩大抽象。这样后续开发围绕已有架构增加能力,而不用重新猜测对象的归属和退出顺序。