文档源码: e47887d3a11f; 代码引用: e47887d3a11f. English. 源语言: en; 请求语言: zh_CN; 实际语言: zh_CN; 翻译状态: 已审查.

文档交付不授予软件或实板资格。准确范围请查阅支持和资格记录。

源码旁的权威合同

各层 README 与实现相邻，保持其权威合同身份。以下引用直接读取这些文件，不复制第二份合同。相对源码链接绑定到本站的源码 revision。

物理目录按 ISA 分组 Arm CPU 实现，按厂家分组 MCU 包。系列标识、公共头路径和显式目标名称保持稳定。这些分组表达源码所有权，不是运行时转发层。

历史开发集合保存在证据归档中，附有精确成员身份和恢复步骤。其原始源码与执行范围保持不变；恢复归档不建立当前源码的资格。

arch/
  include/nexus/arch/         public CPU contracts
  arm/cortex_m/              selected Arm Cortex-M implementation
  native/                    host CPU primitives
drivers/
  <kind>/<ip>/               reviewed reusable register-protocol algorithms
soc/
  common/                    cross-vendor SoC collaboration contracts
  native/configure/          Native policy and static emission
  native/drivers/            independent host device models
  stm32/common/              STM32 identity helpers
  stm32/<family>/            maintained STM32 provider packages
    configure/               STM32 family policy, construction and emission
  gd32/<family>/             maintained GD32 provider packages
    configure/               GD32 family policy, construction and emission
tools/configure/
  providers/                 explicit provider map and shared leaf contracts
  tests/providers/<family>/  host configuration tests
io/
  include/nexus/io/           public I/O contracts
  src/api/                   checked face dispatch
  src/mechanisms/            shared bounded I/O rules
  src/controllers/           shared selected controller engines
  private/                   private structures and hardware ports
components/
  <component>/               common mechanisms
  soc/stm32/<extension>/     explicitly selected STM32 extensions

Core

Core 合同

C11 调用者拥有的请求准入、稳定控制身份、完成状态和绝对单调截止时间。不包含设备、OS 调度器、分配或全局登记表。公共接口位于 include/nexus/core。

REJECTED 不保留任何引用。接受的请求链借用 request 和 buffer，直到调用者以 acquire 观察到 SETTLED。SETTLED 的发布是其对请求的最后一次访问。取消／超时绝不撤销借用；排空失败后仍保持 QUARANTINED 存储有效。生产者等待锁存状态，由唯一执行者推进操作。队列适配器拥有外层请求，并按需要使用显式内层提供者元数据。

tests/contracts/core_contract_test.c 实际验证发布、准入、回绕时间运算和终态不变量。主机结果不能证明 MCU 中断顺序或最坏执行时间。

Arch

CPU 本地原语

公共头仍位于 include/nexus/arch/。Arm Cortex-M 实现源码位于 arm/cortex_m/，主机原语位于 native/。ISA 目录是构建期所有权边界；CPU 事实选择一个实现，不设置运行时 CPU factory。新架构需要自身经过审查的实现和编译器合同，不能以占位声明代替支持。

Nexus::Arch 暴露保存／恢复中断屏蔽、准确异常身份、当前特权级、顺序屏障及可选的已启用 DWT 周期快照。它不调用 I/O、OS 或厂商 SDK。一个编译期 Cortex-M 原语实现覆盖 M0/M0+/M3/M4/M7/M23/M33/M55/M85，包括 ARMv8.1-M Mainline 编译配置。STM32F407 与 GD32F470 维持首发平台范围；G474、H743、U575 提供支持矩阵中的明确参考切片。CPU 支持不扩大这些 SoC 或 Board 切片。独立 CPU runtime 装配为全部九核选择 Core/Arch 及可选 OS 软件，不创建 SoC、Board、startup 或 factory。详见 CPU 合同和 runtime 装配示例。

