接入 SoC、提供者或通用组件

使用本指南增加具有明确资源和可测成本的维护实现。新芯片家族或模式需要同时完成行为、配置和构建集成。STM32／GD32 的外设名称相似，不能证明寄存器兼容。

保持清晰而窄的分层边界

所有者

必需责任

Arch

精确 CPU 原语、特性事实和 ABI；不拥有 PCB 或设备注册表

SoC

完整型号、内存、时钟、IRQ／DMA 路由、复位／启动和私有提供者

Board

经来源审查的接线、晶振、安全电平，以及真实未知项

I/O 提供者

公共操作合同、私有状态、准入判定和最终排空

组件

调用者拥有的存储、有界算法和显式窄端口

外部产品

角色、任务、队列深度、恢复、Flash 预留和发行

阅读架构说明、接入合同和提供者装配合同。

按可评审的顺序实现

  1. 准备固定源码与递归依赖。改变生产实现前，先定义新行为、支持模式、公共所有权义务和拒绝边界。

  2. 为当前生产路径新增并执行有意义的 RED GoogleTest／GoogleMock 合同。保留实际命令、非零执行及预期失败断言。通过 mock 测试 MMIO／CPU／依赖端口；Python 解析器行为使用标准库 unittest。工具缺失或只有编译错误，不能当作预期的行为 RED 结果。

  3. 增加精确的 soc.json／routes.json 事实与来源记录。复用共享 CPU 解析器，不得重复 CPU 编译标志或推断可选特性。

  4. 将芯片家族加入 tools/configure/ 中显式维护的提供者映射。定义支持模式、数值限制、构造函数、回退和 IRQ 接线。不支持的模式必须拒绝；没有运行时注册或插件发现。

  5. 增加显式 CMake 目标与私有 SDK 依赖。更新解析器声明的重新配置输入，以及 Source SDK 的必需文件闭包。

  6. 实现最小的正确生产变更。定义共享只读 ops 和独立上下文的不可变公共接口面。复用公共 Nexus 类型；厂商结构与具体存储保持私有。

  7. 对真实提供者执行 GREEN。按模式需要验证无残留效果的拒绝、接受后的借用、取消／截止时间、排空失败、隔离保留、停止／重启和实例隔离。

  8. 保持合同通过再重构。链接精确 ARM 夹具，验证实际资源、处理函数保留、向量表字节和未选择驱动裁剪。验证独立搬移后的 SDK 消费工程，并将实板工作记录为未执行。

组件通过显式总线、GPIO、时间和可选 OS 端口工作。不得创建执行任务、探测设备、虚构应用角色或提供最大对象池。Flash 驱动暴露物理几何；持久化和升级策略仍在外部。

审查性能与所有权

测量所选空镜像和同一夹具启用新模式后的镜像。分别报告 Flash LOAD、Flash 占用范围、各 RAM 域和预留任务／I/O 存储。高频 IRQ 应直接访问固定提供者；接口查找属于冷路径。在合同要求时，准入判定和流元数据操作保持有界，并且不随队列长度增长。

通过的主机寄存器模型只证明其建模的软件范围。新增 CPU、缓存、FPU／MVE、安全或低功耗行为必须建立自己的实际执行边界；平台支持不能仅凭名称推导它们。