装配输入与拒绝规则

人工编写的配置权威是一份 schema-2 TOML assembly。SoC 和 Board facts 仍为维护的 JSON；resolved.json 是输出，不是另一种人工编写入口。CMake 拥有软件依赖。TOML 解析失败不会回退到 Kconfig、cache 变量、schema-1 JSON 或旧生成头文件。旧 JSON 装配作为输入会被拒绝，不保留为另一种编写接口。

解析器创建不可变 AuthoredAssembly 意图。生产消费者使用 resolve_ir() 与具名、不可变的 ConfigurationIR 决策；只有审计和产物边界消费者调用 to_dict()。Typed source epoch 2 与 schema-1 JSON 输出投影是不同合同，其版本声明由源码兼容策略维护；两者均不引入固件元数据或运行时分发。

运行解析器前，先准备固定源码与递归依赖。

完整维护输入

完整 Native UART 装配，由生产解析器解析。
schema = 2
board = "native_reference"
backend = "native"
clock = "model"
optimization = "Os"

[memory]
main_stack_bytes = 2048
flash_load_limit_bytes = 65536
static_ram_limit_bytes = 32768
libc_heap_bytes = 0

[uart.uart0]
binding = "uart0"
mode = "irq"
baud = 115200

[uart.uart0.rx]
format = "bytes"
capacity = 32

[uart.uart0.irq]
priority = 5

选择

含义与拒绝边界

schema = 2

人工编写的 TOML 生成；未知键拒绝

board

boards/ 的维护中直接子目录；必须恰好选择一个 Board

board_package

相对装配定位的外部包路径；与 board 二选一

backend

显式 native、baremetal、freertos 或受支持 threadx 子集

clock

匹配 Board 与 SoC 事实的维护中精确配置

optimization

维护中的优化/调试/LTO 配置；不接受任意编译器覆盖

[memory]

字节预算，以及可选的执行镜像前缀与尾部保留量

layout

可选的 schema-1 物理 Flash 擦除区 JSON 路径，相对装配定位；恰好一个 image 区

[factory]

显式可选强类型 ID 和能力元数据

类别实例表

稳定人工编写的名称、复核绑定、模式与有界选项

SPI/I2C 器件表

关联已有控制器的独立端点身份

[abi]

断言复核 CPU architecture/FPU/float ABI；不能虚构芯片特性

资源检查覆盖实际引脚／AF、控制器、IRQ 系统调用优先级阈值、共享定时器／时间基准、物理 DMA 控制器／流、时钟、准确内存域、模式及端点身份。即使选择项语法合法，仍可能因提供者未实现该路由而被拒绝。解析器绝不静默改变引脚、模式或时钟。

配置与所有权指南说明从 Board 查询、经验证的 profile、人读摘要及有效差异。explain 默认输出人读内容；自动化必须选择 --json。

物理 Flash 与所选镜像

解析输出中的 flash 描述完整物理器件，包括精确的擦除与编程几何。layout 选择包含可执行镜像的物理擦除区。未编写 layout 时，该区域为完整物理 Flash。可写区域和恢复仍由产品负责；此选择不提供 Flash 访问控制或写保护。

layout JSON 文件包含 schema_version = 1 和 regions。各 region 具有 id、整数 origin、正数 size 和 kind（image 或 data）。只能有一个 image region。ID 必须唯一；全部 region 必须互不重叠、位于物理 Flash 内，并从其精确擦除边界开始、结束。这是辅助 layout 输入；schema-1 JSON 装配仍然拒绝。

执行区的前缀与尾部保留量

可选的 [memory] 字段在选定物理擦除区内部保留字节。两个字段均为无符号 32 位字节数，默认值为零。布尔值、浮点数、负数以及大于 4294967295 的值均拒绝。零值字段不写入解析投影。零值保留现有默认布局、链接地址和预算；源码变更仍会改变源码与配置身份。

字段

含义

image_prefix_bytes

可执行向量表之前保留的字节数

image_suffix_bytes

执行加载窗口之后保留的字节数

ConfigurationIR 根据不可变的 FlashRegionIR 物理擦除区和 MemoryBudgetIR 保留量派生执行起点与大小。PhysicalPartIR 仍是物理几何的唯一权威；JSON layout 投影保留该几何用于审计。用户不另行编写执行地址，也不通过 CMake 覆盖地址。

owner       = [layout.origin, layout.origin + layout.size)
image_start = layout.origin + image_prefix_bytes
image_end   = layout.origin + layout.size - image_suffix_bytes
image_size  = image_end - image_start

物理擦除区仍须按擦除边界对齐，且各区不得重叠。其内部执行窗口无需从擦除边界开始。前缀与尾部之和必须小于物理区大小，并留出完整复位向量。派生窗口必须位于该物理区内，地址不得溢出。显式 flash_load_limit_bytes 不得超过执行区大小；默认 Flash 预算采用执行区大小。前缀与尾部的保留字节不计为实际 ELF LOAD 字节，也不改变物理 Flash API。

