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

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

保持清晰而窄的分层边界¶

所有者	必需责任
Arch	精确 CPU 原语、特性事实和 ABI；不拥有 PCB 或设备注册表
SoC	完整型号、内存、时钟、IRQ／DMA 路由、复位／启动和私有提供者
Board	经来源审查的接线、晶振、安全电平，以及真实未知项
I/O 提供者	公共操作合同、私有状态、准入判定和最终排空
组件	调用者拥有的存储、有界算法和显式窄端口
外部产品	角色、任务、队列深度、恢复、Flash 预留和发行

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

确定源码归属¶

FIG-31 对私有控制器工作作归属判定。箭头表示维护决策，不是运行时调用。共享需要每个选入芯片的寄存器布局、位含义、访问顺序及复位兼容性证据，并显式处理其勘误。名称相似或编译成功不能建立这些证据。尚未复核或不兼容的协议保留在精确 SoC 实现中。

变更	源码归属与必需检查
公共 I/O 合同或可移植 I/O 规则	`io/`；保持公共所有权与失败合同
可复用寄存器协议算法	`drivers/<kind>/<ip>/`；每个 SoC wrapper 确认实际硅片合同
料号、内存、时钟、复位、引脚、IRQ 或 DMA 集成	精确 `soc/<vendor>/<family>/`；事实、配置策略与私有 C 保持各自职责
私有 SoC 协作辅助代码	最窄的已复核 SoC 范围；`soc/common/uart_control.h` 跨厂家共享，STM32 identity 访问则属于厂家特定范围
外部器件、协议或产品策略	按接入合同放入既有组件端口或外部产品

SoC target 通过显式 CMake 条目和私有 include 选择共享源码。driver 目录不选择路由、时钟 profile 或 ABI，目录存在也不增加维护中的模式。不得只为匹配源码目录而引入运行时转发层。选定的私有编译期 port 可以在该共享编译单元内部绑定已审查的官方操作；单独编译的 wrapper 中的宏不能改变它。保留操作宽度、读取副作用、命令原子性和撤离顺序；有界官方操作范围是当前实例，不是全面替换为 HAL 的承诺。

按可评审的顺序实现¶

准备固定源码与递归依赖。改变生产实现前，先定义新行为、支持模式、公共所有权义务和拒绝边界。
对新行为或修复，为当前生产路径新增并执行有意义的 RED GoogleTest／GoogleMock 合同。保留实际命令、非零执行及预期失败断言。等价重构保留实际 old-GREEN 源码／二进制快照、适用回归及真实默认操作探针，不伪造 RED。通过 mock 测试 MMIO／CPU／依赖端口；Python 解析器行为使用标准库 unittest。工具缺失或只有编译错误，不能当作预期的行为 RED 结果。
添加精确 soc.json/routes.json facts 与来源说明。使用共享 CPU resolver，不重复 CPU flags 或推断可选特性。对于仓库内 family，MCU 实现放在 soc/<vendor>/<family>/，并在维护的 family descriptor 声明规范 source_directory。公共 family 标识独立于目录。CPU 实现源码归属对应 ISA，例如 arch/arm/cortex_m/；只有核对每个参与芯片合同后，经审查的跨厂商寄存器算法才放到 drivers/<kind>/<ip>/。跨厂商 SoC 协作留在 soc/common/；STM32 身份辅助留在 soc/stm32/common/。
对于仓库内 family，在 SoC 包根目录添加仅含数据的 descriptor.py（Native 使用 soc/native/descriptor.py），放在 configure/ 包之外。在 tools/configure/providers/descriptor.py 的中央显式映射加入精确模块，复用冻结的 FamilyDescriptor，不建立急切加载的并行注册表。生产配置包放在 soc/<vendor>/<family>/configure/（Native 使用 soc/native/configure/），配置测试放在 tools/configure/tests/providers/<family>/。定义支持模式、数值限制、构造、回滚和 IRQ 连接。返回显式冻结的 Construction 记录，包含私有状态类型和初始化失败后的清理责任。初始化和停止动作使用构造合同中的 DirectCall，这些字段不接受原始 C 表达式。公共生成器不应推断 family 名称。不支持的模式拒绝，不提供运行时注册或插件发现。
增加显式 CMake 目标与私有 SDK 依赖。更新解析器声明的重新配置输入，以及 Source SDK 的必需文件闭包。
实施最小正确生产变更。定义不可变公共 face，共享只读 ops，并使用独立 context。复用 Nexus 公共类型，厂商结构与具体存储保持私有。复制厂商状态机前，先审查官方 HAL/LL 复用。时间、回调、取消、私有依赖与逐模式比较遵守官方驱动边界。
对真实提供者执行 GREEN。按模式需要验证无残留效果的拒绝、接受后的借用、取消／截止时间、排空失败、隔离保留、停止／重启和实例隔离。
保持合同通过再重构。链接精确 ARM 夹具，验证实际资源、处理函数保留、向量表字节和未选择驱动裁剪。验证独立搬移后的 SDK 消费工程，并将实板工作记录为未执行。

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

