当前系统架构

目录与责任

层与目录

拥有的责任

依赖边界

core/

中性结果、绝对 monotonic deadline、caller-owned request 状态

C11；无 Board、RTOS、SDK

arch/

编译期 Cortex-M/Native 原语、异常／特权／掩码查询、中断保存恢复、屏障、cycle snapshot；显式选入的 Cache／MPU／SAU 与 Secure CMSE 权限观察

无 SDK／OS／SoC 政策；原语编译与整平台资格分别记录

soc/<family>/

F407、F470、G474、H743、U575 的精确内存/clock/IRQ/startup、timebase、typed controller 实现

私有 SDK 与私有 provider storage；各家族只开放已维护模式

boards/<board>/board.json

精确型号、已审 route、晶振声明、safe initial、来源与未知 PCB 项

只读资源包；不创建产品任务

io/

typed 多态合同、共享操作表、DMA/stream/wake；可选 CAN、USB、Ethernet 与高级 timer 合同

公共头不含厂商类型；Native 是行为模型

os/

可选 wait/wake、按对象静态 task/stack/TCB/queue 适配

driver 不依赖 OS；不创建应用 worker

components/

显式选入的 owner、BMP280、Modbus、Storage、Log 等通用机制

通过窄端口访问设备、时间与外部政策

tools/、cmake/

严格输入解析、单份生成结果、源码 SDK、ELF/资格/HIL 工具

CMake 是代码依赖唯一权威

外部应用工程

产品 composition、任务、策略、布局、预算、恢复与业务

pin 一个明确平台版本，拥有实际执行进展

SoC 按 controller kind/mode 组织 translation unit，同一实现可服务多个独立实例。 选入一个 UART 不会默认驻留所有 外设、RTOS 队列或最大对象池。启动与 system source 是显式 firmware 输入，不依靠 静态 archive 中未被引用的弱符号来拉入正确 reset/vector。强 provider IRQ 只随所选 实现进入镜像，未使用实现由 section GC 清除。

CMake 从同一 resolved 结果读取选中的 controller kind/mode，仅查询选择事实； 源码集合仍由各家族 CMake 维护。未选择的驱动不参与编译，端点所需 base driver 按组合补齐。STM 空配置不编译外设驱动；GD 保留 system/timebase 所需的基础 SDK 源码。最终 section GC 继续消除未引用函数，编译裁剪与镜像裁剪分别验证。

G474 的 HSE24/170 MHz 参考配置维护真实生成 factory、时钟／GPIO／LPUART／EXTI 算法，以及 empty／GPIO-UART／selected-EXTI 的裸机／FreeRTOS ARM 夹具。 PA0/PA1 EXTI 使用独立 caller-sized event ring，并拥有自己的中断源撤回责任。 空配置没有 GPIO／UART provider；选中 LPUART 的 IRQ91 和系统 TIM2 的 IRQ28 实际绑定到向量字节。FreeRTOS 保留真实 SVC／PendSV／SysTick，170 MHz 时钟和 1 kHz Tick 对应 reload169999。启动先拒绝被占用的 LPUART 控制寄存器，再改动 系统时钟；失败构造对象进入逆序清理，撤销失败仍保留时钟／引脚／状态责任。 这些是独立开发证据，未建立参考 PCB、实板时序或 ThreadX G474 支持。

H743 与 U575 分别增加 M7／M33 的具体 SoC 装配。H743 维护 LDO、固定 HSI32／HSI64 × Cache off/on、TIM2、PB0 与 USART3 PD8/PD9；UART RX 仍为 IRQ bytes，TX 可选 IRQ 或有限 DMA。U575 默认 Platform 维护外部已确认的 TZEN=0、 SWAP_BANK=0、MSIS4 MHz、Cache off、TIM2、PC7 与 USART1 PA9/PA10。 这两类 Platform 均维护裸机／FreeRTOS，不从芯片事实自动派生其他外设支持。 H743 在主 RAM 可写前执行独立的有界电源入口。U575 另有无 OS 的 TZEN=1 双域参考：两个 Runtime 镜像、冷归属 owner 与同步 CMSE GPIO gateway，独立于 TZEN=0 factory。两条 U575 路径都不修改 option bytes，双域参考要求外部预先 完成其启动配置。精确范围见 SoC 完善合同 与 U575 双域合同； 初次执行记录 保留历史资格， 扩展执行记录 单独记录后续证据。