必须在同一 CPU／线程上严格逆序保存／恢复 token。Cortex-M 保持进入时的 PRIMASK，并在相应寄存器存在时不覆盖 BASEPRI/FAULTMASK。只有特权 Task／可配置 IRQ 调用者可以修改屏蔽。NMI 与 HardFault 保持未屏蔽，且不得访问这些受保护元数据。元数据临界区必须短小：不得阻塞、分配、大量复制、调用内核或用户回调。已保存的 Arch token 不是内核临界区 token，也不是 SMP 锁。

屏蔽／上下文查询允许阻塞 I/O 拒绝会阻碍其推进的上下文。只读屏蔽快照区分 PRIMASK、BASEPRI、FAULTMASK；它不是恢复 token，也不冻结中断或安全世界执行。Baseline M0/M0+/M23 查询绝不读取不存在的 BASEPRI/FAULTMASK。即使 CONTROL.nPRIV 描述的是被打断的非特权 Thread，Handler 模式仍为特权。异常号识别当前 CPU／安全状态，不授予内核 ISR API 调用权限，也不协调另一安全世界。DMB/DSB/ISB 具有不同顺序保证，不能证明外设或 DMA 静止。DWT 快照要求显式审查的 CPU 能力和特权访问；能力禁用时不产生 DWT 读取。快照不启用或复位计数器，也不是单调截止时间；回绕／频率限制见头文件。已审查能力是明确 CPU 事实，绝不能通过探测任意寄存器或启用可选单元来推断。

sleep.h 暴露两个显式浅睡眠操作。屏蔽模式的 nx_arch_wait_for_interrupt() 要求特权 Thread、PRIMASK=1、BASEPRI/FAULTMASK 清零且 SCR.SLEEPDEEP 清零。它执行 DSB/WFI/ISB，不改变屏蔽、时钟或 pending 中断。调用者负责最后就绪检查及已启用 IRQ 唤醒源；即使 PRIMASK 已置位，pending 的已启用 IRQ 仍可唤醒 WFI，并在调用者恢复保存的屏蔽后执行。nx_arch_idle_if_unchanged() 则要求进入时全部屏蔽清零，保存 PRIMASK，再以 acquire 语义重新检查对齐的已发布序列；仅仍与调用者快照匹配时睡眠。它恢复准确进入屏蔽；调用者重新检查权威谓词，并为有限截止时间供给 IRQ 定时器。这是单 CPU、单安全状态的发布域，排除 NMI/HardFault、DMA、SMP 和另一安全世界发布者。Native 返回不支持。编译器／模型证据不建立具体定时器、时钟连续性、物理功耗行为或唤醒延迟资格。

cache.h 分别暴露数据 clean、invalidate、组合维护及指令同步。每个范围必须独占完整、已审查的 32 字节行，位于 CPU 地址空间内，并在 CPU/DMA／安全用户之间保持静止。函数不扩展对齐范围、不启用缓存、不刷新无关脏行。cache_control.h 单独拥有 M7 冷态转换。调用者供给一个零初始化控制对象，屏蔽可配置中断，并排除 DMA 及全部其他内存使用者。可信复位或此前成功的自有 clean/disable 建立冷态；仅 CCR 位清零不能证明不存在外来脏行。Enable 拒绝已有启用缓存；disable 清理全部已审查数据 set/way，并在不会弄脏自身栈的叶函数中修改 CCR。部分变更失败后保留缓存／CSSELR 恢复责任。实际指令审计在 O0/Os/O2 验证地址、循环和屏障。其他 CPU 配置不受此冷控制 API 支持；其范围维护能力不暗示已审查的全局缓存转换。mpu.h 分开保留 v7 格式和 v8 base/limit/MAIR 编码器。单区域编程要求已屏蔽的特权 Thread 及关闭的 MPU；写入前检查实际 TYPE 边界与字段。CTRL 和进入时 RNR 保持不变。内存策略和后续 enable 属于调用者。可选 M0+ MPU 使用 CMSIS 确认的 v7 格式寄存器。