每个 SoC 的 configure/ 包中，contract.py 拥有模式能力、ABI／限制与系列准入策略。相邻模块直接导入该合同；__init__.py 将其与构造器、emitter 显式导出。叶模块 providers/common.py 拥有校验辅助函数与不可变 Construction；叶合同及公共辅助模块不导入顶层 resolver 或 emitter。selection.py 检查跨域选项、时钟和 IRQ 策略；ir.py 拥有具名不可变决策及其单向 JSON 投影；matrix.py 编排支持目录。descriptor 的 configuration_modules 属性将固定 package、contract.py、bindings.py、emission.py 路径与显式声明的 configuration_helpers 及所选本地 descriptor 文件合并。这些源码属于重新配置输入和 Source SDK 源码闭包。迁移元数据时保留 family record、顺序和公共选择。单次 descriptor.maintained() 查找不得导入另一 family 或 configure 行为；显式枚举及 snapshot/SDK 清单可以按要求加载全部纯数据 descriptor。

私有 timer_capture_impl.h、advanced_pwm_impl.h 和 uart_fifo_impl.h 模板允许每个 translation unit 只有一个 specialization。所需的具名导出、寄存器、clock、IRQ 和数据绑定缺失时在编译期拒绝。FIFO 模板接受深度 1..16，RTS/CTS 选择为 0 或 1；选择流控时要求相应硬件 flow binding。wrapper 拥有的 binding，包括 ops 名称及 include 之后的 clock-readiness 使用，保留可用。调用方显式定义的 read/write port 保留；清理只移除模板拥有的 helper 和默认宏。逐个审查 specialization 的实际编译、导出表和运行时合同；模板 guard 不建立硬件时序资格。

tools/configure/contracts.py 负责不可变的控制器类别字段、factory 类别顺序和公共头文件映射。编写、选择与 factory 消费同一份元数据；精确 SoC 能力仍归家族合同负责。已审查的事实选择、内存预算、Flash 布局和源码依赖具有冻结的具名阶段结果。一个冻结的设备图结果在最终装配之前完成控制器、端点、USB FIFO、SPI face、ADC trigger、资源和 DMA 决策。它的局部校验构建过程仍可使用字典；这个阶段边界不代表每个 normalizer 都已拆成独立的类型化阶段。

外置 SoC/provider 包契约¶

本节说明当前迭代中 IT-P01–IT-P08 引入的显式包契约。实现与实际验收见原任务记录。契约本身不建立可用芯片、Board 路由、安装版 SDK 结果或物理资格。新增内容不改变已发布的 v0.2.1 归档；对应 SDK 取得实际验证前，使用包含包实现的开发源码。

装配通过相对其 TOML 文件的 soc_package 显式选择包。既有 board_package 独立选择 Board facts。不通过包扫描、自动下载或可变全局注册表选择实现。外置 family 不得替换已有仓库内 family 身份。

包输入	合同
`nexus-soc.json`	严格清单，包含 `schema_version`、`interface_version`、`id`、`version`、`family` 和 `vendor`
`source_directory`	相对包根目录的 SoC 源码目录，包含 `soc.json`、`routes.json` 和 `CMakeLists.txt`
`configuration_directory`	相对包根目录的显式配置入口，包含 `__init__.py` 和选定 provider 模块
`inputs`	相对普通文件路径到 SHA-256 的映射，覆盖选定 facts、配置代码和构建输入，包括必需入口文件

第一版契约的 manifest schema 和 interface version 均为 1。路径和摘要用于准入，不定义目标，也不替代 CMake 源依赖图。未知字段、重复身份、路径越界、不允许的链接、缺文件、不支持的接口版本或字节变化必须拒绝，不回退到仓库内 family。配置拒绝后不得留下部分可用 bundle。

