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

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

配置产品并推进 I/O

从外部应用教程开始。下面的命令使用同一固定 SDK 或源码检出，并从其源码根目录执行；产品 TOML、任务、缓冲区与恢复策略保留在产品仓库。解析器报告支持的软件选择，不验证连接板卡的电气事实。

选择并比较完整配置

编写完整装配之前先查询可选项。该查询不需要猜测后端或时钟：

python tools/configure/configure.py list-bindings \
    --board stm32f407_qiming_v31 --kind uart
python tools/configure/configure.py init \
    --board stm32f407_qiming_v31 --backend baremetal --clock hse8-pll168 \
    --profile uart --binding uart1 --instance link0 \
    --output /tmp/product-uart.toml
python tools/configure/configure.py explain --assembly /tmp/product-uart.toml

init 拒绝已有文件。empty、gpio 和 uart profile 写出可见的 TOML 值并执行正常解析器；非空 profile 需要显式 binding。被拒绝的路由不会替换为其他路由。采用波特率、事件容量、IRQ 优先级和预算前先阅读生成的 TOML。对外部 Board，init 和 list-bindings 都接受 --board-package 代替 --board。命令相对于工作目录解析包路径；init 将其写为相对于新 TOML 目录的路径。整体移动产品目录树仍保留这一关系。经过复核的 Board 包与产品装配分开维护；包内容和 provider 边界见 Board 接入指南。

解释列出公共 face、模式、时钟、资源、内存域、声明预算和执行责任。list-bindings --json 包含 mode_contracts、资源声明、fact_sources 与 limitations。binding 仍为 configuration-required：后端、时钟和全部实例必须一起通过解析。缺失的物理 PCB 事实仍未知。MCU 查询标为 not_established_by_configuration；Native 标为 not_applicable。

每个候选模式分别列出 resource_keys、occupied_resources 和 resource_scope。轮询模式不会占用备选 DMA 路由。先选 Board 的查询保留已知 SoC 和 Board 预留资源，在未选择后端时不虚构 OS owner。装配查询读取与解析输入哈希一致的事实。选项可能增加要求，因此该投影不能替代完整装配准入。使用精确支持查询区分配置接受、模型、ARM、SDK 和物理证据。

编辑独立的下一份装配后，比较有效变化：

python tools/configure/configure.py diff \
    --assembly /tmp/product-uart.toml --against /tmp/product-uart-next.toml
python tools/configure/configure.py explain \
    --assembly /tmp/product-uart-next.toml --json

两份装配都必须成功解析。diff 报告有效的平台、路由、模式、端点、存储和预算变化；只重命名源文件不构成行为变化。JSON 区分缺失字段和显式 null。以前依赖 explain 默认 JSON 的脚本现在必须传入 --json。编辑器提示仅提供帮助；解析器仍是准入权威。

diff 还把 impacts 分为 factory_ids、public_interface、transfer_contract、execution 和 storage。每项指出有效路径、变更前后值和审查责任。factory ID 变化或重排可能需要修改消费者；新执行者或 DMA 模式需要审查其生命周期和存储合同。这些是配置声明带来的影响，不是实测时序、内存节省或消费者已完成迁移的结论。

冲突诊断指出 authored 文件／key 及争用资源的 owner。修正这些输入后重新配置。不要修补生成 C、削弱 DMA reservation 或隐式改变时钟来让构建通过。配置预算是声明；宣称资源节省前必须测量实际链接镜像。见装配参考与支持矩阵。

自动化可加 --diagnostics-json，在标准错误中取得一条结构化拒绝记录并以状态码 1 退出；成功时的标准输出保持原有格式。人读和 JSON 诊断使用同一错误记录。未知或缺失字段保留上下文和键集合；资源冲突指出资源与竞争声明，包括 owner、mode 和 source。这些记录定位手写输入，不会静默修正输入。CLI 参数语法错误仍使用 argparse 诊断并以状态码 2 退出。

预览维护的软件计划