security.h 识别已审查镜像状态并编码显式 SAU 区域。只有带已审查 SAU 区域的 Secure 编译器／配置可以编程一个自有区域，且 SAU 必须关闭、特权 Thread 已设置 PRIMASK。API 不修改 SAU CTRL/ALLNS、其他区域、Secure 网关或另一安全世界别名。NonSecure 和单域镜像在不访问 SAU MMIO 的情况下返回不支持。IDAU、重叠规则、内存权限与网关策略位于这些机制之外。

nonsecure.h 使用真实 CMSE NonSecure 非特权读或读写检查，提供 Secure Thread 对完整范围的瞬时观察。若 IDAU 已建立属性，则不需要可编程 SAU。Native、单状态和 NonSecure 镜像不跨域，直接返回不支持。成功不表示 pin、复制、鉴权、排除 MMIO，或冻结映射、DMA 和总线防火墙策略。SoC 与网关所有者必须在访问内存或执行操作之前，分别建立这些条件。

features.h 报告不可变、已审查的 cache/MPU/DWT/security/SAU 能力，不报告启用状态或硬件资格。Native 暴露相同 API，但返回硬件不存在结果；纯编码器仍可使用。扩展 CPU 机制不提供 SoC startup、向量表、时钟树、内存／DMA 路由、Board 接线或 RTOS FPU/MVE 上下文端口。每个新平台必须独立供给并验证这些边界。发布及 RMW 原子操作在 atomic.h 中具有独立合同；CPU 特定回退绝不隐式链接 libatomic。对齐的 acquire/release 字加载和存储不屏蔽 IRQ。M0/M0+ RMW 使用有界、保存 PRIMASK 的互斥机制，并恢复进入屏蔽；全部并发使用者必须是本地特权 Thread／可配置 IRQ 调用者。NMI、HardFault、其他核、DMA 和另一安全世界位于互斥域之外。其他维护核使用编译器无锁 RMW；exclusive 重试不建立固定周期上限。发布前初始化字，并保持其生命周期直到每个读者／写者停止。

Native 模拟递归互斥与 C11 屏障，不模拟真实 NVIC、DMA、物理时序或信号安全中断。Debug 与 Release 都会在非法恢复嵌套时中止。GoogleTest/GoogleMock 在九种 CPU 配置中，以窄寄存器／指令硬件边界编译真实 Cortex-M 算法；普通 ARM 路径内联该边界，绝不链接 mock。Native 测试执行真实递归互斥、严格 token 嵌套和上下文查询。缓存、MPU、安全模型只 mock 外部 CPU/MMIO 操作，运行生产 C 算法，包括在状态变更前拒绝。锁定的官方 CMSIS-Core v6.4.0 头 core_cm0plus.h、core_cm7.h、core_cm23.h、core_cm33.h、core_cm55.h、core_cm85.h、m-profile/armv7m_mpu.h、m-profile/armv8m_mpu.h 和 m-profile/armv7m_cachel1.h 提供经审查的寄存器布局依据。共享的私有 Core 来源不改变 Nexus 公共的上下文、所有权、屏蔽恢复或 cache/MPU/SAU 合同，也不建立新的处理器／profile 支持或物理资格。实际 IRQ 延迟、特权转换、DMA／缓存一致性与 CPU 时序需要 HIL。

类型化 I/O

类型化 I/O 合同与共享机制

公共 C11 接口覆盖 GPIO、UART、SPI、I2C、物理 Flash、watchdog、中断／定时／采集机制、CAN、USB、Ethernet 和选定的 RTC／LPTIM 合同。派生能力矩阵标明实际 provider 模式和已审路由。仅有接口头文件不代表每款芯片提供全部操作，也不授权 PCB 接线。

源码组	责任
include/nexus/io/	稳定公共 Nexus 类型与操作／所有权合同
src/api/	通过所选不可变 face 校验并分派
src/mechanisms/	共享 stream、DMA 排空、唤醒、事务与观察规则
src/controllers/	由 SoC 目标选择的共享 CAN、USB 和 Ethernet 控制器引擎
private/	私有引擎结构、硬件边界和直接 provider 模板
../soc/native/drivers/	实现相同公共 face 的独立主机模型
../soc/<vendor>/<family>/drivers/	精确 MCU provider 与模式实现

