rust-embedded

Rust 嵌入式固件交付

先确认硬件事实，再选择抽象和框架。不要把针对特定开发板的示例代码当作可移植代码；没有硬件证据时，不要声称固件可用。

确定任务类型

区分以下交付内容：

1. 可移植的 no_std 库或驱动程序：核心逻辑应使用模拟 HAL 在主机上测试。
2. 特定 MCU／开发板固件：需要明确目标、运行时、HAL／PAC、内存布局、烧录工具和硬件验收测试。
3. 板级支持或引导代码：重点关注链接、启动、时钟、引脚和安全不变量。
4. 嵌入式 Linux 应用：通常使用 std；除非涉及设备接口或交叉编译，否则应按命令行、Web 或并发应用处理。

强制硬件约束

修改前确认并记录：

• MCU 的确切型号、架构、开发板版本和外设连接；
• Rust 目标三元组、工具链／MSRV、构建配置；
• 运行时、HAL、PAC、BSP、embedded-hal 和执行框架的实际版本；
• Flash／RAM 起始地址、容量、引导加载程序来源、链接脚本起始位置；
• 调试探针、传输协议、烧录工具和权限；
• 时钟、引脚复用、电压、总线地址／模式／频率；
• 并发模型：裸机中断、临界区、RTIC、Embassy 或其他方式；
• 可观测性通道：defmt、UART、RTT、LED、逻辑分析仪等；
• 实际硬件验收步骤和安全约束。

如果芯片内存布局或引脚配置尚不确定，不要编造数值。优先查阅现有 BSP、数据手册、参考手册，以及项目仓库中锁定的文档。

工作流

1. 确立构建基线和硬件基础

检查仓库配置、目标选择和依赖来源：

rustc --version --verbose
rustup target list --installed
cargo metadata --format-version 1
cargo tree -e features

找到 .cargo/config.toml、链接参数、memory.x／链接脚本、build.rs、运行器、芯片功能标志和现有烧录命令。先重现当前构建，或保存失败日志。

选择目标、运行时或内存布局时，请阅读目标和运行时。

2. 建立最小启动路径

确保最小固件能针对特定目标正确构建，生成可检查的镜像，然后再集成复杂外设：

Reset/Startup Code
    -> Initialize Memory and Runtime
    -> Initialize Clocks and Required Peripherals
    -> Enter Unique Application Entry Point
    -> Produce Observable Heartbeat or Diagnostics

• 裸机二进制通常使用 #![no_std]；是否使用 #![no_main] 取决于运行时。
• 只有在提供全局分配器、内存空间和失败处理策略后，才能使用 alloc。
• panic 策略必须适合设备约束和调试环境。
• 内存布局必须基于芯片／BSP／引导加载程序的事实，而非照搬其他开发板的示例代码；不要针对 Cortex-M、RISC-V 或其他架构硬编码单一假设。

3. 将可移植逻辑与板级连接分离

建议的边界：

Pure Domain Logic (No Hardware Dependencies)
    -> portable driver (core + embedded-hal traits)
    -> board adapter (specific HAL/PAC, pins, clocks)
    -> firmware binary (startup, tasks, failure strategies)

• 可移植驱动程序依赖 embedded-hal trait，而不依赖特定 PAC 单例。
• 板级层负责处理实际外设，并配置引脚、时钟和 DMA。
• 只有当 HAL 无法满足启动或性能需求时，才直接访问 PAC；不要使用 .ok() 悄悄丢弃 GPIO、总线或协议错误。
• 在 SAFETY 注释中记录寄存器、DMA、裸机指针和 FFI 的安全假设，然后使用 rust-unsafe-ffi 深入审查。

4. 选择并发模型

不要在同一固件中随意混用裸机中断、多个执行器或不同的资源锁定模型。

• 裸机中断：确保 ISR 有界且不会阻塞，并尽量减少内存分配；将工作委托给主循环或任务。
• 临界区：尽量缩短屏蔽中断的时间，并明确优先级反转和嵌套语义。
• RTIC：根据锁定版本检查资源锁定版本、优先级和任务 API。
• Embassy：确认执行器配置、时间驱动程序、芯片集成和取消行为。
• DMA：缓冲区所有权和传输生命周期必须由类型约束或明确的不变量保证。

需要选择 HAL、共享状态或框架时，请阅读 HAL and Concurrency。复杂的语言级并发语义应使用 rust-concurrency。

5. 增强可观测性并制定故障策略

• 为开发构建提供可恢复的日志／探测路径；
• 不要让日志记录的时序掩盖中断或实时性问题； 区分开发者触发的 panic、硬件看门狗复位事件和生产环境中的优雅降级策略。
• 保留传感器超时、总线错误、校验和失败、外设不可用等情况的上下文。

不要在日志中泄露设备密钥、配对凭据或敏感标识符。

6. 分层验证

按从快到慢的顺序进行验证：

1. 对纯逻辑运行主机端单元测试；
2. 使用 mock embedded-hal 测试驱动协议和错误路径；
3. 针对真实目标交叉编译所有相关功能／配置；
4. 检查 ELF、段、符号、映像大小以及栈／堆预算；
5. 烧录并保存探针／UART 日志；
6. 在真实硬件上验证引脚、总线、时序、中断和复位路径；
7. 必要时使用示波器或逻辑分析仪确认电气和时序事实。

完整的证据清单见 Hardware Validation。

常用命令

根据仓库配置替换 <target> 和 <package>：

cargo fmt --all -- --check
cargo test -p <portable-package> --all-targets
cargo clippy -p <portable-package> --all-targets -- -D warnings
cargo build -p <firmware-package> --target <target> --release
cargo size -p <firmware-package> --target <target> --release

cargo size 需要安装项目和 cargo-binutils；否则，请使用仓库中已有的 ELF／段检查工具。仅当运行器已针对该目标配置好且硬件目标已确认时，才执行烧录或运行命令。烧录会改变设备状态；请先解析确切目标，并严格遵守用户授权范围。

完成标准

• 明确定义硬件契约、依赖版本和内存布局来源；
• 将可移植逻辑与板级代码分离，且不静默吞掉错误；
• 主机端测试和针对目标的交叉编译均通过；
• 记录并发、DMA、寄存器或 unsafe 不变量；
• 检查映像大小和资源预算；
• 真实硬件验收有日志／测量证据。

如果验证期间没有可用的真实硬件，请标记为“仅构建验证”。

交接边界

主要问题	分配给
裸指针、MMIO、FFI、安全封装不变量	rust-unsafe-ffi
Async、取消、Send/Sync 和通用并发语义	rust-concurrency
主机端测试、属性测试、覆盖率或基准测试	rust-testing
目标配置、功能标志、构建脚本	rust-cargo-build
语言所有权、trait、错误和 core API	rust-stable

按需资源

• 目标和运行时：确认目标、启动方式或内存布局时阅读。
• HAL 和并发：编写中断、RTIC、Embassy 任务的驱动代码时阅读。
• 硬件验证：构建、烧录、测量并报告结果时阅读。
• 场景示例：需要任务拆分模板时阅读。
• examples/golden-no-std/：可在主机上编译、可通过模拟进行测试的 no_std 驱动边界示例。

依据

• The Embedded Rust Book
• Rust Embedded Working Group
• embedded-hal
• The Rust Reference：no_std