interface_version 是兼容准入门槛。version 是包的审计身份，不是 consumer 请求的 expected-semver 约束。包自有的 vendor 源码和锁须声明到 inputs；现有 soc.source_lock 指向 Nexus 管理的依赖，不自动验证任意外部 Git 仓库。

包的配置代码和 CMake 是显式选择的受信任主机代码，不是固件执行的数据。将其身份一次解析为不可变 package context，贯穿 facts、selected contracts、资源校验、静态生成、能力查询和构建选择。查询不得解析一个包，而固件编译选择另一个包。

configuration_directory 内声明的 Python 模块经摘要校验后，从源码急切加载。后续相对 import 复用已声明且已加载的模块；不把未声明的文件系统回退或 bytecode cache 作为包输入。绝对包路径可含空格；CMake 特殊字符会明确拒绝，不会传入生成的构建语法。

选定 SoC 目标私有连接 SDK、startup、system 和 linker 输入。公共 I/O 保留 Nexus 类型和静态 face。普通构建保留一个 Nexus::Config；安装版 Source SDK consumer 显式提供外置包，不得回落开发 checkout。路径搬移、断网消费、接口版本拒绝和独立包夹具属于软件退出；真实 PCB、DMA、clock 和电气行为需要 HIL。

_FactResolution 按 Board 的完整料号引用该 SoC 中选定的只读 variant 视图；不另存一份料号或 variant 决策。公共字段校验器直接接收 Mapping 和明确的 list／tuple 容器；JSON 输入保持相同的严格字段、类型及取值域检查。Provider 直接消费这些不可变容器。

区分事实与准入策略¶

精确 soc.json variant 提供物理 Flash 起始地址、大小、擦除块和 RAM 域。每个家族的 contract.PARTS 通过冻结的 PartPolicy 显式准入完整料号：封装与可选内存域 allowlist 是软件策略，不是重复的容量表。未知料号、不同封装或与物理事实不一致的可选域均拒绝。

校验覆盖事实包中的每个维护变体，包括当前装配未选中的料号。每个变体采用相同的封装、Flash 几何、内存重叠、DMA 可达性和 PartPolicy 检查。选择过程返回已有的所选事实；不会修复错误的未选料号，也不会复制另一料号的几何。

添加构造器前，沿以下维护中的输入核对新增料号或模式：

输入或投影	维护者检查
`soc.json` variant 与 `routes.json`	精确物理几何、引出 pad、路由来源和有限模式 allowlist
家族 `PARTS` 与 `PartPolicy`	显式完整料号、已复核封装与可选放置域
`normalize_clock` 与 `clock_plan`	精确家族实现所选 profile 及经复核的时钟域关系
`i2c_timing_clock`	`I2cTimingClock` 携带所选内核与外设时钟边界，以及是否要求显式 timing；电气假设仍由装配编写者提供
所选限制、格式和硅片策略	元数据属于精确选定 owner；缺失复核保持明确，不因此准入模式
`PhysicalPartIR`	查看同一组冻结的料号、封装、Flash 与内存事实；不增加 JSON 或配置身份字段
`ControllerIntegrationIR`	复用规范资源 claim、DMA lane、IRQ 选项／profile、时钟、引脚及精确 SoC 硬件绑定
家族 `UART_FORMATS`、`STREAM_GEOMETRY` 与 `ENDPOINT_POLICY`	显式经复核的格式、stream geometry 与 endpoint 能力；厂家别名或名称前缀不选择策略
生成的静态 C 与私有 provider	消费已校验数值，并保留独立 SDK／寄存器断言与运行时失败检查

F407 Flash 生成展示了该边界：所选 sector 数组与只读 geometry 来自已校验的 result.flash.erase_blocks、起始地址和大小。C SDK 断言仍核对物理基址，独立寄存器模型测试保留参考几何。删除重复生产表不会让配置取代硬件校验。

维护中的七个 MCU 家族都通过 memory.flash_geometry，从已校验事实生成只读 Flash geometry。六个家族保留既有全局 geometry symbol；F407 生成所选静态 geometry。Native 仍是主机模型。精确源码与独立维护的测试 oracle 仍须执行适用的 provider 和最终链接映像检查。