每个所选实例拥有一个只读 face，其中包含共享只读方法和独立私有 context。在 32 位目标上，face 占用八字节只读存储；方法表、可变状态、所选缓冲和链接代码的成本分别计算。生成实例使用精确静态存储；显式构造器使用其所有者供给的存储。公共消费者不会获得厂商寄存器布局或 SDK 状态类型。

公共操作校验 face，再分派 ops(context, ...)。provider 可在寄存器热路径内使用私有直接调用。缺失的可选方法返回 NX_ERROR_UNSUPPORTED。不同 provider／模式的方法表可并存，无须替换公共符号。IRQ 入口固定连接所选具体实例，不逐字节查询 factory。

生成的 factory getter 返回已有身份。查找、Platform 启动、请求接纳、service、恢复和停止仍是独立动作。SPI／I2C 总线的控制器与端点身份保持独立。新产品应使用生成的强类型引用头；头文件和 ID 生命周期参见 factory 合同。

直接路径在每项操作允许的上下文中由单一串行执行者推进。请求与传输缓冲由调用者拥有，并须保持到 acquire 观察 SETTLED。取消、deadline 和排空失败绝不撤销借用。provider 在最终 release 发布前撤回硬件、IRQ 和延迟引用；QUARANTINED 存储与清理责任继续保留。所有权表区分直接调用、固定 IRQ 工作、跨任务 adapter、等待和停机。

nexus/io/diagnostic.h 组合复制的 request／stream 观察以及明确已知的生命周期、owner 准入、service 时间和 observer join 事实。结果保留独立 finding 位与未知事实组。request 不变不能证明漏调 service；service 间隔诊断需要同一单调时钟域的显式时间戳和声明预算。该函数及可读原因 key 都不访问实际硬件或改变所有权。SETTLED 不能证明传输成功或 observer 已 join。未结清 stream 数量包含生产者、ready 和消费者借用；普通 cursor 忙不描述私有预投递 cursor。未知事实仍未知；空 finding 掩码不建立健康证明。

stream 的 reserve、publish、acquire、release、abort 和 stop 访问的元数据数量固定，与块数无关。stop 检查未归还计数，不在中断屏蔽期间扫描或撤销借出的块。冷态存储重叠校验检查完整所选块集合，具有不同成本。这些软件复杂度合同不建立物理 IRQ 延迟资格。

DMA 内存完成、外设线上完成和请求结清是不同事实。provider 检查精确 DMA 可达性、所选域、Cache 所有权和真实源撤回。有限模式与连续模式具有不同借用／重装／背压合同。默认路径不增加强制 OS 锁、隐藏驱动任务或通用缓冲池。精确范围由 DMA 与 stream 合同规定。

nx_dma_storage_validate 将调用者显式的完整 reservation 与传输 payload 分开检查。例如，对齐的64 字节 reservation 可以承载17 字节 payload，并独占两条32 字节 cache line。地址和容量必须已经满足声明的对齐、完整 DMA 可达域及可选的完整行几何；不进行取整、分配或隐藏 bounce buffer。调用者提供复核过的几何与独占所有权。provider 仍验证选定模式及真实 cache／DMA 能力，并执行所需维护。取消或 deadline 到期不允许在排空和 acquire 观察结清之前重用存储。

可选 USB 激活合同保留独立不可变激活 face 和已有 provider context。其所选非零端点 setter 是有界控制器动作；外部 Chapter 9 政策拥有配置、回退和普通数据包接纳责任。它不增加默认 worker 或配置事务。公共声明继续规定上下文、部分效果和完整停止义务。

Native、生产寄存器模型、所选 ARM 链接和实物 HIL 分别建立不同证据。独立实例状态和源码目录组织不能证明电气行为、实测时序或任意负载下无丢失。MCU 实物 HIL 仍为 not_executed。

OS 适配器

可选 OS 适配器

轻量 wait/wake 与每对象存储合同。裸机没有调度器；Native 使用 POSIX 线程；FreeRTOS 使用调用者选择的显式静态 TCB、栈及队列存储。不使用通用最大对象池、隐藏执行任务、默认定时器 daemon，也不让设备依赖 OS。