本轮 plan/artifact 命令、Settings、wait selection 与串口扩展要求使用包含这些改动的开发 checkout。它们不改变已发布的 v0.2.1 归档；安装版 SDK 支持以对应新 SDK 的实际验证为准。

在固定开发 checkout 的源码根目录，先检查既有完整软件计划，再启动昂贵的验证：

python tools/dev/dev.py plan \
    --output-root /tmp/nexus-planned-run-001 \
    --json /tmp/nexus-plan-001.json

在已有父目录中选择新的 JSON 路径；未来执行目录不会创建。预览从维护中的计划派生命令顺序、时限、选择原因、检查器与 preset 元数据以及输入身份。它不执行进程、不安装工具、不使用设备或访问网络。未提供观察记录时，case 数量保持未知，使用预览无需先运行测试。拒绝通过 --preset 过滤；完整的作者计划仍是选择依据。

若要显示此前观察到的 case，先构建选定的 Native preset，再显式使用现有 Native producer 收集 case 列表证据：

python scripts/ci/native_contracts.py --preset native-debug --observe-only
python tools/dev/dev.py plan \
    --output-root /tmp/nexus-planned-run-002 \
    --observation native-debug=build/native-debug/tdd/io-property-inputs.json \
    --json /tmp/nexus-observed-plan-002.json

--observe-only 会执行 manifest 中每个二进制的未过滤 case-list 进程；它不执行测试 case 或 CTest，也不写入执行成功摘要。此前的摘要和快照保留在唯一的 before-observe 路径中。普通 producer 仍执行完整 CTest 与 Google 计划，包括 disabled case。同一快照绑定全部 manifest 二进制、对象编译上下文，以及去重后的当前已生成编译输入、共享依赖和链接文件的保守超集。Ninja 通过原始命令收据提供元数据；预览本身从不启动 Ninja。这些事实绑定当前字节，不证明进行了新编译，也不创建另一套构建图。大小边界与精确收据要求见开发工具合同。

只有显式观察记录中的源码、对象、头文件、归档、二进制、元数据和成功的原始发现收据仍然匹配时，预览才接受该记录。收据必须属于当前构建且晚于其快照。过期、失败、变化或不完整的观察记录会被拒绝；移动后的源码检出或 SDK 需要重新观察。参数化与 disabled 身份原样保留。已复核生命周期目录中的 case 显示其不变量和限制；未复核的 case 保持 unknown，不计算覆盖率。显示结果仅表示“此前已观察，且当前输入匹配”；绝不表示这些 case 在预览期间执行或已经通过。

已知的宿主阶段无需设备。HIL 准备阶段可以展示声明的工装测试与待测项目，但缺少已解析配置时保持 configuration_pending；不猜测路由或站点事实。未知硬件需求保持 unknown，物理状态保持 not_executed。每个预览阶段仍为 not_executed，qualification 始终为 false。仅在不再需要时删除自己创建的预览 JSON。

构建成功后，查询实际捕获的输出，避免猜测哪个 ELF 属于选定配置。将下面路径替换为该次构建实际的 quality/build-provenance.json：

python tools/dev/dev.py artifacts \
    --provenance build/my-board/quality/build-provenance.json \
    --json /tmp/nexus-artifacts-001.json

命令先校验 provenance 与解析身份，再列出源码、配置、产物角色和原始命令 receipt。缺失、变化、陈旧或不匹配的输入必须拒绝，不能生成成功产物视图。可选 JSON 路径必须是新文件。查询不构建或访问设备，也不为当前 checkout、软件或硬件建立新资格。

使用可选 Settings 与联网机制

在装配的组件列表选择 settings，链接 Nexus::Settings。调用者先打开 Storage，再提供 Settings 元数据、独立暂存 buffer、条目容量和产品定义的 schema。整数 key 和复制的字节值保持有界。Get/set/remove 操作暂存；只有显式 commit 写 Storage，close 丢弃未提交变更。未知 schema 或损坏加载是错误，不是空的可写存储。发生变更性 commit 失败后，先重新打开 Storage 和 Settings，观察实际保留的提交，再决定重试。默认值、迁移、授权和 Flash region 由产品决定。详细所有权见 settings.h 与组件合同。

