驱动框架概览
TGOSKits 的驱动框架连接平台设备描述、硬件实现和系统消费者。rdrive 负责发现与类型化注册，rdif-* 表达领域能力，平台绑定提供寄存器、DMA 和中断资源，运行时按设备合同推进操作并维护资源生命周期。框架统一接入边界，不要求所有驱动具有相同的队列、线程或关闭状态机。
1. 框架范围
管理对象包括存储、网络、显示、输入、串口、USB host，以及中断、时钟、复位、电源、引脚、PCIe 和定时器等平台控制器。设备可能是真实硬件，也可能是宿主操作系统消费的 VirtIO 设备。
1.1 设备与平台能力
普通外设消费平台控制器提供的资源；平台控制器本身也可以通过 rdrive 注册。DriverRegister 描述可用探测回调，PlatformDevice 发布实例，DeviceId 和外层 Rust 类型共同定位已注册对象。
时钟提供者被查询后可直接执行控制操作，块控制器交付硬件队列，USB host 继续枚举外部设备，显示对象提供帧缓冲借用。注册表不会把这些能力变成相同的数据收发接口。
1.2 系统边界
ArceOS 的 HAL 与 ax-runtime 组织平台初始化、探测和领域启动；StarryOS 在相关宿主能力上建立用户态设备语义；Axvisor 的宿主模块按需消费平台设备。virtualization/axdevice 与 virtualization/axdevice_base 的 guest 模拟设备属于虚拟化层，不是宿主 probe 自动生成的对象。
挂载策略、IP 路由、Linux ioctl 和 guest 中断注入由各自系统或领域维护。硬件核心不应通过判断当前操作系统来接管这些策略。
2. 架构组成
公共机制按状态归属划分，而不是为每个设备类别建立一套独立框架。下面的结构同时适用于直接控制的 provider、拥有队列的控制器和继续发现下游设备的总线主机。
2.1 组件关系
平台描述经发现后端和绑定层转为实例，能力契约约束实例的操作，运行时将其转换为系统可消费的服务。IRQ 和 DMA 的生命周期跨越绑定与运行期，不能归入一次性的 probe 日志。
图中的运行时是职责概念，不是一个适用于所有驱动的公共 crate。ax-fs-ng::block::runtime、USB Core、显示输入适配和 ax-net::queue_runtime 分别实现不同合同。
2.2 状态归属
每种状态需要有明确所有者。注册身份、资源来源、硬件状态和上层服务状态相互关联，但不能由一张全局设备表代替。
| 状态 | 主要保存位置 | 不能替代的状态 |
|---|---|---|
| 探测规则 | DriverRegister、发现后端 | 实际硬件存在性 |
| 注册身份 | Descriptor、DeviceContainer | 设备已经就绪或尚未接管 |
| 平台来源 | FDT/ACPI/PCI 元数据、BindingInfo | 已申请的 IRQ action |
| 硬件操作 | 驱动核心、控制器与队列对象 | 文件系统或协议状态 |
| 执行与完成 | 领域运行时、事件 handler、等待者 | 全局热插拔事务 |
| 上层服务 | 卷、帧端口、输入事件、设备树、连接对象 | 寄存器和 DMA backing |
drivers/rdrive/src/manager.rs 保存设备所有者，drivers/ax-driver/src/registration.rs 组织绑定发布；具体服务状态保留在消费它的领域，而不回填为另一套注册表。
3. 接入与交付
设备声明、注册、接管、启动和关闭是不同阶段。公共框架提供其中的发现和身份机制，领域代码负责其余阶段的实际状态转换。
3.1 发现和资源准备
Static、FDT、ACPI 后端处理平台描述，PCI endpoint 枚举依赖先存在的主控制器。回调准备资源并创建具体对象；ProbeLevel 与 ProbePriority 控制调度，但不能代替资源提供者可用性检查。
MMIO 地址映射、DMA domain 和约束、时钟复位控制、IRQ 来源解析在不同接口中表达。缺失资源不能通过默认 IRQ、猜测物理地址或虚构频率补齐。
3.2 运行和撤销
消费者按类型查找设备，再按合同直接借用、一次性接管或移交端点。块队列维护者、USB future、显示输入接口和网络 owner 具有不同推进方式；不能把某一领域的“禁止轮询”或“固定 CPU”扩大为全框架规则。
这些节点是源码操作的归纳，不是框架中已有的通用状态枚举。USB 拓扑撤销、块控制器关闭和一次性网络接管分别有自己的实现边界。
4. 文档与实现边界
主架构章节按公共机制组织，具体设备代码作为机制的实现证据。平台专属 寄存器、外部源码对照和诊断记录保留为实现专题，不决定主架构的章节划分。
4.1 公共机制章节
各独立文档维护一个明确的架构部分，避免在总览、服务和系统集成中重复完整的领域内部算法。
| 文档 | 维护的边界 |
|---|---|
| 总体架构 | 组件关系、依赖和状态归属 |
| 驱动分层 | 硬件核心、能力、绑定和执行策略的代码归属 |
| 设备管理 | 身份、注册容器、句柄和子设备发布 |
| 探测与初始化 | 来源、阶段、匹配和错误传播 |
| 能力接口 | 操作、端点、请求和所有权合同 |
| 平台资源 | MMIO、DMA、时钟、复位、引脚与绑定 |
| 中断与事件 | 来源解析、action 注册和事件交付 |
| 运行时与完成 | 队列、异步等待、预算、背压和控制推进 |
| 生命周期 | 发布、接管、回滚、关闭和撤销 |
| 领域服务 | 卷、帧、显示输入及设备树等交付物 |
| 系统集成 | 启动调用位置和系统消费边界 |
| 构建配置 | feature、链接、平台匹配与支持证据 |
| 迁移约束 | 旧入口与当前合同的差异 |
运行时细节以当前领域源码为依据，不为形式对称而假定每种设备都具备相同的工作线程、热插拔或安全隔离能力。
4.2 实现专题
USB 实现专题 将主机、拓扑、异步传输和 RK3588 平台资源映射回公共机制。专题中的 SoC 地址、lane 配置和 PHY 等待不是其他驱动的通用要求。
硬件支持需要区分源码存在、feature 公开、目标编译、初始化成功和真实传输验证。文档描述调用关系与合同，不把静态分析扩大为所有板卡或功能组合已验证的结论。