Board 不复制 SoC 驱动。GD32 的 I2C/PWM/ADC/EXTI route、STM32 的高级控制器 route 可以在明确标为软件测试夹具的外部 Board 包中编译／链接；这不意味着三块参考 PCB 已核对相同 connector 和电气。默认 Board 仅绑定已有来源的路线。

构建与配置

当前配置链：严格解析与原子bundle进入唯一CMake目标图

当前图的输入/产物关系见FIG-03及源码依据。 软件证据与物理资格分别取得，见FIG-11。 以下简图源仅保留为历史迁移输入，其箭头不能表达当前HIL准入或验证已发生。

历史构建简图源：

flowchart LR
    S[精确 SoC facts/routes] --> R[严格 resolver]
    B[Board board.json] --> R
    A[外部 assembly/layout] --> R
    R --> G[原子 resolved/bindings/linker/budget]
    G --> C[CMake 显式 targets]
    V[锁定私有 SDK] --> C
    C --> E[真实 ELF/BIN/map]
    E --> M[LOAD/RAM/MSP/heap 门禁]
    E --> Q[clean-source 软件证据]
    Q --> H[独立实板资格]

一个 assembly 选择 Board、clock profile、OS backend、控制器实例、有限 mode、 容量、IRQ 优先级、endpoint 和预算。生成器只生成静态硬件装配，不生成任务、业务 代码或软件依赖图。未知键、失效输入、非法模式、引脚／IRQ／timer 冲突、越界容量 都会拒绝；失败重配置使旧 bundle 失效，不静默使用上一次成功结果。

SoC/Board 事实采用 JSON，使用者编写 schema-2 TOML。严格 resolver 产生不可变 typed IR；各生成器消费同一结果。resolved.json 是该结果的序列化，不能作为手工 配置回填。迁移期 schema-1 JSON 夹具有显式入口，不与 TOML 混合叠加。

IR 身份、预算和各类 controller options 使用冻结 record，IRQ 为嵌套 record， ADC channels/sample times 为 tuple；完整 JSON 事实投影仍保留只读 mapping， 不能声称所有字段均有名义强类型。tools/configure/providers/<family>/ 明确 拥有 ABI、mode→implementation、DMA 路线、trigger、共享 IRQ 与 CS 合同，以及 constructor/rollback/IRQ 和系统时钟生成。公共 resolver 保留 schema、事实、 资源、输入身份与输出，公共 binding 编排 Nexus face 与统一生命周期进度。 新增 SoC 需显式登记真实 provider 模块并维护 CMake/SDK 必需文件；未知 family 和 mode 拒绝，不继承 Native 或 Cortex-M4 默认值。普通 Board 复用已有实现， 不复制驱动；文档矩阵不能反向决定配置。

不可变 family descriptor 统一配置入口、依赖身份和 SDK 必需 payload；controller descriptor 复用精确寄存器基址、IRQ、DMA 和引脚绑定事实，生产 C 的 SDK 静态 断言仍独立核对。clock.source／input_hz 表达 HSE、HSI 或 MSIS 等真实来源； 旧 hse_hz 只在解析入口归一化，不为内部振荡器虚构外部晶振。复杂芯片用 dma_engines 分别表达实际可达性，不用一个布尔值掩盖不同 DMA master 的差异。 这些是构建期事实，不新增运行时 registry、查询层或第二份源码图。

CMake 中 Nexus::Platform 导出配置、typed factory 和不可变接口；SDK headers 和 provider storage 只对实现与生成 binding TU 可见。公共消费路径没有厂商 SDK ABI。 外部 firmware 通过 nexus_add_firmware() 显式装入 startup/system/linker 和资源校验。

固定对象与执行

CPU 原语、特权、中断屏蔽和 FreeRTOS 启动合同见 Cortex-M 架构接入。Arch 按编译期目标选择实现，不使用运行时 CPU factory；设备 typed factory 与共享多态方法表保持。F407／F470 的首发模式 和 G474／H743／U575 的有限纵切片分别维护，九核 CPU 软件层的模型/编译不替代 具体 SoC 集成或物理验证。