共同公共抽象是等待／唤醒端口。任务、队列、join 和存储 API 有意采用后端专用形式，暴露所选内核的真实控制块要求。产品切换内核时显式适配任务生命周期；平台不提供通用 Task／Queue ABI 或最大存储池。

通知是提示：arm 后重新检查权威请求谓词。内核 ISR 操作验证选定系统调用阈值。Native 任务返回后 pthread 结束；FreeRTOS 包装函数发布完成并挂起，等待外部删除；ThreadX 包装函数进入内核完成路径。唯一外部生命周期所有者必须成功 join，才能回收包装状态、TCB 或栈存储。只有完成提示不能证明内核引用已撤离。应用拥有调度器启动、执行任务、队列深度、公平性及停机推进。

真实 FreeRTOS POSIX 调度器夹具验证主机任务／队列生命周期。默认特权 runtime 根据已验证 CPU 事实选入准确锁定内核源：M0/M0+ 使用 CM0；M3 及无 FP 的 M4 使用 CM3 整数上下文；有 FP 的 M4 使用 CM4F；有 FP 的 M7 使用 CM7/r0p1；CM23/33/55/85 则使用各自 NTZ 端口及独立汇编文件。纯整数 M7 使用已审查、构建派生的 CM3 端口，加入保持 PRIMASK 的勘误 837070 防护；锁定厂商文件保持不变。主机执行不建立 MCU 异常优先级、FP/MVE 上下文切换、栈高水位或时序资格。

运行期 API 要求特权且未屏蔽的 Thread 模式。调度器启动前，锁定 Baseline 端口可能保留 PRIMASK=1，Mainline 端口保留准确 syscall BASEPRI；该阶段只允许所选端口的规范屏蔽状态。数值匹配不能证明所有者身份。故障屏蔽或其他屏蔽状态在对象变更前拒绝；只读调度器查询区分 bootstrap 与运行／挂起任务。Baseline IRQ 唤醒使用 PRIMASK 内核合同；Mainline IRQ 唤醒检查实现边界、优先级位宽及系统调用阈值。

Armv8-M 支持显式 NTZ、Secure-only 及独立 Nonsecure 构建模式。选定 NTZ 内核不分配 Secure 任务上下文，也不暴露跨世界 Secure 函数调用。Secure startup 拥有 SAU/IDAU 与 Nonsecure 协处理器访问；Nonsecure 本地屏蔽不能防护 Secure 发布者。默认任务 API 保持特权；显式 MPU 配置提供独立静态受限任务生命周期和两个无指针用户 delay/tick SVC 服务。必须提供调用者自有受保护元数据及已审查用户链接区域；不暴露通用用户对象池或特权 I/O API。M0/M0+、M7 MPU 以及 MPU 与分裂安全状态组合均被拒绝。选择可选隔离配置前必须查看 OS 合同及当前矩阵。

显式 split 模式选择真实 TrustZone 感知 Nonsecure 端口，及独立链接、带 Nexus::SecureContext 的 Secure 裸机 Runtime。两个镜像使用匹配 CPU/ABI 事实及真实 CMSE import/SG veneers。包括 Idle 在内的每个授权任务，都拥有调用者提供的 NS TCB／栈，以及由不可变可信映射选择的已准备 Secure 元数据／栈。不提供 Secure 堆或最大上下文池。NS 特权内核被信任；SAU/IDAU、startup、向量表、NSC 内存属性和中断路由仍由消费者／SoC 负责。集成前阅读 Secure 配套合同。双镜像链接与主机租约测试不建立物理属性、上下文保持、栈峰值或对抗恶意 NS 内核的隔离资格。