可选 Nexus::LwIP 目标准入组织托管的 X-Gen-Lab/lwip 2.2.1 gitlink 77dcd25a 与固定源码闭包。显式选择前不参与默认构建。它采用 NO_SYS=1，由产品循环或任务推进单一串行 owner，不隐式创建 RTOS 网络栈移植层。它复用 Ethernet frame 借用和有界内存。已审查切片包括静态 IPv4/ARP/ICMP/UDP 和有限 TCP 集成；完整 TCP 连接生命周期、DHCP、DNS、IPv6、VLAN、TLS 和 MQTT 仍是独立退出。源码、SDK、clock、内存和停止前提见联网集成合同。源码准入和开发 SDK 消费不建立软件候选、完整联网平台、ARM 或物理资格。

指定唯一执行者并保留借用存储

factory 返回已有的 typed face。Platform start、请求准入、执行推进、完成、恢复和停机仍是分开的操作。显式选择一种执行配方：

配方	进度责任方	存储与停机责任
主循环	循环调用选定的 service 步骤；固定 IRQ 入口执行有界 IRQ 工作	请求和缓冲区保持有效直至结清；关闭准入、取消或排空、观察结清、join observer，然后停止
独占任务	一个产品任务拥有直接操作；声明的 IRQ 策略仅允许选定的 OS 交互	显式唤醒和 service；任务超时不能撤销缓冲借用，也不能允许销毁任务栈
共享总线 owner	调用者提交有界 slot；一个 owner service 控制器和端点	队列容量、callback 与存储显式提供；关闭准入、排空已接受的 slot 和控制器引用、join observer，然后销毁 owner

这些是应用选择，不是三个隐藏驱动 worker。产品示例位于 nexus-examples：templates/{native,qiming,sky,liangshan}、apps/shared_spi_runtime 和 apps/stream_recovery。使用与平台对应的固定示例版本及其 README。SPI Native 示例与 FreeRTOS POSIX-host 演练范围不同；Native Platform 不接受 backend = "freertos"。软件双 CS fixture 不能证明首发实板存在第二条 CS 接线。

有限请求的 REJECTED 不保留调用者引用。ACCEPTED 借用请求和传输存储，直到 acquire 观察到 SETTLED。取消与 deadline 到期要求向撤销引用推进，并不结清请求。QUARANTINED 保留存储及清理义务。SETTLED 不表示传输成功，也不表示 callback 和 observer 已 join。在栈上放置异步存储或停止 worker 前先阅读所有权。

多个权威谓词共享一个 wait port 时，nx_wait_select 从显式循环起始索引检查调用者 source 数组。它返回观察到 ready 的索引，不取得或消费对应 source。调用者推进下一次起始索引以选择公平性，把每个 publisher 接到同一 port，并负责 service/timer 进度。回收状态前须停止并 join publisher 和 waiter。没有隐式订阅、派发、worker 或资源转移；公共 wait 合同 仍约束 arm/recheck 与绝对 deadline。

对于 stream，消费者显式释放每个取得的块。慢消费者可能按选定模式造成 loss 或因背压停止；provider 不得覆盖未归还的借用块。在借用块与硬件引用排空前 stop 可以返回 BUSY。完整停止后以新的有效生命周期 restart；清除计数器不等于恢复。H743 连续模式演练使用独立的精确 ARM 配置，不声称三块首发板具有相同的连续模式接线。

诊断事实，不改变所有权

nexus/io/diagnostic.h 中的 nx_io_diagnose 组合复制的 request 和 stream 观察，以及明确已知的生命周期、owner、service 时间与 observer 事实。它既不读取实际 MMIO，也不调用 service 或恢复。独立 finding 位可以并存；unknown_facts 保留缺失信息。没有 finding 不构成健康证明。

request 停止推进不能证明遗漏 service 循环。SERVICE_OVERDUE 需要同一单调时钟域的有限时间戳及正的最大间隔声明；时间倒退以 STATE 拒绝。只有成功取得 owner 诊断快照，准入字段才算已知。仅凭 BUSY 不能证明队列满。未结清 stream 块可以属于生产者、ready 或消费者；普通 cursor 不说明私有预投递 slot。应用仍拥有重试、安全输出与复位策略。