独立 CPU runtime 读取外部 runtime.toml 与显式 cpu.json，复用同一冻结 CpuProfileIR 和生产 CMake targets。nexus_add_runtime(ASSEMBLY ...) 导出 Nexus::Runtime，传递 Config/ABI、Core、Arch、typed I/O face 与选定裸机/ FreeRTOS adapter；安装包用 find_package(Nexus REQUIRED COMPONENTS Runtime) 开放相同入口。该模式没有 SoC、Board、启动、链接脚本或 typed factory。具体 memory/clock/IRQ 资源、设备 provider、安全策略及最终固件仍由外部工程实现。 九核的 FPU/MVE/cache/MPU/DWT/security/SAU 都是显式事实，合法组合和精确 kernel port 经解析器选择，不能靠 CMake cache 推断或覆盖。硬件与产品 qualification 仍独立；单区域 MPU/SAU 机制自身不提供用户 task 隔离或双世界 gateway。 U575 双域参考显式组合独立 SoC 归属 owner 和外部镜像分区，并不是 Runtime 或默认 Platform 自动生成的能力。

ThreadX 是独立的真实内核后端，选入锁定的 Eclipse ThreadX Linux GNU 或 Cortex-M4 GNU port，不复用 FreeRTOS 的配置字段。首批维护三块 F407/F470 Board、Native Linux 及明确的 M4 integer/M4F CPU runtime；其余 Cortex-M port 拒绝。产品通过 nx_threadx_kernel_enter() 进入实际内核，只有真实 tx_application_define 回调 允许启动前创建与回收任务。启动尝试后的异常返回保留全部效果并 fail-stop，不能 回到启动前回收。Linux 使用实际 pthread 与 CLOCK_MONOTONIC kernel timer，但 调用者 stack 参数不是实际 host pthread 栈预算。详见 ThreadX 接入。

当前恢复 factory＋多态接口骨架，生成阶段完成实例构造。每类接口 face 只有 const ops* 和 context*；face 与操作表只读，provider 可变状态及按实例选择的 buffer 独立静态存储。方法接收自己的 context，不通过操作表地址推断实例。

生成 nexus_factory.h 和 assembly-local ID。nx_factory_uart() 等 typed 函数 只返回已存在对象：不申请堆、不启硬件、不查字符串、不加锁。非法 ID 返回 NULL； 取得对象与 nx_platform_start()、请求借用和停止分别执行。静态句柄不是可撤销 session，停机前仍必须结清调用者、IRQ、owner 与通知发布者。

factory 默认 ID 按类命名并以 uint16_t 表达；C typedef 不阻止把另一个类的数值 传入。可显式选择按类 struct reference，防止正常调用混用 ID，或选入只读能力查询； 两者仍返回同一静态对象，不增加运行时注册或构造。能力查询描述已选择的有限模式， 不代替当前状态、PCB 电气或请求 admission。ID 只属于当前 assembly，不作为跨版本 持久化编号。start/stop 由外部单一 执行者串行调用，没有隐藏平台锁；公共 I/O 不统一检查全局 started 状态，启动 失败后的业务退出与清理推进由调用合同约束。stop 可先撤回部分实例再返回 BUSY， 不得把 BUSY 解释成恢复完整运行状态。

冷启动先拒绝可观察到的外部 owner。GPIO 装配先观察全部选中 bank 的 gate， 再检查全部选中 pin 的 mode/lock，最后才保存租约并修改 pin；不能先改一个 bank 再因另一个 bank 冲突而假称未产生效果。控制器路线和 endpoint CS 都属于 同一次检查。共享 bank 的未选中 pin 保持外部所有权。

H743 从可信复位或已成功完成自有 clean/disable 的冷状态建立固定时钟和 Cache 配置，不能仅凭 CCR 关闭位认领未知 bootloader 状态。Arch 冷 Cache 控制对象 保留已取得的 I/D Cache 与 selector 恢复责任；当前机制只维护 M7。所选 TX DMA 仅访问 AXI SRAM，Cache on 时要求完整 32-byte line 的独占借用。提交先取得 PREPARING 借用，再在长中断屏蔽区外 clean；取消不得在准备结束前发布 SETTLED。 平台停止先排空 provider，再撤回 TIM2、clean/disable Cache，最后恢复 HSI divider。任何未清理效果继续由原 owner 持有；这些是冷生命周期，不是运行中变频。

驱动自己的 GPIO stop 保持声明的 safe idle。完整 Platform stop 只有在所有 IRQ／DMA／调用者引用排空后，才恢复原来的选中 pin 租约并释放 gate；恢复读回 失败仍保留对应清理责任。因此完整 Platform 释放不承诺持续主动驱动产品安全 电平。产品需要持续驱动时，应保留平台 owner，或先按外部电源／安全策略退出。 这是资源所有权边界，不是平台内置的产品停机政策。