第一次调度器启动要求冷态特权 Thread/MSP 且 FPCA 清零；应用不得在 bootstrap 前留下活动 FP 上下文。MPU 启动防护依据真实来源／异常帧消费受保护的一次性租约。v8-M 中，配置声明的 security = "single" 表示 Arch 状态 0，而不是 Nonsecure。它使用传统 FD/F9 端口返回元组，不具备 CMSE 权限；显式 Secure 使用相同元组，但具有独立 Secure 事实；显式 Nonsecure 使用 BC/B8。生成的 NEXUS_CPU_SECURE_ONLY 宏选择该端口编码，不向单世界镜像授予 Secure 访问权限。

M55/M85 使用真实、感知 MVE 的异常／上下文端口。内核 configENABLE_FPU 开关为 FP 或 MVE 激活共享协处理器寄存器组及扩展／惰性异常帧；CPU 标量 FP 事实保持独立。纯整数 MVE 使用 +nofp 和 softfp 调用约定编译。共享上半寄存器由端口保存；完整下半寄存器与 VPR 保持依赖硬件扩展异常帧，仍属于物理上下文切换验收。此构建合同不建立该行为资格，也不保证跨世界载荷保持。

主机夹具保持锁定内核与 POSIX 端口不变，并使用 tests/contracts/os_freertos_runtime/posix_event.c 作为自有事件支持。端口在发信号／join 之前取消条件变量等待中的 pthread；上游事件支持没有取消清理，可能使已退出线程的 mutex 保持锁定。自有等待在返回与取消时均解锁，避免重复任务 join 死锁。该主机修正不改变 MCU 后端，也不建立 MCU 调度器资格。

维护范围内的执行合同

参见 OS 合同、交付范围及 OS01-OS55 执行台账。新内核准入遵守后端接入合同及主动执行探针；探针通过不登记另一个已支持 RTOS。

即使序列提示已合并，仍检查有限通知截止时间；持续无关唤醒不能延长等待。超时后公共谓词获得最后一次观察机会，因此观察到真实完成仍可返回成功。队列操作保持立即尝试语义，只在阻塞时消耗绝对预算。NX_DEADLINE_NEVER 使用真正无超时的主机等待。

任务创建在修改内核之前验证选定端口的启动帧与对齐。启动最小栈和实测运行期栈预算保持区分。每个返回型任务由唯一外部生命周期所有者 join。不得在适配器背后取消或 detach Native 任务。永久任务及直接通知是显式可选路径，分别具有存储及接收者／索引合同。

可关闭队列使用独立、调用者拥有的控制及每操作等待者存储；原始队列保留最小原生阻塞实现。停机必须关闭准入、保持 owner 推进、完成并排空并 join 生产者、join owner、使硬件 IRQ 发布者静止，最后才能销毁通知、队列与 guard 存储。外部 UART owner 示例展示该流程。

可选 tickless 路径要求显式绑定定时器端口及连续时钟；未供给时正常 Tick 继续运行。诊断采用调用者确定容量的环与 weak 空操作接收端。跟踪、低功耗及任务隔离不表示物理资格。tools/hil/os_acceptance.py 只准备或验证保留的 OS 硬件记录，不操作设备；全部尚未执行的物理用例保持 not_executed。

组件

可选通用组件

显式 CMake 目标组合窄端口：有界 BusOwner、SPI/UART owner、BMP280 核心和 SPI transport、TMP117 单次 I2C、实例级 Log、双 bank commit-last Storage、物理 Flash region 与 Native 文件 adapter、有界 Settings/KV 暂存以及纯 Modbus RTU 解析。未引用的组件代码不进入固件镜像。

Nexus::Settings 在 Storage 上使用调用者暂存、产品分配的整数 key 和显式 schema/容量。只有 commit 写持久化存储；schema 迁移、默认值、授权与 Flash region 保持外置。参见组件合同和开发流程。

通用机制保留在各自命名的组件目录。精确 STM32 扩展位于 components/soc/stm32/，包括所选 F407 handoff／I2S2 和 U575 retained-time／LPDMA／Stop2 机制。其公共头路径和显式目标名称保持稳定。这种源码分组不会扩大支持的芯片、后端、时钟、安全域或实物资格范围。