已复核的偏移及非零保留量配置仅包括 STM32F407VET6、STM32F407ZGT6 和 GD32F470ZGT6。它们要求完整物理擦除几何，执行向量起点必须按 512 字节对齐；即使物理擦除区从复位地址开始也一样。其他 SoC 和外置 provider 包不会因填写这些字段而获得前缀或尾部支持。精确对齐要求和真实厂商向量符号由维护中的配置合同决定；人工输入或产物元数据不能给其他启动实现授予该能力。

例如，这个完整 layout 文件选择天空星 STM32F407VET6 Flash 的最后 384 KiB。通过装配的 layout 路径选择它。十进制 origin 对应 0x08020000；省略的前 128 KiB 不是另一个所选镜像，也不会因本 layout 而获得写保护。

{
  "schema_version": 1,
  "regions": [
    {
      "id": "application",
      "origin": 134348800,
      "size": 393216,
      "kind": "image"
    }
  ]
}

对于偏移镜像或非零保留量，生成的链接检查要求 .isr_vector 位于派生的执行起点、满足对齐、向量表非空且不超过 512 字节，并要求真实厂商符号位于该 section 起点：F407 为 g_pfnVectors，GD470 为 __gVectors。已复核的启动代码由该链接符号设置 VTOR，并执行所需屏障。默认零保留量、复位地址链接保持原有语义。

ELF LOAD 边界、Flash 容量与占用跨度均采用派生的执行窗口。资源检查器会独立核对物理擦除区、保留量、向量字、复位入口，以及所有真实 Flash LOAD 范围是否符合该窗口。ELF-to-BIN 检查从执行起点重建字节，不添加前缀或尾部内容。物理擦除/编程事实和 RAM 预算保持不变；解释擦除几何应使用 flash，不能以 layout.origin 重新编号。

完整的公开执行窗口参考选择 F407 的一个 128 KiB 扇区 [0x08020000, 0x08040000)。512 字节前缀和 1,024 字节尾部派生出 [0x08020200, 0x0803fc00) 执行区，共 129,536 字节，用于向量表与执行 LOAD。该参考通过安装 SDK 链接真实已复核的启动代码；声明的 2,048 字节 MSP 并非实测堆栈峰值。

带显式字节保留量的完整 F407 装配；layout.json 位于链接的公开参考中。
schema = 2
board = "stm32f407ve_sky_qingchun"
backend = "baremetal"
clock = "hse8-pll168"
optimization = "Os"
layout = "layout.json"

[memory]
main_stack_bytes = 2048
static_ram_limit_bytes = 32768
libc_heap_bytes = 0
image_prefix_bytes = 512
image_suffix_bytes = 1024

前缀保留量不会生成镜像头。尾部保留量不会生成 trailer、激活标记或回滚记录。元数据格式、密钥、Flash 权限与恢复策略均由产品提供。平台不会构建引导器，也不负责认证、安装、激活或引导此镜像。

偏移可执行文件仍需要产品拥有的启动路径，在有效初始机器状态下进入其 vendor reset entry。链接、向量检查和 BIN 身份不会执行这条路径。该机制不提供镜像认证、激活、A/B 回滚、Flash 权限或通用运行态镜像交接。裸机或 FreeRTOS 链接只证明各自构建范围。尤其是现有 F407 handoff 保留 PRIMASK=1，startup 不主动解除屏蔽；偏移链接不能建立 FreeRTOS handoff 资格。

检查并生成

从仓库根目录执行，使用自己拥有的新输出：

python tools/configure/configure.py list-bindings     --assembly tools/configure/assemblies/native-uart.toml
python tools/configure/configure.py check     --assembly tools/configure/assemblies/native-uart.toml
python tools/configure/configure.py explain     --assembly tools/configure/assemblies/native-uart.toml
python tools/configure/configure.py generate     --assembly tools/configure/assemblies/native-uart.toml     --output /tmp/nexus-native-config

check 与 explain 不生成输出。generate 发布一个原子自有 bundle；失败使其自有输出失效，不替换无关数据。检查 resolved.json、输入身份、生成的 nexus_config.h、绑定、factory、链接器内存和预算。声明输入变化要求重新解析；不同 Board/backend 组合使用独立构建根目录。

CPU-only Runtime 使用独立人工编写的 runtime TOML 和共享 CPU 解析器。它只生成 Core/Arch/可选 OS 策略，不生成 SoC/Board/startup/factory。不得据此声明完整设备平台。构建合同、接入合同和生产字段模型／schema 拥有详细合法字段；编辑器补全不建立硬件能力。