timebase 只在成功启动后发布有效 epoch。启动先排除旧 UIF，再观察 UG 产生的 新更新；运行期 ACK 拒绝时不累加 epoch，而是使时间失效并有界撤回中断源。 无论中断源隔离是否成功，都保留终止路径的中断屏蔽并调用故障观察端口；观察者 返回后仍停机，不以无效零时间继续运行 deadline consumer，也不释放 request 或低功耗借用。产品可提供独立审查的非返回恢复；正常 stop/restart 或清理重试 不能恢复这条终止路径。读取在同一掩码区内再次确认 epoch 有效，避免 IRQ 在 读取入口间隙使时间失效。旧 deadline 不能跨停机、失败或重启继续使用。

SPI/I2C controller factory 返回真实控制器，device factory 返回 CS/address 端点。一个 controller 仲裁所有子端点；恢复属于 controller，不借用第一个端点 来冒充总线。不同 provider 的实例可在同一镜像中共享公共接口，各自保存操作表 与状态。Native 生成对象不再将多个名字绑定到一个全局模型。

公共函数做有界检查并调用共享表；provider 内部可以直接调用自己的实现，避免在 寄存器热路径反复多态分派。组件通过公共合同接入，应用角色、任务与恢复策略仍由 外部工程拥有。编译选中某实例不代表其硬件已经启动或请求已经完成。

生成器的私有对象按 port、endpoint、CS、buffer 和平台状态分开命名，避免合法 实例 ID 与内部辅助对象共用存储。设备字段按实际 transport 校验；I2C endpoint 只声明地址，不接受无效的 SPI mode、频率或通用 capacity。devices 当前生成 总线端点，components 选择代码库；器件和 owner 实例仍由外部应用显式构造。

路径

资源与责任

GPIO 直接访问

授权 mask；set/reset 一次 BSRR/BOP；toggle 要求单一 writer

UART 直接访问

调用者 request/payload；一个 execution owner；真正 TC 决定 wire 完成

SPI／I2C／Flash／ADC 轮询

明确 CPU-active polling；有限模式；只报告有效完成前缀

UART／SPI 有限 DMA

精确域与通道；零隐式复制；内存和线上独立排空；失败保留借用

UART 接收块

IRQ／IDLE；调用者精确块数组；不可变 consumer loan；可见 loss

ADC 触发块

精确 timer/DMA；每块停机；显式 service 稳定／校准与 rearm；块间间隙

多 producer owner

外部按容量提供 slot/storage；唯一 admission；slot/epoch 防止旧取消命中新请求

OS 等待／唤醒

sequence/predicate 防 lost wake；通知是提示，client 不 service hardware

停机

拒绝 producer→保持 executor drain→结清 borrow/通知发布者→join→逆序释放接口；仍运行的内核保留 clock/Tick，产品决定 park 或 reset

CAN 使用真实三邮箱和共享 filter domain；USB FS 使用显式 endpoint/FIFO/event 容量、PIO packet loan 和独立 48 MHz owner；Ethernet 使用 caller-sized normal descriptor ring、RX loan 和 MDIO 窄端口。它们没有内置协议栈或产品工作者。 timer capture 与 complementary PWM 分离普通 PWM，拥有精确 timer/IRQ/break 资源。SoC 实现、配置可选择路线、Board 授权和实板测量分别核验，不能从公共类型 的存在推断某个参考 PCB 已完整接入。具体范围见支持说明。

可选 UserIoBroker 只实现被特权 kernel gateway 调用的 scalar GPIO read/set-reset admission。调用者提供真实 principal、memory pin/copy/unpin 与有界策略；用户消息 不能选择指针、MMIO 或信任身份。release 失败保留 mapping，cleanup 不重放 GPIO。 U575 独立无 OS 参考通过真实 SG 接入一个固定 NonSecure-world principal，保留 并屏蔽 NS 中断，在静态归属和无并发 master 的前提下同步 pin/copy；输出跨度 预验证成功后才允许 GPIO 效果。CMSE 范围检查只是权限观察，不独自保证借用。 没有通用 SVC、多任务 userspace 或异步用户 DMA transport；软件模型和 ARM 指令／布局门禁不建立物理隔离或电气安全资格。