Owner 具有唯一执行者、准确槽容量、稳定取消 epoch 及调用者拥有的操作。初始化在发布之前连接尚未使用的槽。准入在元数据临界区中移除一个空闲槽并追加一个 FIFO 条目；完成并排空／拒绝归还一个可复用槽。两者的工作量固定，不随容量变化。同一个槽链接服务于空闲链或 FIFO 链；每个 owner 仅有一个 free-head 索引，不增加逐槽存储。达到最后 epoch 的槽永久退役，不使用重复身份重新绑定。UART 显式内层提供者请求使 owner 仅在自身最后一次访问之后释放外层请求。设备及协议不选择 Board 引脚、产品寄存器、默认执行任务或全局查找。产品供给传输、授权、区域、任务策略及预算。

tests/contracts 中的有效回归覆盖并发生产者、延后取消／TC、失败隔离保留、持久化中断及协议畸形输入。持久主机文件不建立物理 Flash 断电资格。

选定网络与 boot 合同

网络组件合同负责定义 adapter 执行、复制 TCP 字节、TX 结果观察和停机。选定 RX 负载借用合同负责定义可选复制／借用协议栈配置，以及独立的公共／Storage target 边界。最后一次 pbuf free 标记借用已可归还；串行 owner 随后精确归还 MAC 借用。仍有引用或归还失败时，stop 保留存储。这些选择不建立 PHY 布线、DMA／cache 或 HIL 资格。

MCUboot 组件合同负责定义选定覆盖配置、显式 Flash 装配、boot／应用所有权图和产品恢复责任。公共控制 API仅呈现通用 C11 头文件。具体 Flash port 类型与私有 boot／profile 头文件不属于该 API 表面。模型与已链接镜像证据不建立掉电恢复或物理 Flash 资格。

准确 SoC 实现

SoC 包与私有 provider

MCU 源码所有权按厂家和精确维护系列划分。stm32f407、gd32f470 等公共系列标识保持不变。维护中的系列描述符提供规范源码目录；目录名称不产生另一份配置权威或运行时登记表。

soc/
  common/                     cross-vendor SoC collaboration contracts
  native/
    configure/                Native provider policy and static emission
    drivers/                  independent host models
  stm32/
    common/                   STM32 identity helpers
    stm32f103/  stm32f407/  stm32g474/  stm32h743/  stm32u575/
  gd32/
    gd32f303/  gd32f470/

每个 MCU 家族拥有 soc.json、routes.json、私有控制器状态、选定驱动源码与显式 CMake target。其 configure/ 包拥有家族能力、准入、构造与生命周期生成。provider 测试保留在 tools/configure/tests/providers/<family>/；共享解析、typed IR、资源仲裁与 bundle 事务保留在 tools/configure/。启动、时钟、timebase、内存与电源代码仍随该家族维护。可复用 IP 算法位于 drivers，只有每个 wrapper 核对实际厂商布局、位定义、时钟、IRQ／DMA 路由和勘误后才可共享。相似外设名称不能证明等价。

native/drivers/ 通过独立主机模型实现公共 I/O 合同，不建立 MCU 时序或电气行为。common/uart_control.h 是跨厂家 SoC 协作合同；STM32 identity 访问属于 stm32/common/stm32_identity.h。两者均不是可复用外设算法。

Board 包授权经过审查的 PCB 绑定。增加 Board 不会自动启用新的时钟树：应选择精确维护的时钟 profile，或实现并验证另一 profile。不支持的晶振、域、模式和硅片修订须明确保留。

实现遵循 provider 指南，所选路由和模式参见派生矩阵，实际证据参见资格指南。CPU 支持、SDK 宏和源码目录存在均不建立整个系列的支持资格。MCU 实物 HIL 仍为 not_executed。

可复用 IP 实现

可复用 IP 实现

该私有源码目录按控制器类别和 IP 实现组织经复核的寄存器协议算法。所选 SoC target 使用私有 include 与精确 ABI 直接编译所需源码。公共 face 和请求所有权仍在 io/；芯片时钟、路由、启动、内存和 provider 状态仍属于精确 SoC。该分组不增加运行时层、注册表、分配、队列或 worker。