nx_dma_storage_validate 将完整的显式 reservation 与 payload 分开验证。例如17 字节 payload 可以放在调用者拥有、按32 字节 cache line 对齐的64 字节 reservation 中。完整 reservation 必须已经满足声明的 DMA 可达域和完整行所有权。该函数不取整、不分配、不 bounce、不执行 cache 维护，也不替代 provider 模式准入。deadline 到期绝不允许在排空前重用 reservation。

可选 owner 观察增加 accepting、queued 和 slot_available。其公共 observation／sidecar 布局已改变，消费方须重新编译。默认 owner 与 provider 结构不增加这些字段。按选定 ABI 测量可选 sidecar 存储，不能假定它没有成本。

日常设备操作计划与资格验收分开

对于 flash／debug，使用已识别的设备文件和实际成功构建的 provenance。Monitor 可以不关联构建：

python tools/dev/dev.py flash --target /path/equipment.json \
    --provenance /path/build-provenance.json --elf /path/application.elf
python tools/dev/dev.py debug --target /path/equipment.json \
    --provenance /path/build-provenance.json --elf /path/application.elf
python tools/dev/dev.py monitor --target /path/equipment.json \
    --provenance /path/build-provenance.json

默认打印计划。实际执行要求 --execute --output 与新建的自有目录。Flash/debug 要求 board/part、镜像、探针序列号及锁定工具/配置字节匹配，不要求串口控制台。Monitor 要求 board、稳定的 serial by-id 和 station lock，但可省略 build provenance；此时记录 image_linkage = unassociated，不表示镜像已关联。Monitor 使用显式选定且主机支持的标准波特率、8N1 和有限时长；默认仍为 115200。未知速率或 TTY 配置不匹配必须失败，不能改用其他速度。主机接受配置不证明物理设备波特率。EOF 或断开视为失败。Debug 绑定 loopback。设备操作失败或取消后保留锁等待明确检查，正常完成释放锁。日常操作成功不建立 HIL 资格。设备未接入前，物理执行记录为 not_executed。性能与 HIL 指南负责采集和资格规则。

对于一次有界 Linux 批处理，在 debug 上增加 --client。它使用官方 GDB/OpenOCD 管道传输并拒绝 --port；默认调试服务器仍保持回环 TCP 流程。目标 JSON 必须在 gdb_client.tool 中通过 path、size 与 sha256 显式标识 GDB 可执行文件。可选 gdb_client.commands 使用相同文件身份字段，替代默认 info threads 命令。应将该文件作为可执行操作人员输入审查。GDB 启动时禁用自动脚本，加载与 provenance 精确绑定的 ELF，附加、执行所选命令后分离。执行前后检查工具、配置与 ELF 身份。有限超时覆盖拥有的进程链；失败或取消会撤回该链并保留 station 隔离。不会自动发现可执行文件或目标。设备 schema 与命令示例见开发工具合同。主机管道 fixture 不能证明物理探针支持。

开发 monitor 仍限于 Linux/POSIX。会话绑定的终端 phase 为 acquiring、owned、releasing 和 released。确认 helper 已撤回后，只有 owned 证明本会话持有独占所有权时，父进程才可通过原先持有的 descriptor 恢复。Helper 已为 released 时，不授权再次恢复或清除独占：另一个进程可能已经取得终端。未知、损坏或中间 phase、未确认撤回及身份错误均保留隔离，不修改其他 owner 的终端。父进程不打开 by-id 指向的替换设备。

主 I/O 错误与清理错误分别可见，包括各自 exception cause/context 链；清理异常不能隐藏更早的 EOF 或读取失败。独立清理错误保留在操作记录中。父进程遭外部 SIGKILL 时不能保证恢复。波特率扩展不扩大正式 HIL console 准入，也不建立 Windows/macOS 支持。参见串口所有权回归及速率/取消回归。