FreeRTOS 的 lowpower_port = "timebase" 显式选入 F407/GD470 私有浅 Sleep 定时器 适配；默认 custom 保持应用端口或弱 NULL 行为。所选实际 getter 验证固定 PLL、 timebase 与 IRQ 状态，不修复未知配置。共享 timer 保留 monotonic overflow，额外 compare channel 只提供 wake alarm；源撤回失败保留 loan 并 fail-stop。没有动态 clock、STOP/deep sleep 或默认低功耗 worker。软件量化相位模型不等于实测功耗和 时序。详见浅睡眠合同。

UART REJECTED 不借用 request 或 buffer；ACCEPTED 借用到 acquire-observed SETTLED。provider 先 detach，再 release-publish，之后不能读取 request。取消与 超时不能提前释放借用；无法证明 drain 的情况进入 QUARANTINED，保留执行／恢复 责任。TC IRQ 观察时判绝对期限，后到 service 不覆盖较早的完成事实。

STM32 取消保留到实际 TC drain；GD32 可用受控 USART reset 终止 wire interval， 未观察 TC 时保守 count=0，并产生 RX loss。两者都不把写入 DR/DATA 的数量当作 完整发送字节。错误-only RX 和 loss marker 带 NO_BYTE，不能消费旧寄存器数据。

性能与空间

默认 C11 路径无 heap、运行时 registry、字符串查找、隐藏 worker、mandatory OS lock 或 闲置 DMA/copy pool。RX/EXTI queue、OS object、owner slot 和组件 workspace 按 选择的实例配置分配。IRQ 只搬运有界事实，批量读取采用短临界区，ring 热路径不做 可避免的动态除法。

资源工具计算真实 ELF 的 Flash LOAD/footprint、每个物理 RAM 域、MSP、heap 和 未使用 provider 的 GC。O2/Os/O3 与 LTO 的选择依据相同 workload 的实测，不凭 源码行数推断效率。原生测试耗时、汇编数量和真实 MCU cycles/latency 分开；当前 无实板，不能承诺“最低 cycles”或已完成物理时序预算。

固定容量也要测量最坏临界区。Owner admission 使用 free-head 链，提交与可复用 slot 归还为 O(1)，epoch 耗尽的 slot 永久退休。stream 用 outstanding 记录 FILLING/READY/BORROWED 总借用，stop 判断为 O(1)；失败或重复操作不改变计数。 每个 Owner 和 stream 逻辑上增加一个 size_t，不增加 per-slot 存储。实际 Cortex-M4 ARM 编译中 Owner 控制对象为 80→84 B，stream 为 32→40 B，后者包含 64-bit epoch 对齐带来的 padding；slot 大小仍为 48/40 B。冷初始化仍需 构建链、清零和校验 block 重叠，重叠校验为 O(n²)，发生在启动前无 IRQ guard。 这些复杂度不证明实际 cycles 或 IRQ latency，须以同一 ELF 测量。 默认 Owner FIFO 不提供优先级抢占或 deadline 排序；应用必须预算事务长度、 service 间隔及 quarantine 对后续请求的影响。

tools/measurement/interfaces.py 从实际 ELF 审计保留的 face 与操作表。非 LTO ARM face 为 8 bytes Flash／0 bytes RAM，表按 provider 共享；独立状态另外核算。 简单 LTO workload 可能消除整个 face／表，这不是任意应用都可继承的保证。

测试与新版本资格

主机新增合同使用固定版本 GoogleTest/GoogleMock，固件仍是 C11；测试框架、C++ runtime 和依赖 archive 不进入 MCU 镜像。保留已有生产 TU 的 C 寄存器/故障回归， 新增 mock 只替换硬件交互，不替换被测 owner、dispatch 或生成器。

TDD 按 Red→Green→Refactor 实施，新增行为先保留失败证据。commit hook 实际执行 测试并验证全量发现的用例、未过滤的新 XML 和返回码；机械门禁只能证明当前执行， 不能证明所有开发者的历史编辑顺序。代码格式与反斜线 Doxygen 沿用既有规则。

本轮 factory/TOML/多态和 SoC 迭代不能继承此前候选的资格。 初次 SoC 执行记录 绑定其历史 code revision， 不覆盖后续扩展；扩展执行记录 独立绑定对应 源码、执行结果和原始证据。主机门禁、ARM 矩阵、安装 SDK、外部示例与离线 复现各自核验，文档提交不替换被测 code 身份。新候选仍有独立退出条件；全部实板 尚未接入，物理结果保持 not_executed。