源码目录	维护中的算法
uart/uart_v1_channel_dma/	带固定通道 DMA 的 legacy USART
i2c/i2c_v1_async/	经复核的 V1 IRQ／DMA 消息时序
i2c/i2c_v2/	经复核的 V2 轮询消息时序
adc/legacy_adc/	legacy 单次 ADC
timer/legacy_pwm/	legacy 固定 PWM
flash/legacy_flash/	legacy 半字 Flash 编程

STM32F407、GD32F470、STM32F103 与 GD32F303 共享 I2C V1 引擎。前两者保留已复核的 100 kHz profile。8 MHz 低端组合采用标称 80 kHz、优先级零且不调用内核的 IRQ，并禁用 I2C DMA。ES096 2.8.1／2.8.5 与 GD32F30x limitations 2.8.1 要求这些更窄的选择。F4 stream-DMA 布局绝不复用于固定通道控制器。stop 归还借用的通知存储前，已捕获的唤醒发布者必须 join；向量撤回遭拒时保留已初始化 owner，供显式重试。每个 SoC wrapper 核验实际 SDK 寄存器偏移和位定义，提供精确时钟、DMA／IRQ 与可见内存事实，并绑定所选静态状态。寄存器名称相同不能证明另一芯片的路由、引脚接线、时钟频率或勘误策略。

精确 F103 与 GD303 provider 共享 UART V1 channel-DMA 引擎。wrapper 对 legacy USART 和固定通道 DMA 的掩码与布局作断言。dma-tx 拥有一个 TX 通道及显式 IRQ 字节环；dma-duplex 拥有两个通道和调用者提供的有限 RX block。实际线上 TC 独立于 DMA 内存完成。引擎先分离每个来源、观察稳定剩余计数并确认标志，再归还缓冲区。无法证明撤回时保留 request 或 producer loan。正常 RX 通过 owner service 重启，具有明确间隙与背压；不得覆盖 consumer block。在有限边界从 DATA 丢弃的字节会记为丢失。该引擎不隐含循环接收或缓存合同。

只有硬件协议相同时才共享逐字节操作。冷态校验、NVIC 撤回与芯片资源保留在 SoC wrapper。不同协议或勘误需要经过复核的实现或显式窄能力；不得向共享热路径加入猜测性的家族分支。STM32 identity 访问保留在 soc/stm32/common/stm32_identity.h，跨厂家 SoC 控制合同保留在 soc/common/uart_control.h。

CMake 仍是唯一源码图。未选算法不得仅因文件存在于该目录而参与编译。审查所选源码实际链接保留和资源成本。寄存器边界模型测试真实引擎与 wrapper，包括拒绝、错误、取消、排空失败和实例隔离。分别编译每个选定 ARM 实现。Native 模型与链接后的 ARM 镜像建立不同软件性质；时序与电气结论仍需物理执行。参见执行预算和 provider 指南。

私有实现边界与参考配置由 STM32F103、GD32F303、STM32F407、GD32F470、STM32G474、STM32H743 和 STM32U575 维护。这些链接绑定当前站点源码版本。

Board 包

经过审查的 Board 事实

Board 包记录 PCB／来源身份、精确 SoC、晶振、已审控制器绑定、安全初始电平、保留资源、资料来源，以及明确未知的电气事实。它复用所选 SoC provider，不复制驱动或厂商 SDK。

boards/<board>/
  board.json                  reviewed facts and permitted bindings
  README.md                   source, connector and qualification limits

私有 PCB 包属于外部产品仓库，通过 board_package 选择。维护中的公共包通过 board 选择。系列标识须独立于厂家的物理目录。Board 声明不能改变芯片内存几何，也不能启用未维护的时钟 profile、DMA 路由或控制器模式。

从精确料号和少量已审路由开始，再遵循 Board 接入指南。JSON 语法有效不能证明器件装配、连接器导通、电源或物理时序。未检查的 PCB 修订和跳线仍为未知；软件夹具不建立真实 PCB 的资格。MCU 实物 HIL 仍为 not_executed。