ConfigurationIR.physical_part 引用已有的冻结 Flash 和内存对象。ControllerIR.integration 组合权威 ResourcePlanIR 资源申领记录、DmaTopologyIR 通道、IRQ 选项／配置、时钟计划／输入和选定引脚。家族声明了 ControllerBinding 时，它会引用该记录。它的 clock_hz 仅表示配对的标称 APB 输入；缺失值不会猜测，已审查的频率边界来自 clock_plan。固定且经过审查的 SDK 地址、掩码与 Native 模型事实仍是显式叶子数据；它们不独立选择路由、owner 或时钟。维护中构造器的消费审计检查这些选定记录与能力投影；它不引入新的路由 resolver，也不建立最终集成资格。

家族策略 hook 仍是声明的配置输入。H743 经复核的时钟域关系与所选 Flash linker fragment 位于其 configure/ 包；通用工具仍拥有解析、typed IR、资源仲裁与原子发布。hook 不得创建第二份源码图，也不得静默选择不同料号、路由或 profile。

成对 F407／GD470 控制器的 binding、DMA vector map 与具体 secondary controller hook 位于各自 SoC。公共代码消费所选 typed integration，并保留资源 lease、固定 IRQ wiring 和 drain 顺序。耦合 personality 与命名引脚状态同样要求显式 provider 策略。跨 Board／backend 资格仍属于既有 OS 合同；搬移家族机制不会扩大已准入组合。

只读工作包视图将精确维护模式关联到 resolver 夹具、所选 ops 源码与已审生命周期性质。视图条目用于导航，不是已执行测试或新增支持声明。实际适用门禁需要另行运行。

硬件行为使用 C 实现¶

固件机制使用 C11，启动和 CPU 上下文等位置保留必要的汇编。Python 在开发主机上运行：校验手写输入、解析资源，生成静态 C/H 声明、实例、typed factory getter、固定 IRQ 入口连接及明确的类型化调用。MCU 执行编译后的固件，不包含 Python 解释器。

寄存器读写、硬件准入、等待、pin/clock/IRQ/DMA 取得、回滚、停止和恢复应直接维护在具体 C adapter 中。生成的定义可以保留常量寄存器地址和不可变资源数据；固定 IRQ 薄入口可以直接调用所选 handler。不得将这些算法搬进运行时动作解释器，也不得增加 registry、隐藏 worker 或强制锁。通过硬件端口使用 GoogleTest/GoogleMock 测试生产 C 算法；Python unittest 验证配置和静态连接。

已审查的 Native 和七个 MCU 家族增量包含维护范围内的冷态路径。共享增强 SPI 准入在取得资源或设置启动失败标记之前执行只读 C 检查；H743 恢复在重新开放运行时域并取得租约之前检查准入。无用的硬件生成器和未使用的默认 MMIO 宏已删除。审查完整的启动／失败／停止／恢复路径，包括共享 owner 和可选保留组件。某个构造器中的一次 DirectCall 不能证明整个家族或全源码已经完成。精确实现与执行范围继续记录在交付完善台账中。

编写按模式区分的只读配置和精确大小的可变存储。C prepare 函数在产生效果前校验上下文与外部所有权；C close 函数在接触已有 provider 前验证自身收据。空收据必须保持未取得的状态不变。部分准备后，close 必须保留每个尚未完成的引脚、时钟、IRQ 或 DMA 权利，直到读回证明已经归还。既要测试外来空收据，也要测试真实的部分取得收据；还要测试调用者已停止公开外设后的清理。避免重复的持久引脚快照或容纳所有模式最大状态的联合体。

将 schema 字段和数值策略留在主机校验中。将运行态 MMIO 读取、时钟检查、发布者汇合、等待与恢复留在 C 中。在既有家族 descriptor 和显式 CMake target 中声明每个新增配置辅助模块及私有 C／头文件输入。主机模型成功不能替代实际 ARM 链接、迁址 SDK 消费者或物理工位执行。

H743 fixed-run power 通过 power.controllers 引用选中的逻辑控制器 ID，ID 无须命名为 bus4。修改控制器名称时须同步修改端点和 power 引用。这仍严格限定为单个 SPI4 finite-DMA、baremetal、HSI64/cache-off；改变逻辑名称不会准入另一物理控制器、时钟配置或后端。

审查性能与所有权¶

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

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