引言

这是 HiSilicon WS63（Hi3863，RISC-V RV32IMFC，Wi-Fi 6 + SLE/SparkLink + BLE）的 Rust 嵌入式生态开发手册。

整套生态包含：

• hisi-riscv-hal —— 手写的安全外设驱动（GPIO/UART/I2C/SPI/DMA/Timer…），基于 embedded-hal 1.0，可选 async / embassy。
• ws63-pac —— svd2rust 生成的寄存器访问层。
• hisi-riscv-rt —— 启动汇编、链接脚本、中断向量。
• hisi-riscv 工具链 —— 内置 riscv32imfc-unknown-none-elf（硬浮点、无原子）目标的定制 stable rustc。
• hisi-fwpkg —— 把 ELF 打包成可被 flashboot 加载的应用镜像（0x300 头）。
• patched probe-rs —— 支持 WS63 的 J-Link/SWD 烧录与调试。
• hisi-riscv-qemu —— 跑得动 vendor C SDK 与 Rust 固件的 QEMU 模型。
• HIL 测试框架 —— 在真实芯片上构建→烧录→运行→断言 UART 标记串。

本手册如何组织（Diátaxis）

本手册按 Diátaxis 框架分为四个象限，各自服务不同目的：

如果你是第一次接触，先到教程导读选择适合你的路径——本手册的教程分两条：

• 应用开发者：用 cargo generate 从模板脚手架出你自己的 WS63 应用（依赖来自 crates.io，无需克隆本仓库）。见应用开发者路径。
• 生态贡献者：克隆本 monorepo（含子模块），构建/运行完整示例集、改 HAL/PAC/运行时、跑完整 HIL。见生态贡献者路径。

仓库

• 在线手册：https://hispark-rs.github.io/hisi-riscv-rs/（本书）
• API 文档（rustdoc）：https://hispark-rs.github.io/hisi-riscv-rs/api/（hisi-riscv-hal / ws63-pac / hisi-riscv-rt）
• 主仓库：https://github.com/hispark-rs/hisi-riscv-rs
• 工程模板：https://github.com/hispark-rs/hisi-rs-template（cargo generate）
• 其它仓库见 CLI 工具速查 与各组件文档。

教程 · 选择你的路径

欢迎！本章是一组手把手的课程：给确切的命令、给你应当看到的输出，照着做就能成功。

在开始之前，先选一条适合你的路径——两条路径面向不同的人、起点也不同，但风格一样（学习导向、一条happy path）。

你是哪一类？

应用开发者（用 WS63 写你自己的 App）

你想用我们已发布到 crates.io 的库（hisi-riscv-hal / hisi-riscv-rt / ws63-pac） 开发自己的 WS63 程序。你不需要克隆这个monorepo—— 起点是用 cargo generate 从模板 hisi-rs-template 生成一个自包含的工程。有没有开发板都行（QEMU 不需要硬件）。

→ 走 应用开发者路径

生态贡献者（开发 HAL / PAC / rt / QEMU / 示例）

你想给 HAL、PAC、运行时、QEMU 模型或示例目录贡献代码。你需要克隆 带子模块的monorepo，构建并运行完整的示例集，并做硬件在环（HIL）测试。

→ 走 生态贡献者路径

教程只求带你跑通，不展开讲原理。想知道“为什么“看 原理与背景； 想查命令和参数看 参考；想完成某个具体任务看 操作指南。

应用开发者路径 · 导读

本路径面向用 WS63 写自己 App 的开发者。你会用已发布到 crates.io 的库 （hisi-riscv-hal / hisi-riscv-rt / ws63-pac），从模板 hisi-rs-template 生成一个 自包含的工程，在 QEMU 里跑起来，再烧到真板。

你不需要克隆这个monorepo——所有依赖都来自 crates.io，生成的工程自带 justfile。

适合谁

• 想基于现成的库快速做一个 WS63 应用，而不是改 HAL/PAC 本身。
• 想要一条“生成工程 → just run → just flash“的最短上手路径。

你需要准备什么

• 一台 Linux 电脑（本路径在 x86_64 Linux 上验证）。
• 已安装 rustup、git、curl。
• 第 1 课会带你装好其余工具（自定义工具链、cargo-generate、just、烧录器、可选 QEMU）。
• 开发板可选：QEMU 不需要硬件；只有要烧真机（第 2 课后半段）时才需要一块 WS63 开发板。

三节课

1. 搭建环境（应用开发） —— 装好 hisi-riscv 工具链、cargo-generate、just、hisi-fwpkg、烧录用的 probe-rs 分支，以及可选的 QEMU。
2. 从模板创建你的第一个工程 —— cargo generate 生成 blinky 工程，just run 在 QEMU 里跑，再 just flash 烧到真板看 LED 闪。
3. 改造成一个 UART 程序 —— 用 uart_hello 起手，在 QEMU 里看到 Hello from WS63 ...。

学完这三课，你就有了一个自己的、能跑能烧的 WS63 工程。开始吧 —— 搭建环境（应用开发）。

搭建环境（应用开发）

本课带你装好开发 WS63 应用所需的全部工具。注意：你不需要克隆monorepo—— 所有库依赖都来自 crates.io，工程将在下一课用 cargo generate 生成。

本课只求“把工具装上“。每个工具的深入说明与故障排查见 安装 hisi-riscv 工具链。

第 1 步：安装 hisi-riscv 工具链

WS63 应用核是 riscv32imfc-unknown-none-elf（硬件单精度浮点、无原子扩展）。 这个目标被内建进了一个自定义的 hisi-riscv 工具链——它不是 rustup 频道，需要手动下载并链接。

下载与你主机匹配的压缩包（这里以 x86_64 Linux 为例），解压，然后链接：

HOST=x86_64-unknown-linux-gnu
curl -LO https://github.com/hispark-rs/hisi-riscv-rust-toolchain/releases/download/v1.96.0-2/hisi-riscv-rust-1.96.0-$HOST.tar.gz
tar xzf hisi-riscv-rust-1.96.0-$HOST.tar.gz
rustup toolchain link hisi-riscv "$PWD/stage2"

其它主机把 HOST 换成对应三元组即可：aarch64-unknown-linux-gnu、 aarch64-apple-darwin、x86_64-pc-windows-msvc。

确认链接成功：

rustup toolchain list | grep hisi-riscv

你应当看到：

hisi-riscv

第 2 步：安装 cargo-generate 与 just

下一课用 cargo generate 从模板生成工程；生成出来的工程用 just 跑各种命令：

cargo install cargo-generate just

第 3 步：安装打包工具 hisi-fwpkg（烧真机用）

烧到真板时，flashboot 期望一个带 0x300 启动头的应用镜像，hisi-fwpkg 负责打包：

cargo install --git https://github.com/hispark-rs/hisi-fwpkg

也可以克隆 github.com/hispark-rs/hisi-fwpkg 自行构建。确认就位：hisi-fwpkg --help。

第 4 步：安装打过补丁的 probe-rs 分支（烧真机用）

上游 probe-rs 不认识 WS63，必须用打过补丁的分支，并配上它自带的 HiSilicon_WS63.yaml 芯片描述文件：

cargo install --git https://github.com/hispark-rs/probe-rs \
    --branch add-hisilicon-ws63-bs21 probe-rs-tools

确认就位：probe-rs --version。深入说明见 用 probe-rs 烧录到真机。

只想在 QEMU 里跑、暂时不烧真机，可以先跳过第 3、4 步。

第 5 步：安装 QEMU（可选，just run 用）

想用 just run 在模拟器里跑，需要 hisi-riscv-qemu—— 一个带 -M ws63 机器模型的 QEMU 分支。克隆并构建，把它的 qemu-system-riscv32 放进 PATH：

git clone https://github.com/hispark-rs/hisi-riscv-qemu && cd hisi-riscv-qemu
./scripts/build.sh

确认 ws63 机器可用：

qemu-system-riscv32 -M help | grep ws63

第 6 步：验证工具链

hisi-riscv 工具链内建了 WS63 目标，确认它在目标列表里：

rustc +hisi-riscv --print target-list | grep riscv32imfc

你应当看到：

riscv32imfc-unknown-none-elf

看到这一行就说明工具链装好了。下一课生成的工程里有 rust-toolchain.toml， 会自动选用 hisi-riscv，所以在工程目录里直接敲 cargo 即可，无需 +hisi-riscv。

工具齐了！下一课我们生成你的第一个工程 —— 从模板创建你的第一个工程。

从模板创建你的第一个工程

这是应用开发者路径最关键的一课。我们用 cargo generate 从模板生成一个 你自己的 blinky 工程，先在 QEMU 里跑通，再烧到真正的 WS63 开发板， 亲眼看到板载 LED 闪烁。

这条 blinky 路径已在真实芯片上验证通过（2026-06-14，GPIO0 翻转正常）。照做即可成功。

第 1 步：从模板生成工程

用 cargo generate 拉取模板并回答几个提示：

cargo generate --git https://github.com/hispark-rs/hisi-rs-template

按提示回答（默认值就是我们要的）：

• 项目名（Project Name）：随便起一个，比如 my-blinky。
• Target chip：选 ws63（默认）。
• Starter app：选 blinky（默认）。
• App partition flash address：保持默认 0x00230000（WS63 的应用分区地址，已验证）。

生成完成后进入工程目录：

cd my-blinky

这个工程是自包含的：它的依赖（hisi-riscv-hal / hisi-riscv-rt / ws63-pac） 都来自 crates.io，它自带 rust-toolchain.toml（钉死 hisi-riscv 工具链）、 .cargo/config.toml（设好目标和 QEMU runner）和一个 justfile。 你不需要克隆任何monorepo。

第 2 步：在 QEMU 里跑

先用 QEMU 确认程序能正常启动：

just run

这会 cargo build --release 再用 -M ws63 启动 QEMU。blinky 只翻转 GPIO0、 没有串口输出，所以控制台不会打印东西——这是预期的：程序正在安静地循环翻转引脚 （机器 trace 里能看到 GPIO0 每 500 ms 变一次）。

按 Ctrl-A 然后按 X 退出 QEMU。

第 3 步：烧到真正的开发板

插上 WS63 开发板，一条命令完成“编译 → 打包 → 下载 → 复位“：

just flash

just flash 依次做了这些事：

1. cargo build --release 编出 ELF；0x300 HiSilicon 启动头由 hisi-riscv-rt 的 boot-header 特性在链接时直接烘进 ELF，无需单独的打包步骤；
2. hisi-fwpkg patch-hash <elf> 在链接后就地补齐 ELF body 的 SHA-256（链接时占位是零）；
3. 用打补丁的 probe-rs 分支把这枚裸 ELF 直接 download 到应用分区 0x00230000（不经过 .img 中间文件）；
4. probe-rs reset 复位，flashboot 跳进应用入口（app + 0x300）。

不需要真正签名，但需要真实 hash：开发芯片的安全验证是关闭的（efuse SEC_VERIFY_ENABLE == 0），但 flashboot 在硬件上仍会校验 body 的 SHA-256—— secure-off 只是跳过 ECC 签名，不跳过 hash。所以镜像需要的是 0x300 头 + 真实 body SHA-256（这正是 patch-hash 在做的事），而不存在一个能让它启动的“占位签名“。 镜像格式细节见 应用镜像格式与签名。

BS2X 仍走“route 1“：链接时没有 boot-header，用编译后的 hisi-fwpkg image -o app.img <elf> 打包再烧 .img；WS63 用的是上面的 patch-hash + 裸 ELF 路径。

如果 HiSilicon_WS63.yaml 不在当前目录，指给它： just CHIP_DESC=/path/to/HiSilicon_WS63.yaml flash。 probe-rs 分支与 YAML 的细节见 用 probe-rs 烧录到真机。

想在烧录的同时顺便看 UART0 的启动日志，可以用：

just run-hw PORT=/dev/ttyUSB0

它会先 flash，再把 UART0（CH340 串口，/dev/ttyUSB0 @ 115200 8N1）接到终端。

第 4 步：看 LED 闪烁

复位之后，看你的开发板：板载 LED（GPIO0）开始闪烁，亮 0.5 秒、灭 0.5 秒， 不断循环。

成功了！你刚刚用一个完全属于你自己的 Rust 工程，让一块真正的 WS63 芯片 亮起了第一个 LED。

下一课我们把它改造成一个会“说话“的 UART 程序 —— 改造成一个 UART 程序。

改造成一个 UART 程序

上一课你的工程只会闪灯，这一课我们让它开口打印。最简单的办法是用 uart_hello 起手重新生成一个工程，在 QEMU 里看到它打印 Hello from WS63 ...。

QEMU 是本课可靠的成功路径。uart_hello 就是为 QEMU 设计的：它故意不初始化时钟， 只碰 UART0 寄存器。

第 1 步：用 uart_hello 起手生成工程

再跑一次 cargo generate，这次 Starter app 选 uart_hello：

cargo generate --git https://github.com/hispark-rs/hisi-rs-template

• 项目名：比如 my-uart。
• Target chip：ws63（默认）。
• Starter app：选 uart_hello。
• App partition flash address：默认 0x00230000。

进入工程目录：

cd my-uart

第 2 步：在 QEMU 里运行

just run

-nographic 会把 UART0 接到你的终端。

第 3 步：看到它说话

控制台上你应当立刻看到 banner，随后是不断递增的 tick 计数：

Hello from WS63 on QEMU!
UART0 @ 0x44010000 is alive.
tick 0
tick 1
tick 2
...

计数器会一直涨下去。看到这些输出，说明你的 Rust 程序成功通过 UART0 打印了文本。

按 Ctrl-A 然后按 X 退出 QEMU。

成功了！你刚刚让一个属于你的工程打印出了第一行串口日志。

关于真机

在真正的硬件上，串口 banner 的点亮工作仍在进行中——真机需要先初始化时钟， 让波特率分频与 PLL 匹配，而 uart_hello 为了适配 QEMU 故意省去了这一步。 所以本课不承诺真机上能看到这条 banner；要在真板上稳定看到串口输出， 请关注 HIL 测试框架 的进展。

想在真机上看到稳定可观测的行为，最稳妥的仍是上一课的 blinky（GPIO 翻转，已验证）。

接下来想做点什么？

• 想完成具体任务（加驱动、调试读内存）——看 操作指南。
• 想查命令、地址、API——看 参考。
• 想搞懂背后的原理——看 原理与背景。
• 想给生态本身贡献代码——看 生态贡献者路径。

生态贡献者路径 · 导读

本路径面向给生态本身贡献代码的人：改 HAL、PAC、运行时（rt）、QEMU 模型， 或者维护示例目录。你会克隆带子模块的monorepo，构建并运行完整的示例集， 最后做硬件在环（HIL）测试。

适合谁

• 想给 hisi-riscv-hal / ws63-pac / hisi-riscv-rt / hisi-riscv-qemu 提交改动。
• 想新增或调试示例（examples/ws63/*），并用 QEMU + HIL 验证它们。

你需要准备什么

• 一台 Linux 电脑（本路径在 x86_64 Linux 上验证）。
• 已安装 rustup、git、curl。
• 第 1 课会带你克隆monorepo（带子模块）、装好工具链、QEMU 和烧录器。
• 第 3 课（HIL）需要一块 WS63 开发板；第 1、2 课只用 QEMU，无需硬件。

三节课

1. 搭建环境（贡献生态） —— 克隆monorepo、装工具链/QEMU/probe-rs，并以一次成功的 cargo build -p blinky 收尾。
2. 构建与运行示例集 —— 在 QEMU 里跑完整示例目录：GPIO、UART、中断、半主机退出码。
3. 第一次硬件在环测试 —— 把 blinky 烧到真板，观察 GPIO 翻转，认识 hil/hil-smoke.sh。

学完这三课，你就能在这个仓库里构建、运行并验证示例与改动了。开始吧 —— 搭建环境（贡献生态）。

搭建环境（贡献生态）

本课带你装好全部工具、克隆带子模块的monorepo，并以一次成功的编译收尾。 请逐步执行，每一步都有可见的结果。

本课只求“把工具跑起来“。每个工具的深入安装与故障排查见 安装 hisi-riscv 工具链。

第 1 步：安装 hisi-riscv 工具链

WS63 应用核是 riscv32imfc-unknown-none-elf（硬件单精度浮点、无原子扩展）。 这个目标被内建进了一个自定义的 hisi-riscv 工具链——它不是 rustup 频道，需要手动下载并链接。

下载与你主机匹配的压缩包（这里以 x86_64 Linux 为例），解压，然后链接：

curl -LO https://github.com/hispark-rs/hisi-riscv-rust-toolchain/releases/download/v1.96.0-2/hisi-riscv-rust-1.96.0-x86_64-unknown-linux-gnu.tar.gz
tar xzf hisi-riscv-rust-1.96.0-*.tar.gz
rustup toolchain link hisi-riscv "$PWD/stage2"

确认链接成功：

rustup toolchain list | grep hisi-riscv

你应当看到：

hisi-riscv

第 2 步：克隆仓库（带子模块）

示例、HAL、PAC、运行时都是子模块，务必带 --recurse-submodules 克隆：

git clone --recurse-submodules https://github.com/hispark-rs/hisi-riscv-rs.git
cd hisi-riscv-rs

如果你已经克隆但忘了子模块，补一句：git submodule update --init --recursive。

仓库根目录的 rust-toolchain.toml 已经把频道钉成了 hisi-riscv， 所以在本仓库内执行的所有 cargo 命令都会自动用上刚装好的工具链。

第 3 步：安装 QEMU 模拟器

第 2、3 课要用 hisi-riscv-qemu—— 一个带 WS63 机器模型（-M ws63）的 QEMU 分支。在仓库同级目录里克隆并构建它：

cd ..
git clone https://github.com/hispark-rs/hisi-riscv-qemu.git
cd hisi-riscv-qemu
bash scripts/build.sh

构建完成后，确认 qemu-system-riscv32 可用并支持 ws63 机器：

./build/qemu-system-riscv32 -M help | grep ws63

你应当看到 ws63 出现在机器列表中。把这个二进制加入 PATH， 或记下它的路径——第 2 课会用到。详细步骤见 QEMU 模型。

第 4 步：安装烧录工具（真机用）

第 3 课要烧到真板，需要两个工具：

• hisi-fwpkg：把 ELF 打包成可启动镜像（加 0x300 启动头）。
• 打过补丁的 probe-rs 分支（hispark-rs/probe-rs，分支 add-hisilicon-ws63-bs21）： 上游 probe-rs 不认识 WS63，必须用这个分支，并配上 HiSilicon_WS63.yaml。

安装方法（深入说明见 安装工具链 与 用 probe-rs 烧录到真机）：

# hisi-fwpkg
cargo install --git https://github.com/hispark-rs/hisi-fwpkg

# 打过补丁的 probe-rs 分支
cargo install --git https://github.com/hispark-rs/probe-rs --branch add-hisilicon-ws63-bs21 probe-rs-tools

确认两者就位：

hisi-fwpkg --help
probe-rs --version

第 2 课只用 QEMU，可以暂时跳过本步；等到第 3 课要烧真机时再装也行。

第 5 步：验证你的环境

回到仓库根目录，编译 blinky 示例——这是检验工具链是否就绪的最快办法：

cd ../hisi-riscv-rs
cargo build -p blinky --release

第一次编译会拉取依赖、编译 HAL，需要几分钟。结束时你应当看到类似：

    Finished `release` profile [optimized + debuginfo] target(s) in ...

产物在这里：

ls target/riscv32imfc-unknown-none-elf/release/blinky

看到这个文件，就说明工具链、目标、仓库都配好了。

编译过程中会有一些 .weak StorePageFault 之类的汇编 warning，这是正常的，可以忽略。

环境就绪！下一课我们构建并运行完整的示例集 —— 构建与运行示例集。

构建与运行示例集

QEMU 是不用硬件就能跑 WS63 固件的“软件在环“环境。作为生态贡献者，你会反复 构建并运行 examples/ws63/* 里的示例来验证改动。本课带你跑通示例目录里的几个 代表：blinky（GPIO trace）、uart_hello（banner）、timer_irq / gpio_irq（中断串口输出）、 semihost_selftest（半主机退出码）。每一步都有可见结果。

QEMU 模型的原理见 QEMU 模型。

示例都是根工作区的成员，所以一律从仓库根目录用 -p <name> 构建，再用同一条 命令模板运行：

cargo build -p <name> --release
qemu-system-riscv32 -M ws63 -nographic -bios none \
    -kernel target/riscv32imfc-unknown-none-elf/release/<name>

• -M ws63：WS63 机器模型。
• -nographic：无图形界面，把 UART0 接到当前终端。
• -bios none：不加载额外固件，直接跑我们的 -kernel。
• -kernel <elf>：要运行的示例 ELF。

退出 QEMU 始终是：按 Ctrl-A，再按 X。

第 1 步：blinky（GPIO 翻转，无串口）

cargo build -p blinky --release
qemu-system-riscv32 -M ws63 -nographic -bios none \
    -kernel target/riscv32imfc-unknown-none-elf/release/blinky

blinky 把 GPIO0 配成推挽输出，死循环里拉高、延时、拉低、延时。它没有串口输出， 所以控制台不会打印东西——这是预期的：程序在安静地翻转引脚（机器 trace 里能看到 GPIO0 每 500 ms 变一次）。想“看见“可观测行为，用下面带串口的示例。

关于构建目标和产物路径的细节，见 构建一个示例。

第 2 步：uart_hello（串口 banner）

cargo build -p uart_hello --release
qemu-system-riscv32 -M ws63 -nographic -bios none \
    -kernel target/riscv32imfc-unknown-none-elf/release/uart_hello

uart_hello 为 QEMU 设计：它故意不初始化时钟，只碰 UART0 寄存器（0x4401_0000）。 控制台上你应当立刻看到 banner，随后是不断递增的 tick 计数：

Hello from WS63 on QEMU!
ws63-qemu: UART0 @ 0x44010000 is alive.
tick 0
tick 1
tick 2
...

真机上的串口 banner 仍在打磨（需要先初始化时钟），本课只承诺 QEMU。第 3 课的 blinky 才是当前确认可观测的真机行为。

第 3 步：timer_irq（定时器中断）

cargo build -p timer_irq --release
qemu-system-riscv32 -M ws63 -nographic -bios none \
    -kernel target/riscv32imfc-unknown-none-elf/release/timer_irq

TIMER_0 周期性触发 IRQ 26，处理函数每次累加计数并打印。你应当看到：

WS63 timer-IRQ test (TIMER_0 -> IRQ 26)
timer irq #0
timer irq #1
timer irq #2
...
OK: timer interrupts delivered

看到 timer irq # 不断递增、最后出现 OK: timer interrupts delivered， 说明 QEMU 的中断投递闭环正常。

第 4 步：gpio_irq（GPIO 中断）

cargo build -p gpio_irq --release
qemu-system-riscv32 -M ws63 -nographic -bios none \
    -kernel target/riscv32imfc-unknown-none-elf/release/gpio_irq

这个示例把 GPIO0 的边沿映射到一个自定义本地 IRQ（≥32）。你应当看到：

WS63 GPIO-IRQ test (GPIO0 pin0 -> IRQ 33, custom local)
gpio irq #0
gpio irq #1
...
OK: custom local IRQ (>=32) delivered

第 5 步：semihost_selftest（半主机退出码）

有些示例不靠串口打印，而是通过 RISC-V 半主机把结果报告给宿主—— semihost_selftest 跑完后会用半主机的“退出“操作返回退出码：PASS 返回 0，FAIL 返回 1， panic 返回 2。这个退出码会变成 QEMU 进程自己的退出码，非常适合写进自动化脚本。

要让半主机生效，必须加上 -semihosting：

cargo build -p semihost_selftest --release
qemu-system-riscv32 -M ws63 -nographic -bios none -semihosting \
    -kernel target/riscv32imfc-unknown-none-elf/release/semihost_selftest

控制台会打印（通过半主机控制台）：

semihost_selftest: PASS

随后 QEMU 自行退出。检查它的退出码：

echo $?

你应当看到：

0

0 就代表自检通过——脚本可以直接据此判定成败，无需解析串口文本。

各示例的预期标记串汇总见 示例目录与验证标记串； 半主机相关的环境变量见 HIL 标记串与环境变量。

你现在已经能从仓库根目录构建并在 QEMU 里跑示例、读中断输出、用退出码做自检了。 下一课我们走出模拟器，做第一次真机测试 —— 第一次硬件在环测试。

第一次硬件在环测试

“硬件在环”（HIL，Hardware-In-the-Loop）就是：把程序烧进真芯片、让它真的跑起来， 再从外部观察它的行为，确认真实硬件上一切正常。本课我们用 blinky—— 那个已经在真实芯片上验证通过的示例——完成你的第一次 HIL 测试，保证成功。

我们特意选 blinky：它的 GPIO0 翻转是当前确认可观测的真机行为 （上一课提过，真机串口 banner 还在打磨中）。

你需要准备

• 一块 WS63 开发板，已连上电脑。
• 第 1 课装好的 hisi-fwpkg 和打过补丁的 probe-rs 分支。
• 一根 USB 串口线连到板子的 UART0，在系统里通常是 /dev/ttyUSB0（CH340 适配器），波特率 115200 8N1。

注意：/dev/ttyACM0 是 J-Link 的 VCOM，不是应用 UART，别接错了。

第 1 步：把 blinky 烧进真板

从仓库根目录走“编译 → 补哈希 → 下载 → 复位“四步：

cargo build -p blinky --release

# WS63 用 hisi-riscv-rt 的 boot-header 特性：0x300 启动头在链接期就已烘进 ELF，
# 链接后只需补上 body 的 SHA-256（在原文件就地填写），无中间 .img、无 image 步骤。
hisi-fwpkg patch-hash \
    target/riscv32imfc-unknown-none-elf/release/blinky

probe-rs download --chip WS63 \
    --chip-description-path HiSilicon_WS63.yaml \
    target/riscv32imfc-unknown-none-elf/release/blinky

probe-rs reset

hisi-fwpkg patch-hash 把 ELF 里 0x300 启动头之后的 body SHA-256 就地补全； 头已在链接期烘入，flashboot 复位后跳进 app + 0x300。安全启动关闭时，flashboot 仍校验 body hash，只跳过 ECC 签名（efuse SEC_VERIFY_ENABLE==0）——所以镜像需要 一份真实 body SHA-256，没有“占位签名“能让它启动。 HiSilicon_WS63.yaml 来自打补丁的 probe-rs 分支仓库——上游 probe-rs 没有 WS63 支持。 （BS2X 还没有链接期 boot-header，仍走 hisi-fwpkg image -o app.img 的 route 1 路线。） 细节见 用 probe-rs 烧录到真机 与 应用镜像格式与签名。

第 2 步：观察 GPIO 翻转

复位后看开发板：板载 LED（GPIO0）开始闪烁，亮 0.5 秒、灭 0.5 秒。

这就是一次成功的硬件在环观测——程序确实在真芯片上运行，并按预期驱动了真实引脚。 如果手边有逻辑分析仪或万用表，也可以直接量 GPIO0 引脚看到方波。

第 3 步：在串口上看启动日志

打开一个串口监视器，盯住 UART0，就能在烧录/复位时看到 flashboot 的启动日志， 确认芯片确实重启并跳进了你的应用：

stty -F /dev/ttyUSB0 115200 raw -echo
cat /dev/ttyUSB0

再做一次 probe-rs reset，监视器里就会滚出 flashboot 的启动信息。 看完按 Ctrl-C 退出 cat。

blinky 自身不打印串口（它只翻转 GPIO），所以这里看到的是 flashboot 的启动日志， 不是应用输出。UART0 接线与端口的细节见 HIL 标记串与环境变量。

第 4 步：认识 HIL 冒烟测试

手动烧一个示例、肉眼看一个结果，是理解 HIL 的好起点。但当示例越来越多时， 我们希望自动把每个示例烧上去、读 UART、断言它打印了预期的标记串。 仓库里的 hil/hil-smoke.sh 就是干这个的——它是 QEMU 冒烟测试在真硅片上的对应物。

它大致这样工作（概念示意，本课不要求你真的运行）：

PORT=/dev/ttyUSB0 hil/hil-smoke.sh

脚本会逐个示例：用 hil/flash.sh 烧录 → 读几秒 UART → 用 grep 检查预期标记串， 比如 uart_hello 应出现 Hello from WS63、timer_irq 应出现 timer irq #。 而 blinky 因为没有串口输出，脚本会特别提示“请用 LED / 逻辑分析仪人工确认“—— 正是你在第 2、3 步亲手做的事。

HIL 框架的整体设计、标记串约定、它和 QEMU 冒烟测试的关系，见 HIL 测试框架 与 运行 HIL 冒烟测试。

恭喜！你已经完成了贡献者路径的全部三课：克隆仓库、装好工具链，在 QEMU 里跑通了 示例集，最后在真正的 WS63 芯片上完成了第一次硬件在环测试。

接下来想做点什么？

• 想完成具体任务（新建工程、加驱动、调试读内存）——看 操作指南。
• 想查命令、地址、API——看 参考。
• 想搞懂背后的原理——看 原理与背景。

操作指南 · How-to Guides

这一章是任务导向的菜谱：每篇回答一个「如何做某件事」的具体问题，假设你已经掌握了基础（不懂概念请看原理与背景，要查字段/地址/标记串请看参考）。每篇都给出可照做的步骤，并尽量覆盖真实环境里的变体、坑和排错。

构建 · Build

• 如何安装 hisi-riscv 工具链 —— 下载/链接（或源码构建）自定义硬浮点 rustc 工具链，并验证 riscv32imfc target。
• 如何构建一个示例 —— 从仓库根工作区 cargo build -p <name> --release，ELF 落点，release/debug 与 objcopy 到 bin。

打包与烧录 · Flash

• 如何打包成可启动镜像（hisi-fwpkg） —— image（裸 0x300 镜像）vs pack（fwpkg），0x300 header 是干嘛的。
• 如何用 probe-rs 烧录到真机 —— 验证主路径：image → probe-rs download → probe-rs reset，补丁版 fork + yaml + 各芯片基址 + 排错。
• 如何用 hisiflash 烧录到真机 —— 厂商 YMODEM 路径：pack → .fwpkg → hisiflash flash，何时用它。
• 如何用硬件 runner 让 cargo run 烧真机 —— 用 hil/cargo-run-hw.sh 把 cargo run 从 QEMU 改成烧真机；全部环境变量。

测试 · Test

• 如何运行 HIL 冒烟测试 —— hil/hil-smoke.sh 逐示例的 UART 标记断言、环境变量、读懂通过/失败。
• 如何用 probe-rs 调试与读内存 —— 用补丁版 probe-rs read、reset_and_halt、读 CSR/内存、用 HW 断点抓应用入口、dump ROM。

开发 · Develop

• 如何从模板新建一个工程 —— cargo generate 从 hisi-rs-template 起步，用生成的 justfile 完成首次构建+烧录。
• 如何新增一个外设驱动 —— HAL 驱动模块范式、外设单例宏、sealed trait，以及配一个带 PASS 标记的 HIL 示例。

如何安装 hisi-riscv 工具链

WS63 应用核是 RV32IMFC_Zicsr：硬件单精度浮点（ilp32f）、没有原子（‘a’）扩展。仓库用一套自定义的 hisi-riscv 工具链来构建——一套 stable rustc（1.96.0），把 target riscv32imfc-unknown-none-elf 作为 builtin 烤进去，并随附预编译的 core/alloc，因此不需要 -Z build-std。它不是可分发的 rustup channel，必须先手动安装并 link。

工具链的来历、ABI 取舍见硬浮点工具链；target 命名细节见工具链与编译目标。

方式一：下载预编译 tarball（推荐）

发布页 https://github.com/hispark-rs/hisi-riscv-rust-toolchain/releases 为每个 host 提供 tarball（Linux x86_64/aarch64、macOS x86_64/aarch64、Windows x86_64）。挑你 host 对应的那个：

# 以 Linux x86_64 为例（换成你 host 对应的文件名）
curl -fLO https://github.com/hispark-rs/hisi-riscv-rust-toolchain/releases/download/v1.96.0-2/hisi-riscv-rust-1.96.0-x86_64-unknown-linux-gnu.tar.gz
tar xzf hisi-riscv-rust-1.96.0-*.tar.gz

# 把解压出来的 stage2/ 作为名为 hisi-riscv 的 rustup 工具链链接进去
rustup toolchain link hisi-riscv "$PWD/stage2"

rustup toolchain link 只是把 hisi-riscv 这个名字指向 stage2/ 目录，不会拷贝——所以别在 link 之后删/移动这个目录（要换位置就重新 link）。

方式二：从源码构建

源码与构建配方都在工具链仓库 https://github.com/hispark-rs/hisi-riscv-rust-toolchain（它本质是带 WS63 target spec 的 rustc 分支 + 一份 config.toml）。构建很重（需要完整的 rustc bootstrap，几十分钟到数小时、十几 GB 磁盘），照仓库 README 跑 x.py build 即可。构建产物同样是一个 stage2/，照方式一末尾 rustup toolchain link 进去。

大多数人不需要从源码构建——只有你要改 target spec / 编译器本身时才需要。

验证

确认 target 已 builtin（这是关键——没有它说明链接的工具链不对）：

rustc +hisi-riscv --print target-list | grep riscv32imfc
# 期望输出： riscv32imfc-unknown-none-elf

确认 core 预编译可用（直接试构建，下一篇如何构建一个示例）：

rustc +hisi-riscv --version          # 应打印 1.96.0 系列版本

rust-toolchain.toml 会自动选它

仓库根的 rust-toolchain.toml 写着：

[toolchain]
channel = "hisi-riscv"

只要你在仓库目录里跑 cargo，rustup 就会自动用 hisi-riscv 工具链，不用每条命令都加 +hisi-riscv。换句话说：链接好之后，在仓库里普通 cargo build 就走对了。 默认 target 由 .cargo/config.toml 的 target = "riscv32imfc-unknown-none-elf" 指定。

排错

• error: toolchain 'hisi-riscv' is not installed：还没 rustup toolchain link，或 stage2/ 被移动/删除了——重新 link。
• error: target 'riscv32imfc-unknown-none-elf' not found / 触发 build-std：你用的是普通 stable 而不是 hisi-riscv。检查 rustc +hisi-riscv --print target-list | grep riscv32imfc 是否有输出；在仓库外构建时记得 cargo +hisi-riscv ... 或带上 rust-toolchain.toml。
• 下错 host tarball（如在 aarch64 上用了 x86_64 包）：rustc 跑不起来。按 uname -m 重新挑文件名。

如何构建一个示例

仓库带了一批 WS63 示例（blinky、uart_hello、timer_irq、spi_loopback、i2c_scan、async_delay、embassy_multitask…，完整清单见示例目录与验证标记串）。本篇讲怎么把它们编出来。

前提：已安装 hisi-riscv 工具链。在仓库目录里 rust-toolchain.toml 会自动选它，默认 target 是 riscv32imfc-unknown-none-elf，无需 +hisi-riscv 或 --target。

从仓库根工作区构建（推荐）

在仓库根目录用 -p <包名> 构建任意示例：

cargo build -p blinky --release
cargo build -p uart_hello --release
cargo build -p spi_loopback --release

包名就是 crate 名（见根 Cargo.toml 的 members），和它在磁盘上的 examples/ws63/<name> 路径无关。一次构建全部库 + 默认示例：

cargo build --release        # 构建 default-members（库 + 全部 ws63 示例）

坑：别在 examples/ws63/ 里构建全部示例。 examples/ws63/ 自带一个嵌套工作区，但它的 members 只列了 blinky 一个。所以在那个目录里 cargo build -p timer_irq 会失败（不是它的成员）。从仓库根构建，根工作区才把全部示例列全。

ELF 落点

根工作区共用根 target/，release ELF 在：

target/riscv32imfc-unknown-none-elf/release/<name>

例如 target/riscv32imfc-unknown-none-elf/release/blinky。注意是无扩展名的 ELF（cargo 按 [[bin]]/crate 名命名产物）。

如果你是在 examples/ws63/ 嵌套工作区里单独构建（只有 blinky），它的产物在 examples/ws63/target/riscv32imfc-unknown-none-elf/release/——hil/ 里的脚本默认就找这个目录。两个 target/ 不要混。

--release vs debug

• --release：默认就用它。优化后体积小（blinky 约 48 KB），是真机/HIL 烧录用的产物。
• debug（去掉 --release）：体积大很多、有完整调试信息，适合 GDB 调试，但可能因为体积/布局在受限的 app 分区里不合适。烧真机一律用 --release。

objcopy 成裸 bin

打包成可启动镜像时 hisi-fwpkg 直接吃 ELF（见如何打包镜像），通常不需要手动 objcopy。但若某条工具链确实要裸 bin，用工具链自带的 rust-objcopy：

OBJCOPY="$(rustc +hisi-riscv --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin/rust-objcopy"
"$OBJCOPY" -O binary \
    target/riscv32imfc-unknown-none-elf/release/blinky \
    blinky.bin

（host 三元组那段按你的 host 改；hil/flash.sh 的 hisiflash 路径就是这么从 ELF 生成 bin 的。）

下一步

• 打包成可启动镜像 → 如何打包成可启动镜像
• 烧到真机 → 用 probe-rs / 用 hisiflash
• 在 QEMU 里跑 → 见教程 在 QEMU 里运行与调试

如何用 probe-rs 烧录到真机

这是 2026-06-14 在真实 WS63 硅片上跑通的验证主路径（blinky 上电启动 + 翻转 GPIO0）。WS63 用 hisi-riscv-rt 的 boot-header feature 在链接期就把 0x300 HiSilicon 头烤进 ELF，所以裸 ELF 本身就可启动——无需 hisi-fwpkg image 那一步、也没有中间 .img 文件。流程三步：链接后用 hisi-fwpkg patch-hash 就地把 body SHA-256 填进头里（secure-off 仍会校验 hash，只跳过 ECC 签名），用 probe-rs download 把 ELF 直接写进 XIP flash 的 app 分区，再 probe-rs reset 复位运行。

用串口/YMODEM 而不是 SWD/JTAG 探针的话，走厂商 hisiflash 路径。

前提：补丁版 probe-rs fork（必须）

上游 probe-rs 还没有 WS63 target，也没有 ws63-sfc flash 算法，用 mainline 烧不了。必须装补丁版 fork：

cargo install --git https://github.com/hispark-rs/probe-rs \
    --branch add-hisilicon-ws63-bs21 probe-rs-tools

同时需要该 fork 随附的芯片描述 HiSilicon_WS63.yaml（在 fork 仓库 probe-rs/targets/HiSilicon_WS63.yaml）。烧录时用 --chip-description-path 指向它。该端口的来历见probe-rs 端口说明。

三步走（手动，WS63）

# 1. 链接后填充 body SHA-256（boot-header 已把 0x300 头烤进 ELF，
#    这一步把头里的 body hash 就地补齐；secure-off 仍校验 hash，只跳过 ECC 签名）
hisi-fwpkg patch-hash \
    target/riscv32imfc-unknown-none-elf/release/blinky

# 2. 直接把 ELF 下载进 app 分区（基址来自 ELF 里 boot-header 的链接地址，
#    无需 --base-address；fork 的 ws63-sfc 算法会按 ELF 段地址落位）
probe-rs download --chip WS63 \
    --chip-description-path HiSilicon_WS63.yaml \
    target/riscv32imfc-unknown-none-elf/release/blinky

# 3. 复位运行
probe-rs reset --chip WS63 --chip-description-path HiSilicon_WS63.yaml

关键：WS63 烧的是带 boot-header 的 ELF 本身，不是裸二进制，所以不需要 --binary-format bin + --base-address——probe-rs 按 ELF 段地址落位即可。patch-hash 是必须的后链接步骤，少了它 flashboot 校验 body hash 不过、不会进你的程序。

BS2X（bs21/bs20…）走 route 1： 还没有链接期 boot-header，要先 hisi-fwpkg image -o app.img <elf> 打出 0x300 头镜像（裸二进制），再用 --binary-format bin --base-address <app 基址> 把 .img 落到 app 分区。下面「各芯片基址」表给的就是 BS2X 这条路要用的基址。

各芯片基址（route 1 / BS2X 用）

WS63 走 route 2 烧 ELF，地址由 boot-header 链接进去，不需要手填基址。下表是 route 1（hisi-fwpkg image + --base-address）落 .img 时用的 app 分区基址——目前主要给 BS2X，也可作为 WS63 boot-header 链接地址的参考：

BS2X 基址来自 hisi-fwpkg 的 Chip::Bs21 默认值，尚未 HIL 验证——烧 BS2X 前对照你的 fbb_bs2x 分区表确认。自定义分区表时用 --base-address 覆盖。

用脚本一把梭

hil/flash.sh 默认 METHOD=probe-rs，封装了 download + reset 一条龙：

PROBE_RS_YAML=/path/HiSilicon_WS63.yaml hil/flash.sh blinky

注意：当前 hil/flash.sh 仍走 route 1 老流程（内部调 hil/pack.sh 跑 hisi-fwpkg image 出 .img，再 --binary-format bin --base-address 落位）——对 BS2X 正确，对 WS63 也仍能跑通（.img 与 boot-header ELF 的 body 一致）。WS63 的精简 route 2 推荐路径见上面「三步走」或模板 justfile 的 patch/flash recipe（hisi-fwpkg patch-hash + 直接烧 ELF）。

可用环境变量：

如要直接用本地编译出来的 fork：PROBE_RS=/home/.../probe-rs/target/debug/probe-rs。

排错

• 'probe-rs' not found 或 chip 'WS63' not found：装的是上游 probe-rs，不是补丁版 fork。重装上面那条 --branch add-hisilicon-ws63-bs21。
• PROBE_RS_YAML not found：忘了给 yaml 路径，或路径错。yaml 在 fork 仓库 probe-rs/targets/HiSilicon_WS63.yaml。
• "Flash Init Fail" 之类的提示：在本端口里通常非致命——download 仍会继续并成功。先看最终是否 Finished/写入成功，再决定是否当真问题。
• 写入卡住 / 校验失败：很可能是 flash **block protect（块保护）**没解。先确认 app 分区不在保护区（厂商工具或 SFC 寄存器层面解保护），再重试。
• download 成功但 reset 后没反应：
  • WS63（route 2）：八成是忘了跑 hisi-fwpkg patch-hash——头里 body SHA-256 没填，flashboot 校验 hash 不过，不会进你的程序（secure-off 只跳过 ECC 签名，hash 仍校验，没有“假签名/dummy 签名”能让它启动，必须是真实 body hash）。也要确认烧的是带 boot-header 的 ELF，不是 cargo 直接产出但没 patch 的 ELF。
  • BS2X（route 1）：确认烧的是 hisi-fwpkg image 出的 .img（0x300 头镜像）而不是裸 ELF/bin——裸文件复位后 PC 落在头区，不会进你的程序。

之后

要边烧边看 UART、或让 cargo run 直接烧真机，见如何用硬件 runner 让 cargo run 烧真机；要 attach 调试/读内存见如何用 probe-rs 调试与读内存。

如何用 hisiflash 烧录到真机

这是厂商串口 / YMODEM 路径：把程序打成 .fwpkg，用 hisiflash 经串口烧进去。它不需要 SWD/JTAG 探针，只要一根 UART 线——适合手上没有补丁版 probe-rs 探针、或就想用厂商工具的场景。

想用探针的验证主路径请看如何用 probe-rs 烧录。两者怎么选见文末。

前提

• hisiflash：cargo install hisiflash-cli（或自行构建 hisiflash 仓库）。
• LOADERBOOT：厂商 LoaderBoot 二进制。hisiflash 会先把它推进 SRAM，再让它接管 flash 写入。取自 fbb_ws63 构建产物（src/output/ws63/.../*loaderboot*.bin）。必填。
• ADDRESS：程序写入的 flash 偏移（典型 app 分区偏移 0x230000）。对照板子的分区表确认——写错可能烧不进或烧错位置。

两步走

1. 打成 .fwpkg

hisi-fwpkg pack -o blinky.fwpkg --chip ws63 \
    target/riscv32imfc-unknown-none-elf/release/blinky
# 或用脚本：
FWPKG=1 hil/pack.sh blinky          # -> examples/ws63/target/.../blinky.fwpkg

.fwpkg 是单分区容器（V1 + CRC），内含已带 0x300 头的 app 镜像（见如何打包镜像）。

2. 用 hisiflash 烧

hisiflash 直接吃 .fwpkg：

hisiflash flash blinky.fwpkg

或者走 hil/flash.sh 的 METHOD=hisiflash 分支（它写程序而非 fwpkg，先推 LoaderBoot 再 write-program）：

METHOD=hisiflash PORT=/dev/ttyUSB0 \
    LOADERBOOT=/path/loaderboot.bin ADDRESS=0x230000 \
    hil/flash.sh blinky

环境变量（hisiflash 路径）：

波特率注意：fwpkg/YMODEM 流程常见 230400，更稳的可降到 115200；hisiflash 本身的 write-program 默认 921600。波特率太高在差线材上易丢包，烧不进就降速重试。

何时用 hisiflash vs probe-rs

优先 probe-rs（能顺带调试）；没有探针、或只想用厂商成熟链路时用 hisiflash。

如何打包成可启动镜像（hisi-fwpkg）

裸 ELF/bin 烧进 app 分区不会启动。flashboot 会无条件跳到 app 分区 + 0x300（WS63 上 app 分区 = flash 0x230000，故入口 = 0x230300）。所以 app 分区开头必须放一段 0x300 字节的 HiSilicon 镜像头，后面才是你的代码。镜像头的字段布局见应用镜像格式与签名，启动流程见启动流程。

补这层 0x300 头有两条路线，按芯片不同：

• WS63（route 2，当前主路径）：用 hisi-riscv-rt 的 boot-header feature，0x300 头在链接期就烧进 ELF，裸 ELF 本身即可启动——不需要 hisi-fwpkg image。链接后只需补一步 body SHA-256（hisi-fwpkg patch-hash），再用 probe-rs download/run 直接烧裸 ELF，没有中间 .img。详见下面的 WS63：boot-header + patch-hash。
• BS21/BS2X（route 1）：尚无链接期 boot-header，仍走 hisi-fwpkg image -o app.img <elf>（编译后），再把 .img 烧到 app 分区。

安装：cargo install --git https://github.com/hispark-rs/hisi-fwpkg（或 cargo install hisi-fwpkg-cli）。

WS63：boot-header + patch-hash

WS63 用 hisi-riscv-rt 的 boot-header feature，把 0x300 HiSilicon 头在链接期直接放进 ELF，裸 ELF 即可启动。链接后再补一步 body 哈希即可：

# 编译（boot-header feature 会把 0x300 头烧进 ELF）
cargo build --release

# 补 body SHA-256（就地改写 ELF；secure-off 时 flashboot 仍校验 hash）
hisi-fwpkg patch-hash \
    target/riscv32imfc-unknown-none-elf/release/blinky

# 直接烧裸 ELF（无中间 .img），再复位运行
probe-rs download target/riscv32imfc-unknown-none-elf/release/blinky
probe-rs run      target/riscv32imfc-unknown-none-elf/release/blinky

patch-hash 只接受一个位置参数 <ELF>，就地填回 body 的 SHA-256（不产新文件）。注意 cargo flash 不适用于 WS63 boot-header——它没有插入这步强制 patch-hash 的 runner 槽位，无法保证烧进去的 ELF 带正确 body hash。烧录细节见如何用 probe-rs 烧录，新工程脚手架见 hisi-rs-template 的 justfile（patch / flash / run-hw recipe）。

BS2X：hisi-fwpkg 的两个子命令：image vs pack

仅 BS2X 走 image。 WS63 已改用上面的 boot-header + patch-hash（route 2），不要再对 WS63 的 ELF 跑 image。下面的 image 子命令针对 BS21/BS2X（route 1）；pack 子命令 WS63/BS2X 都可用（厂商 fwpkg 路径）。

hisi-fwpkg 自动从 magic 识别输入是 ELF 还是裸 bin，两个子命令各产一种产物：

产 *.img（BS2X probe-rs 路径用）

hisi-fwpkg image -o blinky.img \
    target/riscv32imfc-unknown-none-elf/release/blinky

image 只有 -o/--output <OUTPUT> 和一个位置参数 <INPUT>（ELF 或裸 bin）。app 基址在烧录时由 probe-rs --base-address 给（见如何用 probe-rs 烧录），所以 image 自身不需要芯片/地址参数。

产 *.fwpkg（hisiflash 路径用）

hisi-fwpkg pack -o blinky.fwpkg --chip ws63 \
    target/riscv32imfc-unknown-none-elf/release/blinky

pack 多几个选项：

• -c/--chip <ws63|bs21>（默认 ws63）：决定 app 分区基址（ws63 = 0x230000，bs2x = 0x90000）。
• --app-addr <APP_ADDR>：覆盖 app 分区烧录地址（接受十六进制，如 0x230000），自定义分区表时用。
• --name <NAME>：fwpkg 里分区名（默认 app）。

用脚本一把梭

• WS63（route 2）：用 hisi-rs-template 的 justfile——just patch（cargo build + hisi-fwpkg patch-hash）、just flash（patch + probe-rs download/reset）、just run-hw（patch + probe-rs run）。
• BS2X（route 1）：hil/pack.sh 封装了 image（+ 可选 pack），按示例名解析 ELF：

CHIP=bs21 hil/pack.sh blinky       # -> examples/.../blinky.img（默认只产 .img）
FWPKG=1   hil/pack.sh blinky       # 额外再产一个 blinky.fwpkg

CHIP 决定 app 基址（APP_ADDR= 可覆盖），脚本跑完会把两条烧录命令（probe-rs / hisiflash）打印出来供复制。pack/fwpkg（厂商 hisiflash 路径）对 WS63 同样可用。

关于签名：本片不需要真签名（但需要真实 body hash）

镜像头里有签名字段，但开发芯片 secure boot 是关的（efuse SEC_VERIFY_ENABLE == 0）。注意 secure-off 只跳过 ECC 签名，不跳过 body 哈希——flashboot 在硅片上仍会校验 body SHA-256。所以一个能启动的镜像需要 0x300 头 + 真实 body SHA-256（secure-off 仍校验 hash，只跳过 ECC 签名），并不需要真实签名密钥；hisi-fwpkg image（route 1）/ patch-hash（route 2）填的就是这份真实 hash。要打开 secure boot 的代价与做法见安全启动与签名。

如何用硬件 runner 让 cargo run 烧真机

平时 cargo run 走的是 QEMU runner（在模拟器里跑）。本篇让 cargo run 改成「编译 → 打包 → 烧进真机 → 复位 → 串口看输出」，靠的是 cargo 的 per-target runner 机制 + hil/cargo-run-hw.sh。

这只影响你显式覆盖 runner 的那一次（或那个 shell）。不覆盖时，普通 cargo run 仍然走 QEMU，互不影响。

原理

cargo 调用 runner 的方式是 <runner> <编译出的ELF路径> [args...]。hil/cargo-run-hw.sh 接住 $1 这个 ELF。WS63 用 hisi-riscv-rt 的 boot-header feature，0x300 HiSilicon 头在链接期就烤进了 ELF，裸 ELF 直接可引导——没有 hisi-fwpkg image 步骤、也没有中间 .img。脚本只用 hisi-fwpkg patch-hash <elf> 就地补上 body SHA-256（flashboot 即便关了 secure-verify 也仍校验 hash，secure-off 只跳过 ECC 签名，不跳过 hash），然后用补丁版 probe-rs download 把这个补好 hash 的 ELF 直接写进 flash，reset 复位，并（若设了 PORT）在复位前就开始抓 UART0 输出。

它依赖补丁版 probe-rs fork 和 hisi-fwpkg——脚本启动时会检查这两个二进制在不在。

用法

用 per-target runner 环境变量覆盖（target 是 riscv32imfc-unknown-none-elf，转成大写下划线即环境变量名）：

CARGO_TARGET_RISCV32IMFC_UNKNOWN_NONE_ELF_RUNNER=hil/cargo-run-hw.sh \
    cargo run -p blinky --release

要边烧边看串口，再加 PORT：

CARGO_TARGET_RISCV32IMFC_UNKNOWN_NONE_ELF_RUNNER=hil/cargo-run-hw.sh \
PORT=/dev/ttyUSB0 \
    cargo run -p uart_hello --release

环境变量

脚本全部参数都有合理默认：

装的 probe-rs 内置库里若没有 WS63 描述，必须显式给 PROBE_YAML=/path/HiSilicon_WS63.yaml（fork 自带）。本地编译的 fork 用 PROBE_RS=/home/.../probe-rs/target/debug/probe-rs。

典型一条龙（指定 fork 二进制 + yaml + 抓串口 15 秒）：

CARGO_TARGET_RISCV32IMFC_UNKNOWN_NONE_ELF_RUNNER=hil/cargo-run-hw.sh \
PROBE_RS=/home/me/probe-rs/target/debug/probe-rs \
PROBE_YAML=/home/me/probe-rs/targets/HiSilicon_WS63.yaml \
PORT=/dev/ttyUSB0 UART_BAUD=115200 MONITOR=15 \
    cargo run -p uart_hello --release

与模板 justfile 的对应

从模板生成的工程（见如何从模板新建一个工程）用 just 封装了同样的流程：

• WS63：just flash ≈ 这里的「补 hash + download + reset」（hisi-fwpkg patch-hash → probe-rs download <elf> → probe-rs reset）；just run-hw 则等价于在补好 hash 的 ELF 上跑 probe-rs run（顺带抓 RTT/semihosting）。
• 要让 cargo run/just run-hw 烧真机而非 QEMU，是同一套机制：模板的 just run 走 QEMU，烧真机用 just flash/just run-hw（或在工程里照本篇加一条 run-hw 配方，把 CARGO_TARGET_..._RUNNER 指向 cargo-run-hw.sh）。

WS63 的 just flash 实现就是上面三步的等价命令，区别只是用 justfile 变量（CHIP/CHIP_DESC）代替环境变量。

BS2X（BS21/BS20）没有链接期 boot-header，仍走「route 1」：just image 用 hisi-fwpkg image -o app.img <elf> 后打包，just flash 再把 .img 按 --binary-format bin --base-address {{APP_ADDR}} 写到 app 分区。本篇的 WS63 runner 不适用于 BS2X。

如何运行 HIL 冒烟测试

hil/hil-smoke.sh 把每个示例逐个烧到真机、读串口、断言它打印了预期的标记串。它验证 QEMU 证明不了的部分——真实时钟/时序、真实外设（尤其是修正后的 24 MHz TCXO 定时器和 160 MHz UART 波特基准）。HIL 框架背景见HIL 测试框架，全部标记串见HIL 标记串与环境变量。

前提：板子接好、UART0 接到 host、烧录环境就绪（见用 probe-rs 烧录，hil-smoke 默认通过 hil/flash.sh 烧录，即默认 METHOD=probe-rs）。

运行

PORT=/dev/ttyUSB0 PROBE_RS_YAML=/path/HiSilicon_WS63.yaml hil/hil-smoke.sh

走厂商烧录路径时把 flash.sh 那套环境变量带上：

METHOD=hisiflash PORT=/dev/ttyUSB0 \
    LOADERBOOT=/path/loaderboot.bin ADDRESS=0x230000 \
    hil/hil-smoke.sh

环境变量（与 hil/flash.sh 同：PORT/BAUD/LOADERBOOT/ADDRESS/HISIFLASH/PROBE_RS_YAML…），外加：

它检查哪些标记串

脚本逐示例烧录后，在 SETTLE 秒内 grep -E 串口输出找下面的模式（命中即 PASS）：

两个示例不在自动断言里：blinky（GPIO0 翻转无 UART——用 LED / 逻辑分析仪看）、semihost_selftest（需要调试器的 semihosting——裸 HIL 跳过）。

读懂结果

• 每个 check 打印 PASS: '<pat>' seen 或 FAIL。FAIL 时会把串口最后几行 / flash 错误尾部打印出来帮你定位。
• 末行汇总 HIL SMOKE: PASS（退出码 0）或 HIL SMOKE: FAIL（退出码 = 失败数 / 非零）。
• 常见 FAIL 原因：
  • flash failed：烧录环境没配好（缺 yaml/LOADERBOOT/探针），看尾部错误。
  • 标记串没出现但板子像在跑：UART_BAUD 不对（示例用 8N1，默认 115200），或 SETTLE 太短没等到输出——调大 SETTLE。
  • spi_loopback FAIL：真机上没短接 MOSI↔MISO（QEMU 会自环，真机不会）。

封装与 CI

• .claude/skills/hil-smoke 是这个脚本的 wrapper skill，给 agent 一键跑全套 HIL 冒烟。
• .github/workflows/hil.yml 在 self-hosted runner（接了真板子的机器）上跑同一脚本，把真机回归纳入 CI。

如何用 probe-rs 调试与读内存

烧录之外，补丁版 probe-rs fork 还能 attach 上去读内存、读 CSR、复位到指定状态、下硬件断点。本篇是真机诊断的常用招式。

全部命令都需要 fork（--branch add-hisilicon-ws63-bs21）+ 其 HiSilicon_WS63.yaml。下面为简洁省略了 --chip-description-path HiSilicon_WS63.yaml，实跑时按需补上（或用 PROBE_RS_YAML/--chip-description-path）。

读内存 / flash

# 读 app 镜像头开头 16 个 word（验证 0x300 头烧对没）
probe-rs read --chip WS63 b32 0x00230000 16

# 读 app 入口前几条指令
probe-rs read --chip WS63 b32 0x00230300 8

read <宽度> <地址> <个数>，宽度 b8/b32 等。地址直接给绝对物理地址（内存映射见内存映射）。

复位行为：reset_and_halt 落在复位向量

本端口修了 resethaltreq，所以 reset_and_halt 现在真的停在复位向量 0x100000（而不是任意位置）。这让「复位后第一条指令开始单步」成为可能：

probe-rs reset --chip WS63                 # 复位并运行
# attach + halt 在复位向量（GUI/脚本里用 reset_and_halt）

复位后 core 从 mask ROM（0x100000）起跑，ROM 再跳 flashboot、flashboot 跳 app（0x230300）。整条链见启动流程。

读 CSR

attach 后可读 RISC-V CSR（mstatus/mepc/mcause/mtvec…）定位 trap：

# 在 halt 状态下读（具体子命令依 fork 版本，常见为 probe-rs read 的 CSR 形式或 GUI）
probe-rs read --chip WS63 b32 0x00230300 4   # 读应用代码确认在跑你的程序

mcause/mepc 对排「跑飞到 ROM」最有用：若 halt 时 PC 在 0x10xxxx 区间，说明根本没进 app（多半是 0x300 头没烧对，见排错）。

抓住 app 入口：在 0x230300 下硬件断点

复位后直接 halt 经常停在 mask ROM 里，而不是你的程序——因为 ROM/flashboot 要先跑一段。要抓到「应用刚开始执行」的那一刻，在 app 入口 0x230300 下一个硬件断点，再复位运行，core 会停在你的第一条指令而不是 ROM：

设硬件断点 @ 0x230300  →  reset run  →  命中断点（已在 app 入口）

这正是 HIL 诊断里 examples/trapdump.rs 那类「trap dump」模式的做法：上电后在 app 入口设硬件断点，命中后 dump 寄存器/CSR/栈，确保你看到的是应用状态而不是落在 mask ROM 里的假象。把它当成「真机版 panic backtrace」——QEMU 给不了真实时序下的现场。

Dump ROM

mask ROM 在 0x100000，可整段读出来离线分析（启动早期行为、ROM 边界，见启动流程）：

# 读 ROM 头部若干 word（按需扩大个数 / 写文件留存）
probe-rs read --chip WS63 b32 0x00100000 64

ROM 是 mask ROM——只读、不可改。dump 出来是为读懂启动链和定位「PC 卡在 ROM」的问题；mask ROM + SFC 是 QEMU 复刻不了的两处真机边界。

排错

• attach 不上 / 找不到芯片：装的是上游 probe-rs 不是 fork；或没给 yaml。见用 probe-rs 烧录的排错。
• halt 后 PC 一直在 0x10xxxx：还在 mask ROM，没进 app——用上面的「app 入口硬件断点」抓应用，并确认烧的是 0x300 头镜像。
• "Flash Init Fail" 类提示：本端口里通常非致命，不影响 read/reset。

如何从模板新建一个工程

要从零起一个 WS63/BS2X 应用，用 cargo generate 从模板仓库 hisi-rs-template 生成——它帮你配好工具链、链接脚本、依赖和一份 justfile，开箱即可构建+烧录。

前提：已安装 hisi-riscv 工具链；cargo install cargo-generate。

生成

cargo generate --git https://github.com/hispark-rs/hisi-rs-template

交互式会问两个选项：

• chip（目标芯片）：ws63 / bs21 / bs21e / bs22 / bs20（默认 ws63）。BS2X 几个 SKU 在 HAL 里是同一颗芯片（chip-bs21），差别只在 L2RAM 大小（bs20=128K，其余 160K，写在 memory.x）和 QEMU machine 名。
• starter（起步应用）：blinky / uart_hello / async（默认 blinky）。
• 还会问 app 分区 flash 地址（WS63 默认 0x00230000，BS2X 默认 0x00090000）——没有自定义分区表就用默认。

非交互式可一把给定：

cargo generate --git https://github.com/hispark-rs/hisi-rs-template \
    --name my-app --define chip=ws63 --define starter=blinky --silent

WS63 的内存布局来自 hisi-riscv-rt 自带的链接脚本，所以模板不为 WS63 生成 memory.x；BS2X 才需要工程级 memory.x（模板会带）。

生成的 justfile

工程带一个 justfile（cargo install just），封装了硬件验证过的流程：

烧录配方的前提（构建/run 不需要这些）：hisi-fwpkg、补丁版 probe-rs fork + 其 HiSilicon_WS63.yaml。CHIP/CHIP_DESC/APP_ADDR 可在命令行覆盖，例如：

just CHIP_DESC=~/probe-rs/HiSilicon_WS63.yaml flash

第一次构建 + 烧录

WS63（route 2，链接期已带 0x300 头）：

cd my-app
just build          # 编出 release ELF（boot-header feature 已把 0x300 头嵌进 ELF）
just patch          # hisi-fwpkg patch-hash 补 body 的 SHA-256
just flash          # probe-rs download 直接烧裸 ELF 并复位（需 probe-rs fork + yaml）

just flash 依次做了这些事：先 just patch（hisi-fwpkg patch-hash {{elf}} 把 body 的 SHA-256 填进链接期已嵌好的 0x300 头），再 probe-rs download --chip WS63 ... {{elf}} 把这份裸 ELF 直接烧到芯片（无中间 .img），最后 probe-rs reset 复位运行。

BS2X（route 1，build 后才补 0x300 头打成 .img）：

cd my-app
just build          # 编出 release ELF
just image          # hisi-fwpkg image 补 0x300 头 → *.img
just flash          # probe-rs download 把 *.img 烧进 app 分区并复位

烧 BS2X 时把 CHIP/APP_ADDR 调成对应值（BS2X 基址 0x00090000，尚未 HIL 验证，先对照分区表确认）。

之后

• 不想用 just、想理解每一步 → 如何打包镜像 + 如何用 probe-rs 烧录。
• 想让 cargo run 直接烧真机 → 如何用硬件 runner。
• 要加自己的外设驱动 → 如何新增一个外设驱动。

如何新增一个外设驱动

给 hisi-riscv-hal 加一个新外设驱动，照仓库统一的「驱动模块范式」走，再配一个带 UART PASS 标记的示例让 HIL 能验证它。本篇是配方；范式背后的设计取舍见 HAL API 总览 和外设清单与覆盖情况，也对照仓库 CLAUDE.md 的「Driver Module Pattern」一节。

配置接口必须遵守类型化配置约定 ——「能编译就能在硅片上跑」是本项目头号 API 约定:配置面用校验 newtype / type-state / 自起时钟收紧,不留「能写出来却被静默 clamp/截断/没接时钟」的参数;操作面保持 embedded-hal 的 Result。落地按 docs-first(先改文档再写代码),用 .claude/skills/typed-config/scan.sh 扫候选,参考 pwm.rs。

0. 确认外设单例存在

驱动消费的是 crates/hisi-riscv-hal/src/peripherals.rs 里用宏生成的外设单例。文件里两个宏：

• peripheral!($name, $pac_ty) —— 为某个 PAC 类型生成带生命周期的 ZST $name<'d>，附 steal()、ptr()、register_block()。
• peripherals!(...) —— 生成 Peripherals 结构体，带 take()（安全单例）和 steal()（unsafe）。

若你的外设的 PAC 类型还没被 peripheral! 包过，先加一行（注意按芯片放进对应的 #[cfg(feature = "chip-ws63")] / chip-bs21 块），并在对应的 peripherals!(...) 列表里加 字段 => 类型。例如已有的：

peripheral!(Spi0, crate::soc::pac::Spi0);
// ...
peripherals!(
    // ...
    SPI0 => Spi0,
    // ...
);

1. 写驱动模块

在 crates/hisi-riscv-hal/src/ 加 <name>.rs，并在 lib.rs 加 pub mod <name>;（按芯片可加 #[cfg(...)]）。模块结构：

//! <Name> driver for WS63.
use crate::peripherals::MyPeriph;
use core::marker::PhantomData;

/// 配置项：用一个 `Config` 结构体 + `Default`（对齐 spi/uart 的 `Config`）。
#[derive(Debug, Clone, Copy)]
pub struct Config {
    pub frequency: u32,
    // ...
}
impl Default for Config {
    fn default() -> Self { Self { frequency: 1_000_000 } }
}

pub struct MyDriver<'d> {
    _peripheral: MyPeriph<'d>,
}

impl<'d> MyDriver<'d> {
    /// 构造即配置：消费外设单例（保证独占 + 防 use-after-drop）。
    pub fn new(peripheral: MyPeriph<'d>, config: Config) -> Self {
        let me = Self { _peripheral: peripheral };
        // ...用 me.regs() 配置硬件...
        me
    }

    /// 拿到 PAC 寄存器块。指针是静态物理 MMIO 地址，恒有效。
    fn regs(&self) -> &'static crate::soc::pac::myperiph::RegisterBlock {
        // SAFETY: PAC 指针是静态物理 MMIO 地址，始终有效。
        unsafe { &*MyPeriph::ptr() }
    }

    // ...API 方法...
}

要点：

• 构造函数消费外设单例（MyPeriph<'d>），靠生命周期 'd 防止 token 被 drop 后还用——这是仓库的安全主线。
• regs() 返回 &'static RegisterBlock，内部 unsafe { &*MyPeriph::ptr() }，把 unsafe 寄存器读写收口在驱动方法里。
• #![no_std]：不用堆 / Vec，要缓冲区用定长数组。

多实例外设（UART/I2C/SPI/DMA 那种）

同一类外设有多个实例时，用 PhantomData<&'d T> 区分，并为每个实例给独立构造函数（不是统一 new()，因为每个实例配置可能不同）：

pub struct MyBus<'d, T> { idx: u8, _peripheral: PhantomData<&'d T> }
impl<'d> MyBus<'d, Inst0<'d>> { pub fn new_inst0(_p: Inst0<'d>, c: Config) -> Self { /* ... */ } }
impl<'d> MyBus<'d, Inst1<'d>> { pub fn new_inst1(_p: Inst1<'d>, c: Config) -> Self { /* ... */ } }

实例到寄存器块的映射用一个按 idx 分发的小函数（参考 spi.rs 的 spi_regs(idx)）。

2. 实现 embedded-hal trait

在模块末尾为驱动实现对应的 embedded-hal 1.0 trait（SPI 实现 spi::SpiBus、I2C 实现 i2c::I2c、串口实现 embedded-io 等），先 ErrorType 再具体 trait。对照 spi.rs 底部：

impl embedded_hal::spi::Error for SpiError { /* kind() */ }
impl embedded_hal::spi::ErrorType for Spi<'_, Spi0<'_>> { type Error = SpiError; }
impl embedded_hal::spi::SpiBus for Spi<'_, Spi0<'_>> { /* read/write/transfer/flush */ }

开了 async feature 还可以补 embedded-hal-async 的对应实现（多以阻塞版兜底，见 spi.rs 的 embedded_hal_async::spi::SpiBus）。

3. Sealed trait（需要时）

如果你要引入「只能内部实现」的标记 trait（比如限定哪些类型能当某外设的输入/输出，或 DMA word），加在 private.rs：以 Sealed 为 supertrait，外部就无法实现。现有的有 DmaWord、PeripheralInput、PeripheralOutput。不要复活已删掉的空 DriverMode/Blocking/Async 标记 trait——它们没有真实 async 后端时纯属误导。

4. 配一个带 PASS 标记的 HIL 示例

新建一个示例 crate（如 examples/ws63/myperiph_demo），用 UART0 打印一个HIL 能 grep 的标记串，并在根 Cargo.toml 的 members / default-members 里登记它。骨架（仿 spi_loopback）：

#![no_std]
#![no_main]
use hisi_riscv_hal::Peripherals;
use hisi_riscv_hal::uart::{Config as UartConfig, Uart};
use hisi_riscv_rt::entry;

#[entry]
fn main() -> ! {
    let p = Peripherals::take().unwrap();
    let uart = Uart::new_uart0(p.UART0, UartConfig::default());

    let mut dev = hisi_riscv_hal::myperiph::MyDriver::new(p.MYPERIPH, Default::default());
    match dev.do_thing() {
        Ok(_)  => uart.write(0, b"  MyPeriph OK\r\n"),   // <- HIL PASS 标记
        Err(_) => uart.write(0, b"  MyPeriph FAIL\r\n"),
    }
    loop { core::hint::spin_loop(); }
}

#[panic_handler]
fn panic(_: &core::panic::PanicInfo) -> ! { loop { core::hint::spin_loop() } }

标记串约定：用一个稳定、唯一、好 grep 的短语（如 MyPeriph OK）。然后把它登进 HIL 冒烟脚本，让 hil/hil-smoke.sh 自动断言它（脚本里加一行 check myperiph_demo "MyPeriph OK" "..."，标记串清单见HIL 标记串与环境变量）。

5. 验证

cargo check -p hisi-riscv-hal              # 驱动能编过（host 上 check）
cargo build -p myperiph_demo --release     # 示例能编出 ELF

再按如何运行 HIL 冒烟测试烧到真机看标记串。

提交时记得：HAL 与示例若在 submodule 里，先在 submodule 内 commit，再更新父仓库的 submodule 指针（见 CLAUDE.md）。

本章导读 · Reference

参考章节是信息导向的查阅资料：精确、结构化、可逐项检索。这里只陈述事实（地址、大小、标志位、字段偏移、签名、默认值），不讲教程，不讲原理。需要“怎么做“请看 操作指南，需要“为什么“请看 原理与背景。

本章所有事实均直接取自源码（memory.x、HAL 源文件、hisi-fwpkg 源、HIL 脚本、工具链配置）。

速查入口

内存映射

本页复现 WS63 的内存布局，事实取自 crates/hisi-riscv-rt/memory.x 与 crates/hisi-riscv-rt/asm/startup.S。默认配置：576K SRAM、16K ITCM、16K DTCM。TCM 与 SRAM 大小可经 CONFIG 标志配置（参见 fbb_ws63）。

启动流程的“为什么“见 启动流程。

内存区域（MEMORY{}）

BOOTROM + ROM 共 304K（36K + 268K），地址连续（0x100000–0x14C000）。

关键地址

flashboot 无条件跳到 app_partition + 0x300，故 app 镜像必须带 0x300 字节 HiSilicon 镜像头。镜像头字段见 应用镜像格式。

导出的链接符号（PROVIDE）

区域符号（用于运行时重定位）：

riscv-rt v0.14 所需符号：

数据/BSS 符号（memory.x 中为占位 0，权威值在 layout.ld）：__sidata、__sdata、__edata、__sbss、__ebss。

栈大小（可被用户覆盖）

IRQ/异常/NMI 栈顶在 layout.ld 的 .stacks 段中权威定义（trap 处理器引用它们，KEEP 的 .trap 段经 --gc-sections 保活）。

区域别名（riscv-rt v0.14 REGION_ALIAS）

复位向量

startup.S 中 reset_vector 位于 .text.entry 段，链接为程序内存第一项，内容为 j HandleReset。HandleReset 依次：禁用 PMP（pmpcfg0..3 = 0）、以 vectored 模式（mtvec[1:0]=01）装载 trap_vector、关中断、使能 FPU（mstatus.FS = 0b11）、初始化 gp。

复位地址 0x100000 是掩膜 ROM 入口；上电后由 ROM 经 flashboot 转交到 app 入口 0x230300。

示例目录与验证标记串

examples/ws63/ 下 18 个示例。下表的成功标记串、失败标记串、是否需接线均直接取自各 examples/ws63/<name>/src/main.rs。所有 UART 输出走 UART0 @ 115200 8N1；semihost_selftest 走 RISC-V 半主机（semihosting），不走 UART。

如何构建/运行见 构建一个示例 与 在 QEMU 里运行。HIL 标记串汇总见 HIL 标记串与环境变量。

一览表

图例（真机列）：✅ 已在真实硅片上验证通过；⚠️ QEMU 通过、真机尚未逐一验证（bring-up 进行中）；❌ 该观测通道真机不适用。截至 2026-06-14，只有 blinky 经硅片确认；其余 UART 类示例的真机标记串套件正在 bring-up（见 HIL 测试框架）。

注：

1. gpio_irq / embassy_async_io 把 GPIO0 pin0 设为输出，依赖 ws63-qemu 建模的 输出→输入 自环产生边沿；真机需相应注入/接线。
2. i2c_scan：QEMU 下无真从机，no devices acked 是正常结果而非失败。
3. i2c_scan 真机需挂接真实 I2C 从机才会有 found device。
4. spi_loopback：QEMU 把 SPI0 TX FIFO 环回 RX，无需跳线；真机必须短接 MOSI↔MISO。
5. net_ping 需 QEMU user netdev（-nic user，默认），纯软件/SLIRP，无需外部网络。
6. net_ping 依赖 ws63-qemu 合成 MAC（ws63-netmac @ 0x4421_0000），真机无此通道。
7. rf_port_demo / wifi_blob_link 需厂商 blob libwifi_rom_data.a（ws63-RF 子模块）链接到位。
8. semihost_selftest 需 QEMU -semihosting；真机半主机陷阱为 no-op，exit 只自旋。
9. uart_hello 真机上已确认能跑到 main 并运行（probe-rs 单步/采样验证），但 UART banner 在 115200 下暂不可读 —— 疑似该例不做时钟初始化、波特率基于 QEMU 默认时钟假设，真机 UART 时钟不同。属已知 bring-up 待修项。

成功标记串（逐字，用于 grep）

blinky 无 UART 输出，只能由 GPIO0 翻转观测。

失败标记串

其余示例（blinky、gpio_irq、timer_irq、reset_demo、async_delay、embassy_*、uart_hello）无显式 FAIL 串；失败表现为成功标记串始终不出现。各 UART 示例的 #[panic_handler] 仅静默自旋（不输出），唯一例外是 semihost_selftest（写 semihost_selftest: PANIC\n 并 exit(2)）。

semihost_selftest 退出码

机制：exit(code) 发 SYS_EXIT_EXTENDED (0x20) + ADP_STOPPED_APPLICATION_EXIT (0x2_0026) 块 [reason, code]，使 QEMU 进程退出码等于 code。console 写经 SYS_WRITE0，串末需 NUL（\0）。

HAL API 总览

hisi-riscv-hal 是手写的安全驱动层，建模自 esp-hal 模式。本页给出公开 API 的结构图。

完整 API 文档（rustdoc）↗ —— 在线:https://hispark-rs.github.io/hisi-riscv-rs/api/（hisi-riscv-hal / ws63-pac / hisi-riscv-rt，与本手册同站部署，CI 自动构建）;本地:cargo doc -p hisi-riscv-hal --open。本页只是结构图,逐项 API 以 rustdoc 为准。

事实取自 crates/hisi-riscv-hal/src/lib.rs 及各模块头。

模块全清单与外设映射见 外设清单；async/embassy 的原理见 async 与 embassy。

crate 约定

• #![no_std]（cfg(test) 下链接 std 供主机单测）。
• 必须恰好选一个芯片特性：chip-ws63（默认）或 chip-bs21（二者互斥，否则 compile_error!）。
• 依赖 embedded-hal 1.0、embedded-hal-nb 1.0、embedded-io 0.6、portable-atomic。

顶层导出

单例模式（peripherals.rs）

两个宏生成单例：

• peripheral!($name, $pac_ty) — 生成生命周期参数化 ZST $name<'d>，带 steal()、ptr()、register_block()。
• peripherals!(...) — 生成 Peripherals 结构，带 take() -> Option<Self>（安全，仅一次）与 steal()（unsafe）。

let p = hal::Peripherals::take().unwrap();        // 一次性安全取得
let uart = Uart::new_uart0(p.UART0, Config::default());

每个驱动经构造函数消费其外设 token（'d 生命周期参数防止 Peripherals 失效后再用）。

GPIO 三级驱动（gpio.rs）

配置结构：InputConfig { pull }、OutputConfig { open_drain, initial_high }。另有 Io::new(IoConfig) 顶层封装。

多实例外设

UART / I2C / SPI / DMA 用 PhantomData<&'d T> 区分实例，构造函数按实例分开（每实例可能配置不同）：

SPI Config { frequency, mode, data_bits }；UART Config { baud, data, parity, stop }。

单外设驱动（new() 模式）

多数驱动遵循 DriverName::new(peripheral)：Watchdog::new、TimerDriver::new、TcxoDriver::new、RtcDriver::new、LsAdc::new、I2sDriver::new、PwmChannel::new(&Pwm, channel)、SfcDriver::new、PkeDriver::new、SpaccDriver::new、KmDriver::new、TrngDriver::new、TempSensor::new、EfuseDriver、System::new(SysCtl0, GlbCtlM, CldoCrg)。完整签名见各模块 rustdoc。

时钟（clock.rs / clock_init.rs，仅 chip-ws63）

• clock_init::init_clocks(&sys_ctl0, &cldo_crg) -> SystemClocks — 为不经 flashboot 启动的固件初始化系统时钟。
• ClockControl 包裹 CldoCrg，两种访问：直接方法（enable_uart() 等）或 RAII PeripheralGuard（AtomicU8 引用计数）。
• Peripheral 枚举把每个外设映射到 (cken_register_index, bit_position)。

多数外设访问寄存器前需经 CLDO_CRG 门控使能；复位默认即使能；WDT/RTC/TCXO 常开。

sealed trait（private.rs）

Sealed 作为超 trait，阻止外部实现 DmaWord、PeripheralInput、PeripheralOutput。（旧的空 DriverMode/Blocking/Async 标记 trait 已移除。）

特性（features）

async/embassy 在无原子的 WS63 上经 portable-atomic + critical-section 工作。

外设清单与覆盖情况

crates/hisi-riscv-hal/src/*.rs 下的全部驱动模块。基地址取自各模块的 doc 注释/常量或 safety.rs 断言；标 “—” 者源文件头未列。“芯片“列：默认构建为 chip-ws63，标注 BS21 的模块仅在 chip-bs21 下编译。

完整 API 见 HAL API 总览；驱动如何新增见 新增一个外设驱动。

驱动模块表

裸板自检：✅ 可在裸板上自验（无需外接器件）；⚠️ 需外接器件/接线/从机；n/a 非外设驱动。

DMA 控制器

Peripherals 实例（WS63，chip-ws63，35 个）

SYS_CTL0、SYS_CTL1、GLB_CTL_M、CLDO_CRG、IO_CONFIG、GPIO0、GPIO1、GPIO2、ULP_GPIO、UART0、UART1、UART2、I2C0、I2C1、SPI0、SPI1、PWM、I2S、LSADC、DMA、SDMA、SFC_CFG、TIMER、WDT、RTC、TCXO、TSENSOR、EFUSE、SPACC、PKE、KM、TRNG、RF_WB_CTL、SHARE_MEM_CTL、FAMA_REMAP。

Peripherals 实例（BS21，chip-bs21，28 个）

GLB_CTL_M、GPIO0–GPIO4、ULP_GPIO、UART0–UART2、I2C0/I2C1、SPI0–SPI2、PWM、DMA、SDMA、TIMER、WDT、RTC、TCXO、TRNG、GADC、KEYSCAN、QDEC、PDM、USB。

全部 PAC 外设均有 HAL 封装。寄存器行为以 fbb_ws63 / fbb_bs2x C SDK 为 ground-truth。

工具链与编译目标

WS63 用自定义 hisi-riscv 工具链构建。事实取自 rust-toolchain.toml、.cargo/config.toml、CLAUDE.md。

安装步骤见 安装 hisi-riscv 工具链；硬浮点选型原理见 硬浮点工具链。

工具链 / 目标速查

目标三元组写法 riscv32imfc（注意是 imfc，含硬浮点 f、不含原子 a）。CLAUDE.md 中出现的 riscv32imafc-unknown-none-elf 是 --target 覆盖示例，并非默认目标。

builtin 目标（无需 -Z build-std）

riscv32imfc-unknown-none-elf 在 hisi-riscv 工具链里被烤进为 builtin 目标，工具链随附该目标的预编译 core/alloc，故构建不需要 nightly 的 -Z build-std。工具链是芯片中立的（ws63 + bs2x 都目标 riscv32imfc）。

无原子的处理：原子 load/store 降为普通 ld/st（单 hart）；RMW 经 portable-atomic 的 critical-section polyfill。不发射 lr.w/sc.w/amo*。

rust-toolchain.toml

[toolchain]
channel = "hisi-riscv"

该工具链不是可分发的 rustup channel，必须先手动安装并 rustup toolchain link hisi-riscv（见下“安装“）。

.cargo/config.toml

[build]
target = "riscv32imfc-unknown-none-elf"

[target.riscv32imfc-unknown-none-elf]
runner = "gdb-multiarch"
rustflags = ["-C", "link-arg=--no-relax"]

安装（release URL 形态）

按主机选 tarball（linux x86_64/aarch64、macOS x86_64/aarch64、windows x86_64）：

curl -fLO https://github.com/hispark-rs/hisi-riscv-rust-toolchain/releases/download/v1.96.0-2/hisi-riscv-rust-1.96.0-x86_64-unknown-linux-gnu.tar.gz
tar xzf hisi-riscv-rust-1.96.0-*.tar.gz
rustup toolchain link hisi-riscv "$PWD/stage2"

release URL 形态：

https://github.com/hispark-rs/hisi-riscv-rust-toolchain/releases/download/<tag>/hisi-riscv-rust-1.96.0-<host-triple>.tar.gz

当前 <tag> = v1.96.0-2；<host-triple> 如 x86_64-unknown-linux-gnu、aarch64-unknown-linux-gnu、x86_64-apple-darwin、aarch64-apple-darwin、x86_64-pc-windows-msvc。链接目标为解压后的 stage2 目录。

应用镜像格式与签名

WS63 app 镜像（flashboot 从 flash 0x230000 加载的对象）的字段布局。事实逐字段取自 hisi-fwpkg/crates/hisi-fwpkg/src/image.rs 与 src/fwpkg.rs。所有多字节字段为小端。

构建命令见 打包成可启动镜像；安全启动原理见 安全启动与签名。

整体布局

+--------------------------------------+ 0x000
| image_key_area_t   (0x100 字节)      |  magic = 0x4B0F2D1E
+--------------------------------------+ 0x100
| image_code_info_t  (0x200 字节)      |  magic = 0x4B0F2D2D
+--------------------------------------+ 0x300  = APP_IMAGE_HEADER_LEN
| code body（原始 .text/.rodata/...）  |  链接到 0x230300 运行
+--------------------------------------+

0x300 字节前缀为定长镜像头。secure boot 关闭（efuse SEC_VERIFY_ENABLE == 0）时，flashboot 的 verify_image_* 在检查任何签名/body hash 之前短路成功，故签名字段从不被读。关键只有两点：头恰好 0x300 字节、其后是链接到 0x230300 的真实代码。

常量

密钥区 image_key_area_t（偏移 0x000，长度 0x100）

代码信息区 image_code_info_t（偏移 0x100，长度 0x200；下表偏移相对区起点）

code_area_hash（区内偏移 0x28，即镜像绝对偏移 0x128）是 body 的真实 SHA-256，与厂商 sign_tool 一致。

code_enc_flag（区内 0x48，绝对 0x148）= 0x3C7896E1 是非零哨兵：flashboot ws63_flash_encrypt_config() 做 if (code_enc_flag == FLASH_NO_ENCRY_FLAG) return;，故零值反而会令 flashboot 尝试配置 on-the-fly 解密而启动失败。明文镜像必须用此值。

dummy-zero 字段：两个区的 ECC 签名 blob（sig_key_area、sig_code_info、sig_code_info_ext）与公钥（ext_public_key_area、die_id、protection key、iv）。

fwpkg V1 容器（fwpkg.rs）

“all-in-one” 固件包：小头 + 每分区描述符表 + 串接的分区负载。布局是 hisiflash 解析器的逆，匹配厂商 packet_create.py create_allinone()。

+----------------------------------+ 0x000
| FWPKG_HEAD (12 字节)             |  flag(4) crc(2) cnt(2) total_len(4)
+----------------------------------+ 0x00C
| IMAGE_INFO[0] (52 字节)          |  name[32] off(4) len(4) burn_addr(4)
| IMAGE_INFO[1] ...                |           burn_size(4) type(4)
+----------------------------------+
| payload[0] || 16 个 0 字节       |
| payload[1] || 16 个 0 字节       |
+----------------------------------+

常量

FWPKG_HEAD（12 字节）

IMAGE_INFO（每分区 52 字节）

分区 type

CRC

crc = CRC16/XMODEM（poly 0x1021，init 0x0000），覆盖范围为从偏移 6（cnt 字段）到描述符表末尾的字节（即 out[6..head_len]，head_len = 12 + cnt*52）。已知向量：crc16_xmodem("123456789") == 0x31C3。

每个负载后跟 16 个 0 字节分隔，计入 total_len 但不计入描述符 length。

HIL 标记串与环境变量

HIL（hardware-in-the-loop）框架的标记串与环境变量参考。事实取自 hil/hil-smoke.sh、hil/flash.sh、hil/pack.sh、hil/cargo-run-hw.sh。

HIL 框架原理见 HIL 测试框架；运行步骤见 运行 HIL 冒烟测试。

串口约定

hil-smoke.sh 检查的标记串

hil-smoke.sh 逐例烧录后读 UART，用 grep -qE 匹配下列模式（check <example> <egrep> <desc>）：

blinky（GPIO 翻转无 UART，需 LED/逻辑分析仪）与 semihost_selftest（需 debugger 半主机）在裸 HIL 跳过。总结果：全过打印 HIL SMOKE: PASS，否则 HIL SMOKE: FAIL 并 exit 1。

各示例标记串（HIL 期望）

完整 18 例标记串见 示例目录与验证标记串。

环境变量

flash.sh

烧录方式选 METHOD=（默认 probe-rs）。

hil-smoke.sh（在 flash.sh 变量之外另加）

pack.sh

默认 app 分区地址：ws63 0x00230000、bs21 0x00090000。

cargo-run-hw.sh（cargo runner）

cargo 以 <runner> <built-elf> 调用，脚本把 ELF 打包成 0x300-header 镜像、probe-rs download、复位、（设了 PORT 则）流式 UART0。

启用：CARGO_TARGET_RISCV32IMFC_UNKNOWN_NONE_ELF_RUNNER=hil/cargo-run-hw.sh cargo run -p blinky --release（或 just run-hw）。

CLI 工具速查

本项目工具的命令参考：hisi-fwpkg、补丁版 probe-rs、QEMU、hisiflash。事实取自 hisi-fwpkg-cli/src/main.rs、HIL 脚本、tutorials。

镜像字段布局见 应用镜像格式；烧录步骤见 用 probe-rs 烧录、用 hisiflash 烧录。

hisi-fwpkg

把编译产物（ELF 或裸 bin，按 magic 自动识别）打包成 HiSilicon app 镜像 / fwpkg。

cargo install hisi-fwpkg-cli

hisi-fwpkg image（路线 1 / BS2X）

ELF/bin → app 镜像（0x300 header || body，含真实 body SHA-256）。这是 BS2X 的路线 1 产物：BS2X 暂无 link-time boot-header，构建后用 image 单独生成可启动 .img，再烧到 app 分区。

WS63 走 路线 2：boot-header feature 已把 0x300 头烤进 ELF（链接期），构建后只需 hisi-fwpkg patch-hash <elf>（见下）补 body hash，直接烧裸 ELF——不再有中间 .img，也不走 image。

# BS2X 路线 1：
hisi-fwpkg image app -o app.img

hisi-fwpkg patch-hash（路线 2 / WS63）

WS63 的 路线 2 post-link 步骤：原地把裸 ELF（已含 link-time 0x300 头）的 body SHA-256 填回头部。无输出文件、无 .img，补好后直接 probe-rs download <elf> 烧、probe-rs run <elf> 跑。

硅片上 flashboot 始终校验 body hash：即便 efuse SEC_VERIFY_ENABLE==0（secure-off）也只跳过 ECC 签名，不跳过 hash——所以镜像需要 真实 body hash，没有任何「dummy 签名」能让它启动。patch-hash 正是用来填这个真实 hash 的。

# WS63 路线 2：
hisi-fwpkg patch-hash blinky

hisi-fwpkg pack

上面的镜像再包进单分区 fwpkg（V1 容器 + CRC），供厂商 hisiflash 烧录。

hisi-fwpkg pack blinky -o blinky.fwpkg --chip ws63 --name app

probe-rs（补丁版 fork）

需补丁版 fork hispark-rs/probe-rs（branch add-hisilicon-ws63-bs21）——上游 probe-rs 尚无 WS63 target 与 ws63-sfc flash 算法。需 fork 提供的 HiSilicon_WS63.yaml 芯片描述。

本项目用到的子命令与标志：

调试与读内存细节见 用 probe-rs 调试与读内存。

QEMU

姊妹仓 hisi-riscv-qemu 的 QEMU fork，提供 -M ws63 / bs21 / bs21e / bs22 / bs20 机器。软件在环，无需硅片。

qemu-system-riscv32 -M ws63 -nographic -bios none -kernel <elf>

QEMU 模型原理见 QEMU 模型。

hisiflash

厂商串口/YMODEM 烧录 CLI（@230400）。

cargo install hisiflash-cli

环境变量：HISIFLASH_PORT（串口）、HISIFLASH_BAUD（烧录波特，默认 921600）。

仓库清单

全部位于 GitHub 组织 github.com/hispark-rs（旧 sanchuanhehe/* URL 已重定向）。

原理与背景 · Explanation

这一章不是教你“怎么做“，也不是给你查“叫什么“的索引——它讲的是为什么： 为什么栈这样分层、为什么要一条自定义工具链、为什么一个裸 ELF 在硅片上不会启动、 为什么我们用 UART 里的一行字符串来判定一次硬件测试是否通过。

如果你想动手，去 教程 或 操作指南； 如果你想查一个确切的地址、字段或 API，去 参考。 本章是给你靠在椅背上读的——读完你会理解这套生态为什么长成现在这样， 也就更容易判断某个改动是否合理、某个故障应该往哪个方向想。

概念章节

这些章节自顶向下，把分散在各组件里的事实串成一个整体：

• 系统架构总览——crate 依赖链（svd → pac → hal → 示例，rt 管启动）、 以及那些贯穿全栈的设计取舍：no_std、用生命周期泛型保证安全、把 unsafe 寄存器访问 封进驱动、用 sealed trait 锁住扩展点。为什么这样分层。
• 类型化配置：能编译就能在硅片上跑——本项目 HAL API 的头号约定:配置面 用校验 newtype / type-state / 自起时钟收紧,操作面保持 embedded-hal 的 Result, 为什么「能写出来的值就该能跑」、以及 A/B/C/D 缺陷分类法与逐字段决策树。
• 启动流程：mask ROM → flashboot → app——从上电到 main() 的整条引导链， 以及为什么“补 0x300 头部、烧到 app 分区“是必须的，为什么一个裸 ELF 不会启动。
• 硬浮点工具链——为什么是一条把 riscv32imfc 烤进 builtin 的 自定义 rustc，而不是 -Z build-std；hard-float ABI、无原子、code model 的来龙去脉。
• async 与 embassy——阻塞驱动、async feature、embassy feature 三者的关系，以及它为什么能在一颗没有原子扩展的核上跑起来。
• 安全启动与签名——为什么开发片把 secure boot 关掉、这意味着什么、 为什么一个全零“假签名“镜像照样能启动、真正签名又需要什么。
• QEMU 模型——hisi-riscv-qemu 为什么存在、它能模拟什么、不能 模拟什么，以及 QEMU 里跑和真硅片上跑的根本差别。
• HIL 测试框架——硬件在环测试的哲学：为什么用 UART 标记串做验证通道、 QEMU↔硅片的几类分歧、以及诚实的当前 bring-up 状态。

组件深入文档

组件深入文档索引 列出了 10 篇逐组件的权威深入文档 （HAL、rt、pac、svd、示例、flashboot、RF、guide、async-embassy）。 本章的概念章节会链接进这些深入文档：概念章讲“为什么、怎么串起来“， 深入文档讲“这一个组件内部到底怎么实现“。两者互补——读概念建立全局，读深入查实现。

系统架构总览

这一篇讲的是为什么这套 Rust 代码长成这个形状——不是逐个 API 的清单（那是 HAL API 总览），也不是逐组件的实现细节（那是 组件深入文档），而是把分层、所有权模型、安全边界这几件事串成一个 能自洽解释的整体。读完你应该能回答：“如果我要加一个外设驱动，它该放在哪一层、长什么样、 为什么不能直接写寄存器。”

一条单向的依赖链

整个库栈是一条严格单向的依赖链，每一层只依赖它下面的一层：

ws63-svd (XML 真值)
   │ svd2rust 生成
   ▼
ws63-pac  ── 裸寄存器访问层（~1.5 MB lib.rs，35 个外设的 RegisterBlock）
   │
   ▼
hisi-riscv-hal  ── 手写的安全驱动（35 个源文件 + 可选 async/embassy）
   │
   ▼
examples/ws63/*  ── 应用

hisi-riscv-rt  ── 运行时（启动汇编、链接脚本、中断向量）：横切，被示例链接

这条链不是随手画的，它对应着一个明确的抽象递进：SVD 是芯片寄存器的机器可读真值， PAC 把它机械地翻成 Rust 类型，HAL 在 PAC 之上用人手写出安全、符合 embedded-hal 的驱动， 示例再在 HAL 之上写业务。每往上一层，unsafe 越少、类型越强、离硬件越远。

为什么要这么分？因为这三层的变化频率和变化原因完全不同。SVD/PAC 跟着芯片走， 芯片定了就几乎不动；HAL 跟着 Rust 嵌入式生态（embedded-hal 版本、esp-hal 的模式演进）走； 示例跟着用户需求走。把它们拆开，任何一层换代都不会逼着另外两层跟着改。 逐层的实现细节见各自的深入文档：ws63-svd、 ws63-pac、hisi-riscv-hal、 hisi-riscv-rt、ws63-examples。

为什么 PAC 必须只有一份

有一个容易被忽视、却会在链接期炸掉的约束：全仓库只能链接一个 PAC 实例。 PAC 里的 Peripherals::take() 依赖一个 DEVICE_PERIPHERALS 单例静态——如果链接进两份 PAC（比如一个来自 crates.io、一个来自本地 submodule），这个静态会重复、类型也不兼容。 所以根 Cargo.toml 用 [patch.crates-io] 把 ws63-pac 的 registry 依赖重定向到本地 submodule。这是“单一真值“原则在构建层面的体现：不只是源码单向依赖，连链接出的符号 也必须唯一。

所有权即安全：用生命周期泛型守住外设

HAL 的核心安全模型不是运行时检查，而是借 Rust 的类型系统把“外设被独占使用“编译期化。 机制有三层：

1. 外设单例：Peripherals::take() 在 critical-section 保护下只成功一次， 返回一组零大小（ZST）的外设令牌。
2. 生命周期参数化：每个令牌是 Peripheral<'d>。驱动构造器消费这个令牌 （Watchdog::new(wdt)），把 'd 借进驱动。于是“在外设令牌还活着时不能再拿到它“ 被编译器强制——use-after-drop 在编译期就过不了。
3. 多实例靠类型区分：UART/I2C/SPI/DMA 这些有多个实例的外设，用 PhantomData<&'d T> + 每实例构造器（new_uart0 / new_uart1）把实例编进类型， 避免“两段代码同时以为自己独占 UART0“。

这套模式直接借鉴了 esp-hal——不是为了好看，而是因为它把资源冲突这类最难调试的嵌入式 bug 挡在了编译期。代价是 API 略繁（不能用统一的 new()），但换来的是“能编译过就不会有两个 驱动抢同一个外设“。

unsafe 的边界：把它关进驱动里

裸寄存器访问本质上是 unsafe 的——你在往任意物理地址写值，编译器无从知道这是否合法。 这套架构的处理方式不是消灭 unsafe，而是把它收敛：

• PAC 层暴露的 reg.write(|w| w.bits(val)) 是 unsafe 的；
• HAL 的每个驱动方法在内部 unsafe { ... } 这一句，外部 API 全是安全的；
• 应用层（示例）完全不写 unsafe。

也就是说，unsafe 被压缩成 HAL 里一条条短小、可审计的语句。一次架构评审 （见各组件文档里的“评审发现“）的隐含目标就是：让每一处 unsafe 都对应一个经人核对过 寄存器手册的写入，而不是散落在应用代码里无人负责。

sealed trait：留扩展点，但不让外人乱接

HAL 用了一批 sealed trait（private.rs 里的 Sealed 超 trait）：DmaWord、 PeripheralInput、PeripheralOutput 这些 trait 外部 crate 实现不了。这是有意的—— 这些 trait 表达的是“哪些类型是合法的 DMA 字宽 / 合法的引脚功能“，它们的完整集合由硬件 决定，不该让下游随便加。sealed 让 HAL 可以放心地用这些 trait 做编译期约束 （比如 DmaChannelFor<P> 保证某外设只能配对它真正支持的 DMA 通道），而不必担心 有人实现出一个硬件根本不支持的组合。

贯穿全栈的几个决定

有几条决定不属于某一层，而是整个栈共享的前提：

• #![no_std]：无堆、无 Vec、无 String。需要缓冲就用定长数组。这不是洁癖—— WS63 是资源受限的裸机环境，引入分配器会带来确定性和体积代价，而嵌入式代码几乎总能用 定长缓冲解决。
• 目标是 riscv32imfc-unknown-none-elf（硬浮点 ilp32f，无原子），由自定义 hisi-riscv 工具链提供。为什么是它而不是软浮点、为什么是自定义工具链而不是 -Z build-std——这件事本身就是一篇 硬浮点工具链。
• 无原子怎么办：这颗核没有 A 扩展，lr/sc/amo 会陷入。所以 RMW 原子全部走 portable-atomic 的 critical-section polyfill，hisi-riscv-rt 提供 critical-section-single-hart 实现。这一条让 async/embassy 能在这颗核上跑—— 详见 async 与 embassy。
• 多芯片：同一套 HAL 用 chip-ws63 / chip-bs21 feature 二选一区分， 条件编译外设模块。WS63 含 Wi-Fi 相关，BS2X 含 GADC/KEYSCAN/QDEC/RTC/TRNG 等 M1 外设。

这套架构想达到的最终目的

把上面几条放在一起看，会发现它们都服务于同一个目标：让“写应用“这一层完全安全、完全 no_std、完全不碰 unsafe，同时不牺牲对硬件的精确控制。精确控制被压进 PAC（机械生成、 对着 SVD）和 HAL 的 unsafe 短句；安全被生命周期和 sealed trait 守住；启动和链接这些 最底层、最容易出错的事被隔离进 hisi-riscv-rt。

而这套栈服务的北极星是连接性（WS63 的 Wi-Fi / BLE / SLE）。分层之所以值得， 是因为连接性那一层（RF blob 的 porting）最复杂、最容易把下面搅乱——清晰的分层正是 为了在引入那层巨大复杂度时，下面的 PAC/HAL/rt 不被污染。连接性的可行性与现状见 ws63-RF 深入文档 与 HIL 框架。

类型化配置：「能编译就能在硅片上跑」

这是本项目 HAL API 的头号约定:配置面被设计成 ——你能写出来的值,就是能在真硅片上跑起来的值。不存在「编译通过、却被静默 clamp / 截断 / 没接时钟」的参数。

本篇讲为什么这样设计、它怎么和 embedded-hal 分层、以及落地时该怎么判断。配方见 如何新增一个外设驱动;仓库内的可调用清单见 .claude/skills/typed-config/(含缺陷分类法 + 候选扫描器)。

问题:能写出但跑不了

很多嵌入式 HAL 的配置接口会接受一个结构上合法、却在硅片上跑不通的值,而且不报错:

• 算出来的分频/周期/计数超过寄存器位宽 → 被静默掩码截断,频率/波特悄悄错;
• 角色与分频的组合合法但不产生时钟(比如 I2S Master 配了零分频);
• 需要一个没被强制的前提(时钟门没开、板上没焊晶振、模拟 AFE 没上电);
• 越界被悄悄 .clamp() / saturating_ / if x == 0 { 1 } 掉,而不是报错。

这类 bug 的代价极高:编译、烧录、上板,全过,但行为是错的,且无任何信号 —— 往往要拿逻辑分析仪或半天 debug 才发现。本约定的目标就是把这类错误从「上板才暴露」提前到「根本写不出来」。

两层:config 面收紧,操作面保持 embedded-hal

关键边界:出问题的是配置面,而 embedded-hal 的 trait 根本不约束配置面。 所以两层互不打架。

为什么操作面只能 Result:embedded-hal 1.0 的 trait 方法必须 fallible(见下「参考」),set_duty_cycle(u16) 这种签名你改不了 —— 越界就返回 Err,这是它的惯例,不是妥协。而配置/构造方法是 HAL 自有的 inherent 方法,不归 trait 管,可以放手编译期化。

缺陷分类法(给每个配置字段定级)

• A —— 寄存器位宽溢出。 算出的值比硬件字段宽,被静默掩码/截断(& 0xFFFF、as u16)。
• B —— 合法但死的组合。 结构合法却不产生可用时钟/输出(如零分频的 I2S Master)。
• C —— 未强制的前提。 必须先开的时钟门、必须焊的晶振 / 上电的模拟 AFE、XIP-unsafe 上下文。
• D —— 静默 clamp/wrap。 越界被悄悄夹/饱和/if x==0 {1},而不是报错。

决策树:每类字段怎么收

• 频率 / 波特 / 周期 / 超时(从运行时值算出来的)→ 校验 newtype + const fn try_from_hz(u32) -> Option<Self> / from_count / try_new,越出可达寄存器范围就返回 None。拒绝,不要 clamp。(治 A、D)
• 角色相关配置(合法字段取决于模式)→ type-state:需要额外参数的那个状态在构造函数里强制要求它,非法组合在类型上不可表达。(治 B)
• 小的有限选择 → enum(本就装不下非法值;除非现在是裸整数)。
• 时钟门没开 → 驱动在 configure/new 里自起自己的时钟门(照搬 vendor *_porting 的 CKEN + DIV_CTL 分频 + LOAD_DIV 序列)。(治 C)
• 板级/模拟前提(RTC 32 kHz 晶振、ADC AFE/LDO 上电)类型治不了 → doc + 守护:命名明确 / cfg / feature 门控的构造,有界轮询(绝不用会拖死总线的无界轮询),加一行 # 硬件要求 文档。(治 C)
• 本就是全宽 32 位寄存器 / 本就是 enum → 不动。 不要无中生有造约束,只收真缺陷。

类型编码的是实测硅片现实,不是手册

最有教育意义的一例:pwm::PwmPeriod 是 u16,因为 WS63 的 pwm_freq_h 高 16 位在硅片上根本不存值(实测:写 0x0001 读回 0,即便整条时钟树都拉起来),而 vendor regs_def 明明声明这个字段是 32 位。类型编码实测行为,而不是数据手册。 如果某字段的真实范围拿不准,先上板量,再定类型边界 —— 别只信 PAC/SDK 的位宽。

落地流程(docs-first)

1. 先改文档 —— 本约定要求 docs-first:先更新该驱动的组件文档 + 本页 + ROADMAP,再写代码。
2. 扫候选:bash .claude/skills/typed-config/scan.sh crates/hisi-riscv-hal/src/<driver>.rs。
3. 追到寄存器:从 PAC 拿字段真实位宽,从 vendor SDK 拿有效范围 + 时钟前提,标 file:line。
4. 定级 + 选方案(决策树),只动配置层,embedded-hal trait impl 的签名不碰。参考 pwm.rs。
5. 更新测试:host 单测/property(newtype 的接受/拒绝边界)+ tests/hil.rs。
6. 上板验证(硅片佐证):寄存器/轮询级事实可上板确认;示波器级行为(真实波形)和板级前提(RTC 晶振)不能 —— 如实说明。

参考实现与依据

• 参考实现:crates/hisi-riscv-hal/src/pwm.rs —— PwmPeriod(u16,from_count/try_from_hz)、Duty(0..=100)、configure 自起时钟树、保留 SetDutyCycle。
• 仓库约定:CLAUDE.md 的「Typed config — if it compiles, it runs on silicon」一节 + .claude/skills/typed-config/ skill。
• 业界依据:
  • esp-hal API 准则:「prefer compile-time checks over runtime checks; prefer a fallible API over panics」—— 本 HAL 本就仿照 esp-hal。
  • Parse, don’t validate(Alexis King):只给可失败构造,值要么解析成功要么不存在。
  • Typestate pattern(The Embedded Rust Book):把运行时状态编码进编译期类型,零运行时开销。

启动流程：mask ROM → flashboot → app

这一篇回答一个看似简单、却让很多人第一次烧 WS63 时困惑的问题：为什么我 cargo build 出来的那个 ELF，直接烧上去不会跑？ 答案藏在一整条引导链里——从上电的第一条指令，到你的 main() 拿到控制权，中间隔着好几道关卡，每一道都对镜像格式有要求。理解这条链， 你就理解了为什么必须“打包 + 烧到特定地址“（操作步骤见 打包成可启动镜像 与 用 probe-rs 烧录， 确切地址见 内存映射）。

整条链：四级接力

WS63 上电后，控制权像接力棒一样在四个阶段间传递，每一级都把芯片往“能跑应用“的状态推一步：

上电
  │
  ▼
① mask ROM   @ 0x100000   复位向量 `j 0x100024`，固化在硅片里、不可改
  │           最底层 bring-up，随后把控制交给 flash 里的 loaderboot
  ▼
② loaderboot              一级引导：最早的时钟/外设 bring-up、烧录通道（YMODEM）
  │
  ▼
③ flashboot               二级引导：时钟切到 PLL、SFC 初始化、（可选）校验镜像，
  │           然后【无条件】跳到 app 分区 + 0x300
  ▼
④ app  @ 0x230300         你的 Rust 程序，从 0x300 头部之后的入口开始
              hisi-riscv-rt 的启动代码接管 → 最终调用 main()

每一级“为什么存在“都不一样：mask ROM 解决“硅片上电后第一条指令从哪来“， loaderboot/flashboot 解决“flash 里的东西怎么被搬起来跑、镜像合不合法“， 而 app 这一级才是你的代码。前三级里有两级（mask ROM、app ROM）是厂商固化的 ROM—— 它们的真实内容是从硅片上读出来的 dump，专有、仅本地可见，不会进仓库； 我们对它们的理解来自对照 fbb_ws63 C SDK 和实测行为。

① mask ROM：硅片里固化的第一步

复位时 PC 落在 mask ROM 的 0x100000，那里是一条 j 0x100024——跳过最前面几个字的头部， 进到真正的 bring-up 代码。这段代码无法修改（它就是硅片的一部分），职责是把芯片从“刚上电、 什么都没配“的状态拉到“能从 flash 取下一级“的状态。除了 0x100000 的 mask ROM， 还有一块 app ROM @ 0x109000——厂商固化的运行时支持例程（C SDK 的某些底层函数会调到它）。 对纯 Rust 的裸机应用来说，app ROM 基本不在路径上；但理解连接性（RF blob）时它很关键， 因为厂商协议栈会跳进这些 ROM 地址——这正是 blob 难以脱离真硅片的原因之一 （见 ws63-RF 深入文档）。

②③ loaderboot 与 flashboot：把镜像搬起来、跳进去

loaderboot 是一级引导，flashboot 是二级引导。对“跑一个 Rust 应用“这件事， 最关键的是 flashboot 的最后一跳：

flashboot 无条件跳到 app 分区起址 + 0x300。WS63 的 app 分区在 flash 的 0x230000，所以入口固定是 0x230300。

注意“无条件“三个字——flashboot 不去解析 ELF 头、不去找 entry point、不做任何重定位。 它只是把 PC 设到 0x230300 然后一跳了事。这就直接解释了下一节那个核心问题。

仓库里有一个实验性、学习用途的 Rust 版 flashboot（chips/ws63/flashboot）， 它对照原厂 flashboot_ws63 重写了这条流程：汇编启动（PMP 清零、mtvec、开 FPU、清 BSS）、 时钟从 TCXO 切到 PLL、SFC 四线读初始化、镜像头边界校验 + 软件 SHA-256 完整性校验， 最后 transmute 到 addr + 0x300 跳进去。它有意不依赖 PAC/HAL（裸 MMIO）， 以免链接进第二份 PAC。生产上不该用它——生产应复用原厂 flashboot， 它有真实签名验签、A/B 槽、FOTA、解压。详见 flashboot 深入文档。

为什么 0x300 头部必须存在——以及为什么裸 ELF 不会启动

把上面两件事拼起来，答案就清楚了：

• flashboot 无条件跳到 app 分区 + 0x300；
• 它不解析 ELF。

所以 app 分区开头那 0x300（768）字节必须是一段 HiSilicon 镜像头——一个 0x100 字节的 KeyArea（签名/密钥区）加一个 0x200 字节的 CodeInfo（含 body 长度、body 的 SHA-256 等）。 flashboot 跳到 +0x300 时，正好落在这段头部之后、也就是你程序真正的第一条指令上。

如果你把 cargo build 出来的裸 ELF 直接写到 0x230000，会发生什么？ flashboot 照样无条件跳到 0x230300——但那里现在是 ELF 文件里偏移 0x300 处的某段数据 或节内容，不是入口指令。PC 落在一堆并非代码的字节上（或者 SRAM 残留），于是跑飞。 你的程序明明被烧进去了，却一条指令都没执行到。

这就是为什么必须用 hisi-fwpkg 打包：它把 ELF/bin 转成 “0x300 头部 + body“的镜像，把入口对齐到 +0x300，并把 body 的 SHA-256 填进 CodeInfo。 头部各字段的精确布局见 应用镜像格式与签名。

XIP：app 直接在 flash 里执行

还有一个值得理解的点：WS63 的应用是 XIP（execute in place） 的——代码段不被搬进 RAM， 而是直接从 flash 的 XIP 窗口（映射在 0x200000 区域）取指执行。app 分区 0x230000 就落在这个窗口里。这意味着 flashboot 跳进 0x230300 后，CPU 是直接对着 flash 取指的， SFC（flash 控制器）必须已经被初始化成可读状态——这正是 flashboot 在跳转前要做 SFC 四线读 初始化的原因。

④ app：hisi-riscv-rt 接管

控制权落到 0x230300 你的程序入口后，并不是直接进 main()，而是先经过 hisi-riscv-rt 的启动序列。这段代码做的是每个裸机 Rust 程序 都需要、但又必须按 WS63 实际情况定制的事，大致顺序：

1. PMP 清零——把物理内存保护配成不挡路（否则后续访问可能陷入）；
2. 设置 mtvec——安装中断/异常向量基址（向量化模式）；
3. 初始化 gp / sp——gp 用于 linker relaxation 的全局指针寻址，sp 指向栈顶；
4. 栈染色（stack paint）——往栈区填已知图案，便于事后测高水位 / 检测溢出；
5. runtime_init——把 .data 从 flash 拷到 RAM、清 .bss，让静态变量就位；
6. 调用 main()——到这里你的代码才真正开始跑。

这套序列为什么不能省、为什么 gp/sp/PMP 这些必须由 rt 而不是应用来做， 属于 rt 这一层的职责；它的链接脚本（memory.x / layout.ld）如何把段摆到正确地址、 又如何把脚本传播给下游的 bin，见 hisi-riscv-rt 深入文档。

与 QEMU 的差别：为什么 QEMU 里裸 ELF 反而能跑

一个会让人困惑的对照：在 QEMU 里，你直接 -kernel blinky.elf 就能跑，根本不需要 0x300 头部、不需要 flashboot。这不矛盾——QEMU 用 load_elf() 解析 ELF 并按 ELF 的物理地址落段，再把复位向量设成 ELF 的 entry。也就是说 QEMU 替你做了“理解 ELF、跳到正确入口“这件 flashboot 不做的事。

所以记住这条分界：QEMU 跑的是裸 ELF（无头部、无 flashboot、时钟取标称值）；真硅片跑的是 带 0x300 头部、烧到 app 分区、经 flashboot 跳入的镜像。 这正是 QEMU 能验证逻辑、却验证不了 “镜像格式 / 引导链 / 真实时钟“的根本原因——详见 QEMU 模型 和 HIL 框架。

硬浮点工具链

这一篇解释一个看起来“过度工程“的决定：为什么 WS63 要用一条自定义的 rustc——把 riscv32imfc-unknown-none-elf 烤进 builtin 的 hisi-riscv 工具链——而不是用现成的 stable rustc 加 -Z build-std？ 这背后串着三个互相牵连的约束：硬浮点 ABI、没有原子扩展、 以及 code model。逐项的安装与版本细节见 工具链与编译目标 和 安装 hisi-riscv 工具链；这里只讲为什么是这条路。

这颗核到底是什么

WS63 的核是 RV32IMFC：

• I（基础整数）、M（乘除）、C（压缩指令）——常规；
• F（单精度浮点）——有硬件浮点单元；
• 没有 A（原子扩展）——lr.w/sc.w/amo* 这些指令会陷入非法指令。

这两个非常规点（有 F、没有 A）合起来，把“选哪个编译目标“这件事从“随手挑个标准 target“ 变成了一道需要权衡的题。

为什么硬浮点（ilp32f ABI）

既然硅片有 FPU，最自然的选择就是让它用起来——也就是 ilp32f ABI：浮点参数走浮点 寄存器、浮点运算发真正的 f* 指令，而不是软件模拟。软浮点（ilp32）当然也能跑（编译器把 f32 运算翻成调用 libgcc/compiler-builtins 里的软件例程），但那是在一颗有 FPU 的核上 白白浪费硬件、还更慢更大。

但硬浮点 ABI 的真正分量不只在性能。ilp32f 是一条 ABI 边界——用 ilp32f 编的代码和用 ilp32 编的代码不能直接链接（浮点参数的传递约定不同）。而 WS63 的北极星是连接性， 连接性意味着最终要和厂商的闭源 blob 链接，那些 blob 是用厂商 gcc 按 ilp32f 编的。 所以选 ilp32f 不仅是“用上 FPU“，更是“为了将来能和 vendor blob 在同一个 ABI 上对接“ ——这是阶段 3（blob 链接）的前置条件。这一层动机，使硬浮点从“优化“升级成“必需“。

为什么没有原子是个真问题

RV32IMFC 缺 A 扩展，意味着任何会发 lr/sc/amo 的代码在硅片上都会陷入。 而 Rust 的 core::sync::atomic 默认假设有原子指令。历史上一度用过 riscv32imafc （带 A）作为权宜——但那会让编译器发原子指令、在真硅片上触发非法指令陷阱，所以被弃用。

正解是两段配合：

1. 目标本身声明为无原子——用 forced-atomics + no-CAS 配置，让原子 load/store 降级成 普通 ld/st（单核下这是安全的），而需要 RMW（compare-and-swap 之类）的操作不发 原子指令；
2. RMW 走 polyfill——portable-atomic（开 critical-section feature）把 CAS 实现成“关中断 → 读改写 → 开中断“的临界区，hisi-riscv-rt 提供 critical-section-single-hart 这个单核实现。

这套机制正是 async/embassy 能在这颗核上跑的地基（见 async 与 embassy）。 它和“用不用自定义工具链“正交——但目标必须被正确声明为无原子，否则 polyfill 也救不了， 编译器照样会在别处发出原子指令。

核心抉择：自定义 builtin target，还是 -Z build-std？

到这里问题收敛成：我们需要一个标准 rustc 里没有的目标（riscv32imfc，硬浮点、无原子）。 Rust 提供两条路拿到一个非标准 target，二者是真正的取舍：

路线 A：-Z build-std（用现成 stable rustc + nightly 特性）

写一个 *.json 自定义 target spec，然后让 cargo 用 -Z build-std 从源码现编 core/alloc。

• 好处：不用自己造工具链，跟着官方 rustc 走。
• 代价：-Z build-std 是 nightly-only 的不稳定特性。整条工具链就被钉死在 nightly 上——nightly 每天变、偶尔回归，CI 的可重现性变差，用户也得装 nightly + rust-src。 对一个要给别人用、要长期维护的嵌入式 SDK，“必须 nightly“是个不小的负担。

路线 B：自定义 rustc，把 target 烤成 builtin（现在走的路）

构建一条 hisi-riscv 工具链：一个 stable rustc，但在编译它的时候就把 riscv32imfc-unknown-none-elf 这个 target spec 编进 rustc 内部成为 builtin， 并预编译好 core/alloc 一起分发。

• 好处：用户拿到的是一条稳定、自带预编译 core/alloc 的工具链，.cargo/config.toml 里设好默认 target 就行，完全不需要 -Z build-std、不需要 nightly。 cargo build 直接出 RV32IMFC ilp32f 固件，可重现、好分发。
• 代价：得自己维护这条工具链——跟 rustc 版本、出多平台预编译包、走自己的 CI。 这是实打实的工程量，也是这套生态接受的那笔账。

权衡的结论很清楚：用户体验和可重现性 > 维护方自己省事。对一个嵌入式 SDK，“装好工具链 就能稳定 cargo build“远比“维护方不用管工具链、但每个用户都得忍 nightly“更值。 所以选了 B。工具链通过 rust-toolchain.toml pin 住 channel = "hisi-riscv"， 用 rustup toolchain link 接进 rustup。

code model：medlow 还是 medany

还有一个容易被忽略、但在裸机上会真出问题的旋钮：code model，它决定编译器怎么寻址 全局符号。

• medlow：假设代码和数据都落在地址空间低 2 GiB 以内，用更短的寻址序列。
• medany：用 PC 相对寻址，可以放在地址空间任意位置，序列略长。

WS63 的地址布局把外设、flash、SRAM 散布在很高的地址（比如外设在 0x4400_0000 一带、 SRAM 更高），全局符号未必落在低 2 GiB。所以这条工具链用 medany——这样不管链接脚本把 段摆到哪个高地址，PC 相对寻址都能正确指到。如果误用 medlow，链接期或运行期会因为 “地址放不进 medlow 的寻址范围“而出错。这件事和硬浮点、无原子一样，是“WS63 的地址空间 不像教科书 RISC-V“逼出来的细节。

一段不算短的历史

这条路不是一步到位的：

• 2026-05-31，阶段 0：先用 stable rustc 里已有的 builtin riscv32imc（软浮点、 stable、免 build-std）做过渡——目的是先让整条构建/链接跑通，把“无原子 + critical-section“ 这套机制验证出来。
• 随后切到硬浮点工具链：为了和 vendor blob 的 ilp32f ABI 对齐（阶段 3 的前置）， 把目标换成 riscv32imfc，并为此造了 hisi-riscv 工具链。

理解这段历史有助于读懂仓库里偶尔还能见到 riscv32imc 字样的地方——那是过渡期的遗存， 现在的默认与正解是 riscv32imfc + hisi-riscv 工具链。

这件事对其他部分的影响

值得强调的是：异步/embassy 这块完全不在乎工具链是否上游。异步只依赖 portable-atomic + critical-section，与“target 是 builtin 还是 build-std“正交。 真正被自定义工具链“绑住“的是上游化——只要还依赖自定义 rustc，hisi-riscv-hal 就难以 进 embassy 那种“基于标准 stable target 构建“的 in-tree CI。所以“摆脱自定义工具链“ （短期改用标准 target + build-std，长期推 target 进 rustc 主线）被列为一条独立的上游化 工作线，详见 async 与 embassy 深入文档 里的上游化讨论。

async 与 embassy

这一篇是异步故事的概念总览——它讲三种用 HAL 的方式（纯阻塞、async feature、 embassy feature）各自是什么、为什么并存、以及一个反直觉的事实：这一切跑在一颗连原子 扩展都没有的核上。 想看代码在哪个文件、每个 trait 怎么实现、怎么上游化，去 async-embassy 深入文档；这里建立的是全局直觉。

同一套 HAL，三种用法

hisi-riscv-hal 默认是一套阻塞驱动（符合 embedded-hal 1.0）。在它之上， 两个 feature 叠出了异步能力，于是同一套驱动有三档用法：

1. 不开任何 feature——纯阻塞。uart.write() 就在那儿自旋等 FIFO 有位。 简单、确定、没有执行器、没有 waker。绝大多数简单固件用这档就够。
2. 开 async feature——中断 + waker 驱动的 .await。多了 embedded-hal-async / embedded-io-async 的实现（DelayNs、digital::Wait、 SpiBus、I2c、UART 的 Read/Write），外加一个极小的 block_on 执行器和一个 IrqSignal 桥。让你“不上 embassy 也能 .await“。
3. 再开 embassy feature——完整的 embassy 时间生态。多了一个 embassy-time 的 Driver，于是 embassy-executor（platform-riscv32）能跑，Timer::after / Instant / Ticker 都可用。

这三档不是三套代码，而是同一套阻塞驱动上逐层叠加。这个分层本身是个设计取舍： 不想要异步复杂度的人完全感知不到它的存在，想要的人按需开 feature。

async feature：两块地基

block_on + IrqSignal

async 这一档的核心是两个极小的零件：

• block_on(fut)——一个最朴素的 future 执行器：poll，遇到 Pending 就 wfi 休眠，硬件中断把核唤醒后再 poll。没有堆、没有全局执行器、没有任务队列。它存在的意义 正是“轻“——给只想偶尔 .await 一下、不愿背上 embassy 全套的场景。
• IrqSignal——一座“ISR → future“的桥：一个 AtomicBool（fired 标志）加一个停在 critical_section::Mutex 里的 Waker。中断里调 signal()，future poll 时检查 fired、登记 waker。这是把“硬件中断这件异步的事“接到 Rust async 模型里的接缝。

一个关键克制：不抢中断向量

这套异步驱动有一条很重要的设计纪律——它不自动安装 ISR、不抢占中断向量。每个驱动只 导出一个 on_interrupt 钩子（timer::on_interrupt、gpio::on_interrupt、 uart::on_interrupt……），由应用自己的 trap 处理函数按 mcause 把中断路由过去。

为什么这么设计？因为 Rust 的 cargo 工作区会把 feature 并集——只要工作区里有一个 crate 开了 async，整个工作区都可能被打开。如果异步层一旦被开启就默认安装 ISR，那它会悄悄 改变那些根本没打算用异步的固件的中断行为。“只导出钩子、由应用显式路由“保证了： 开不开 async feature，对非异步固件的行为零影响。这是一条“不给用户埋雷“的边界。

为什么能跑在没有原子的核上

这是最反直觉的一点。WS63 是 riscv32imfc——没有 A 扩展，lr.w/sc.w 会陷入 （详见 硬浮点工具链）。而异步执行器、waker 这些东西通常被认为 “当然要原子操作”。它怎么还能跑？

三件事让它成立：

1. HAL 一直走 portable-atomic + critical-section。需要 CAS 的地方由 portable-atomic 用临界区 polyfill 实现，hisi-riscv-rt 提供单核的 critical-section-single-hart。
2. embassy-executor 本身就支持无 CAS 目标。它内部按编译期 cfg 在 core::sync::atomic 和 portable_atomic 之间切换——这是它早就为 thumbv6m （Cortex-M0，同样无 CAS）准备好的能力。riscv32 平台模块里的 SIGNAL_WORK 只用 load/store（这颗核支持），不需要 CAS。所以无需改 embassy 一行。
3. 一个真实踩过的坑值得记一笔：target/ 里陈旧的 host proc-macro 工件会让 embassy 宏构建莫名失败——cargo clean 后全量通过。这不是逻辑问题，是构建缓存问题。

也就是说，“无原子“在这里没有变成异步的拦路虎——它早被 portable-atomic + critical-section 这层垫片吸收掉了，而 embassy 恰好已经为这种核留好了路。

embassy feature：让 WS63 成为时间提供者

embassy feature 做的事可以一句话概括：让 WS63 成为 embassy-time 的时间源。 具体是实现一个 embassy-time Driver：

• now() 读 TCXO 的 64 位自由计数器（24 MHz），缩放到 embassy-time 的 1 MHz tick。单调、跟随真实（QEMU 上是虚拟）时间流逝。
• schedule_wake(at, waker) 把 waker 入队，并用一个 TIMER 通道编程一次性闹钟。
• 闹钟 IRQ 触发时排空到期 waker、重新武装下一个截止时间。

这里有个和 HIL 框架 直接相关的细节：时间的真值来自 TCXO（24 MHz）， 不是 PLL（240 MHz）。如果时间源算错了时钟基，所有 Timer::after 都会偏 10×—— 这正是 QEMU 验证不了、必须上板验的那类时钟假设。

这一档该用哪个

把三档放在一起，选择其实很自然：

• 简单顺序逻辑、不在乎并发 → 纯阻塞。
• 想 .await 个别 IO、不想背 embassy → async + block_on。
• 要多任务、要 Timer::after、要 embassy 生态 → embassy。

覆盖范围、每个 trait 落在哪个文件、以及“为什么走 esp-hal 那种 out-of-tree 上游模型而不是 塞进 embassy monorepo“这些更深的讨论，都在 async-embassy 深入文档 里。那篇是权威；本篇负责让你先有 全局图景。

安全启动与签名

这一篇解释一个让很多人第一次成功烧片时困惑的事实：为什么一个签名字段全是零的“假“镜像， 居然能在真硅片上启动？ 答案是——开发片的 secure boot 是关掉的。理解这一点， 既能让你明白当前开发流为什么这么顺，也能让你清楚这条流绝不是生产流、以及生产要补什么。 镜像头里签名/哈希字段的精确布局见 应用镜像格式与签名； 本篇讲“为什么“。

secure boot 想解决的问题

安全启动要回答一个问题：flashboot 凭什么相信它即将跳进去的那段 app 是可信的、 没被篡改的？ 在一个开了 secure boot 的设备上，flashboot 在跳转前会做两件事：

1. 真实性验签——用固化在 efuse 里的根密钥，对镜像头里的 ECC（bp256）/ SM2 数字签名做验证。只有用对应私钥签过的镜像才通过。攻击者就算能写 flash， 也伪造不出一个能通过验签的签名（他没有私钥）。
2. 完整性校验——对 app body 算哈希，和签过名的头里的哈希比对，确保 body 没被改。

关键在第 1 点：真实性靠的是“攻击者拿不到私钥“，这是密码学保证。光有完整性（哈希） 是不够的——因为哈希就在镜像头里，能写 flash 的人改完 body 重算哈希写回头部即可绕过。 没有验签的“安全启动“根本不安全。

开发片为什么把它关掉

WS63 用一个 efuse 位 SEC_VERIFY_ENABLE 控制是否启用安全启动。 在开发片上这个 efuse 位是 0，意味着：

flashboot 跳过 ECC/SM2 签名验签，但仍然校验 body 的 SHA-256 哈希，校验通过才跳进 app。

于是引导链对镜像头的签名字段不做检查——但哈希字段照样比对。这就是为什么——

• 签名区全零的镜像能启动，但 body 哈希必须是真的：打包时签名区填的是全零的占位符 （dummy zero signature），flashboot 既然不验签，全零的签名照样放行；但镜像头里的 body SHA-256 哈希必须算对——secure-off 只跳过 ECC 签名，不跳过 hash，哈希对不上同样拒绝启动。 所以根本不存在某个“假签名“能让任意 body 启动；需要的是 0x300 头 + 真实 body SHA-256。 镜像头的结构当然也要正确（0x300 字节、KeyArea + CodeInfo、body 的 SHA-256 字段位置对——见 启动流程），只是签名的内容无所谓。
• 整条开发流因此非常顺：WS63 走 route 2——靠 hisi-riscv-rt 的 boot-header feature 在 link 时把 0x300 头烤进 ELF，再用 hisi-fwpkg patch-hash <elf> 补上真实的 body SHA-256 （这一步不可省：secure-off 仍校验 hash，只跳过 ECC 签名），然后直接 probe-rs download <elf> / probe-rs run <elf> → reset，就启动了。没有中间 .img、 也没有 hisi-fwpkg image 这一步。不需要任何私钥、不需要厂商签名工具。 （BS21/BS2X 暂无 link-time 头，仍走 route 1：hisi-fwpkg image -o app.img <elf> 后烧 .img。）

这是一个有意的、便利的开发态选择：开发片关掉验签，让 Rust 固件能自由迭代烧录， 不被“每次都得找厂商签名“卡住。

efuse 是一次性的——这件事的份量

要理解为什么“开发片关、量产片开“是条单向门，得知道 efuse 是一次性可编程（OTP）—— 熔丝只能从 0 烧成 1，烧了不可逆。所以：

• 开发片出厂时 SEC_VERIFY_ENABLE == 0，安全启动关；
• 一旦在量产环节把这个位烧成 1，这颗片子就永久进入“必须验签才启动“的状态， 回不去了。从那以后，只有用对应私钥签过的镜像才能在它上面跑。

这也是为什么仓库里那个实验性 Rust flashboot 只做完整性校验、明确标注“非真实性验签“ （见 flashboot 深入文档）：它对着同一份未签名的头里的哈希 比对——这在关掉 secure boot 的开发片上够用，但绝不是 secure boot，文档里如实写明了 这一点，不假装安全。

真正签名需要什么

如果要把固件跑在一颗开了 secure boot 的量产片上，dummy 全零签名就过不了了，需要：

• 厂商闭源的 sign_tool——用真正的私钥对镜像生成 ECC-bp256 / SM2 签名，填进 KeyArea。 这个工具是厂商闭源的，不在本仓库、也不可能在本仓库重写（重写一个签名工具没有意义—— 没有对应的、烧进 efuse 的根密钥，签出来的东西在那颗片子上也过不了）。
• 因此生产推荐复用 fbb_ws63 原厂 flashboot 的完整签名/打包/烧录流程——它有真实验签、 A/B 槽、FOTA、解压、flash 在线加密。本仓库的 Rust 应用在生产里应作为被原厂 flashboot 加载的 app 镜像，按原厂流程签名后烧到 app 分区。

安全含义：别把开发流当生产流

把上面拼起来，要诚实说清楚的边界是：

• 当前这套 Rust 烧录流是 DEV 流——它工作，是因为开发片关掉了验签。它不提供任何 真实性保证：能写到这片 flash 的人就能换掉你的固件。
• 在开发/评估阶段这完全没问题——你要的是迭代速度，不是抗篡改。
• 但不要把“全零签名也能启动“误读成“WS63 的安全启动是摆设“。恰恰相反： 量产片烧了 SEC_VERIFY_ENABLE 之后，验签是真的、靠 efuse 根密钥 + 私钥签名， 全零镜像会被拒绝。是开发片主动关掉了它，不是它不存在。

一句话：当前的便利来自一个被有意关掉的安全特性；上生产就得把它打开，并接入厂商签名链。 两者不能混为一谈。镜像头里每个字段（结构版本、签名长度、code_area_len、 code_area_hash……）的确切位置见 应用镜像格式与签名。

QEMU 模型

这一篇讲 hisi-riscv-qemu（WS63/BS2X 的 QEMU 仿真）为什么存在、它的能力边界在哪。一句话先说结论：它让你在没有真硅片、没有 RF 的情况下把绝大多数开发——内存布局、启动、外设逻辑、中断投递——都验证掉， 但它模拟不了的那部分恰恰是 HIL 必须上板验的部分。把这两件事的边界 看清楚，就理解了整套验证策略。

为什么要造一个 QEMU 板卡

最朴素的理由：真硅片稀缺、RF 难搞、迭代慢。如果每改一行 HAL 都得打包、烧片、接串口看 输出，开发会被硬件可用性卡死。QEMU 给的是一个软件在环的快速反馈环——cargo build 完 直接 -kernel firmware.elf 就能看它跑、能 GDB 调、能跑确定性回归。

为什么不用现成的 -M virt？因为固件是按 WS63 的真实地址链接的——外设在 0x4400_xxxx、 flash 在 0x200000、SRAM 在特定高地址。在 virt 上，固件第一次访问 WS63 外设就会 fault。所以必须有一个地址布局和 WS63 一致的板卡。

为什么不做“树外插件“？因为 QEMU 没有稳定的树外板卡 ABI。自定义 SoC 的标准做法 （Espressif 的 esp-qemu 也是如此）是 fork 一个固定版本的 QEMU、加一个 in-tree 板卡文件。 hisi-riscv-qemu 正是这么做的：加 hw/riscv/ws63.c，只构建 riscv32-softmmu。

它建模了什么

这个模型的覆盖面相当完整，远不止“能跑起来“：

• CPU：命名核 -cpu ws63 = RV32IMFC（I/M/F/C + Zicsr/Zcf，关 A/D、无 MMU）， 和真硅片的 ISA 一致——包括“没有原子“这一点。
• xlinx 自定义 ISA：HiSilicon riscv31 的一批私有指令。这是为了能跑厂商 gcc 编的 C SDK 固件——有了它，Rust 固件（标准 RV32IMFC）和厂商 C SDK 固件可以对照交叉验证 内存映射、启动、外设时序。
• 全部 35 个 SVD 外设：不是“catch-all 黑洞“，而是逐个建模。其中很多是行为完整的—— DMA 真的搬内存、Timer/RTC/WDT 真的计时和触发中断、I2C/SPI/I2S 真的回环 FIFO、 LSADC 真的出采样、EFUSE 真的走 OTP 按位或、GPIO 是真实信号网（bank 内回环 + 跨 bank 板级连线 + 可外部驱动）。少数配置类寄存器（晶振/RF/PHY 相关）是读回影子。
• 时钟树：时钟门控生效（清门会冻结定时器、置位恢复）、源路由（TCXO/PLL 选择）建模为状态。
• 中断：两类都端到端投递——IRQ 26–31 走标准 mie，IRQ ≥32 走 HiSilicon 自定义 LOCIxx CSR（经 target/riscv 补丁实现），并强制 LOCIPRI 优先级 + PRITHD 阈值。
• -icount 确定性指令计时：开了之后虚拟时间绑定指令数，同一固件每次运行结果完全 一致（实测 1e6 循环三次都是同一个 tick 数）。这让 CI 回归可重现。

这是一个真值驱动的模型：外设基址/寄存器对着 WS63.svd，内存布局对着 hisi-riscv-rt 的 memory.x/layout.ld，UART 行为对着 HAL 的 uart.rs + SDK 头文件。 也就是说它和真硅片共享同一批真值来源——这是它能当“软件在环替身“的前提。

它模拟不了什么

诚实地划出边界，比夸大覆盖面重要得多。QEMU 本质上模拟不了这几类东西：

• RF / PHY / 模拟量：射频前端、PHY 事件、真实无线收发——这是物理边界，仿真器里没有可 观测行为。（连接性因此走“合成 MAC 在 netif 缝合点“的软件在环底座，而不仿 RF； BS2X 的 BLE/SLE 在 radio-MMIO 层模拟已被论证是死胡同。）
• 真实时钟频率与时序：TCG 不模拟流水线/cache/逐指令周期。-icount 给的是 IPC=1 的 确定性近似，不是真实微架构周期精确。更要命的是——QEMU 的 chardev 不限速， 所以 UART 哪怕波特率算错了，它照样把字节原样吐出来，根本不会暴露波特错误。
• 真实 flash 内容：flash XIP 窗口是 RAM 背靠的，默认空白。分区表、NV、出厂标定 （xo_trim 这类逐芯片烧录的键）QEMU 里天然没有——只能用 -device loader 回填一份 构建出来的，而出厂标定值任何构建产物都不含。
• 掩膜 ROM / app ROM 的真实内容：那些是从硅片读出的专有 dump，不在仓库。厂商 blob 里 会跳进这些 ROM 地址，所以连接性的 blob 难以脱离真硅片——这也是 QEMU 的天花板之一。

QEMU 跑 vs 真硅片跑：根本差别

这是最该记住的一张对照表——它直接解释了为什么“QEMU 过了“不等于“硅片能跑“：

换句话说，QEMU 替你做了 flashboot 不做的事（理解 ELF、跳对入口），又省略了 flashboot 做的事（镜像格式、引导链）——所以“裸 ELF 在 QEMU 里能跑、在硅片上不能跑“ 不是矛盾，而是这张表的直接推论（详见 启动流程）。

QEMU↔HIL 的 parity 思路

把上面拼起来，整套验证策略就清楚了：QEMU 负责证明逻辑对——内存布局、启动序列、 外设行为、中断投递、DMA 搬运；HIL 负责证明 QEMU 证明不了的物理现实对——真实时钟、真实波特、 真实外设时序、引导链、RF。 两者验的是不同的东西，不是冗余。

理想形态是 parity：同一个固件（比如 uart_hello），QEMU 里看到什么标记串、硅片上就该 看到同样的标记串。QEMU 先把逻辑钉死，硅片再把物理现实钉死，两边比对。一旦硅片上的输出和 QEMU baseline 分歧，那个分歧几乎必然落在 QEMU 模拟不了的那几类——波特、时钟 10× 偏差、 引导挂死、IRQ 投递、外设接线。这正是 HIL 框架 那套 triage 的出发点。 模型的逐外设建模矩阵、xlinx ISA 细节、NV 回填等见 hisi-riscv-qemu 仓库的 docs/design.md。

HIL 测试框架

这一篇讲硬件在环（hardware-in-the-loop, HIL）测试的哲学——为什么我们用 UART 里的一行 字符串来判定一次真机测试通过、QEMU 已经验过的东西为什么还要上板再验一遍、以及一份诚实的 当前 bring-up 状态。操作步骤见 运行 HIL 冒烟测试， 标记串与环境变量见 HIL 标记串与环境变量；本篇讲“为什么这样测“。

HIL 存在的意义：验 QEMU 验不了的那部分

QEMU 已经把逻辑钉死了——内存布局、启动序列、外设行为、中断投递、DMA 搬运 都在软件在环里过了。那为什么还要 HIL？因为 QEMU 本质上模拟不了真实的物理现实： 真实时钟频率、真实波特、真实外设时序、真实引导链、RF。

所以 HIL 的定位很明确：它不是再验一遍逻辑，而是验 QEMU 验不了的物理现实。 一个固件如果在 QEMU 里跑通、却在硅片上出问题，那个问题几乎必然落在“真实时钟/时序/外设/ 接线“这几类——而不是逻辑 bug（逻辑 QEMU 已经替你筛过了）。这个前提决定了 HIL 故障诊断 （triage）的整个思路：先怀疑物理现实，而不是先怀疑代码逻辑。

为什么用 UART 标记串做验证通道

HIL 的验证通道是串口里打印的标记字符串——比如 uart_hello 该打印 Hello from WS63 ...、timer_irq 该周期打印 timer irq #N。为什么选这么“土“的通道， 而不是用调试器读寄存器、或者别的什么？三个理由：

1. QEMU 可证 + 硅片可观测。同一行标记串，QEMU 的 smoke-test 能看到、真硅片接串口也能 看到。这就让 parity 比对成立：QEMU baseline 打印什么、硅片就该打印什么， 两边逐字对照。换个调试器专属的通道，QEMU 那边就对不上了。
2. 它恰好能抓住 QEMU 抓不到的 bug。一行 UART 输出要正确出现，背后牵连真实波特 （UART 时钟分频对不对）、真实定时（timer 时钟基对不对）、引导是否真的跑到了 main—— 这些全是物理现实。QEMU 的 chardev 不限速，所以波特算错它照样原样吐字节、根本不报错； 而真串口接收端波特不匹配就是一屏乱码或者干脆没有。也就是说，UART 这个通道天生能暴露 时钟/波特/定时类 bug，正好补上 QEMU 的盲区。
3. 门槛低、确定。一根串口线、一个标记串比对，不需要逻辑分析仪也能跑出第一轮结论 （需要时再上逻辑分析仪做更细的诊断）。

三段式流程：qemu-smoke → hil-smoke → hil-triage

整套验证是三段接力，逐步逼近真机现实：

• qemu-smoke——在 QEMU 里逐例跑，建立baseline：每个固件该打印什么标记串、按什么 顺序、什么节奏。这是“应该是什么样“的真值。
• hil-smoke——在真硅片上逐例烧录 + 读 UART + 比对标记串，镜像 QEMU 的 smoke-test。 通过则该例的物理现实也对了；不通过则进下一步。
• hil-triage——诊断单个失败步。它的工作假设很关键：板子跑的是 QEMU 已验证的固件， 所以失败通常意味着一个 QEMU 模拟不了的真实时钟/时序/外设/接线现实，而不是逻辑 bug。 triage 的任务是带证据点名最可能的那一类原因，而不是漫无目标地猜。

分歧的几类——先查这些

QEMU↔硅片的分歧高度集中在固定几类，triage 按这个清单逐项对照：

1. UART 波特——乱码 / 没 banner ⇒ UART 时钟分频假设错。WS63 UART 从 160 MHz 基 分频；若按别的时钟算分频，波特就偏。（QEMU chardev 不限速，永远抓不到这类。）
2. 定时器周期偏约 10×——timer_irq 来得太快/太慢 ⇒ 定时器还在按 240 MHz PLL 算、 而真值是 24 MHz TCXO（或反过来）。这是**最典型的“QEMU 过了、硅片不行“**的 bug。
3. 引导挂死 / 全程静默——一点输出都没有 ⇒ 电源/PWR_ON、错的 LOADERBOOT、错的 flash ADDRESS、或启动时读了一个真硅片上永远锁不上的 PLL。
4. IRQ 没投递——gpio_irq 静默 ⇒ LOCI 使能、触发沿、或引脚接线；核对 IRQ 号和 LOCIEN/mie 路径是否和 SDK 一致。
5. 外设接线——spi_loopback 需要 MOSI↔MISO 短接、i2c_scan 需要真实上拉。 这一类“失败“可能是测试台架（rig）的问题，不是固件的问题——triage 必须把 “固件要改“和“台架要修“分开。

诊断时对时序类症状要做算术：从 HAL 的时钟常量算出期望周期/波特，再从实测值反推真实 时钟是多少，用数字说话而不是猜。

当前 bring-up 状态（诚实版，2026-06-14）

要诚实——这是进行中的工作，不是已完成的胜利：

• blinky：已在真硅片上确认。 完整的 Rust → flash → 启动主流程 （cargo build → hisi-fwpkg patch-hash <elf> → probe-rs run <elf>） 于 2026-06-14 在真 WS63 硅片上跑通，blinky 上电启动并翻转 GPIO0。这是第一个、也是目前 唯一一个端到端真机确认的例子。WS63 走 boot-header feature——0x300 头在链接期就烤进 ELF，链接后只需 hisi-fwpkg patch-hash 补上真实 body SHA-256（secure-off 仍校验 hash， 只跳过 ECC 签名），裸 ELF 即可直接 probe-rs download / probe-rs run，没有中间 .img、 也没有 hisi-fwpkg image 步骤。（BS2X 暂无链接期 boot-header，仍走 route 1 的 hisi-fwpkg image -o app.img <elf> → 烧到 app 分区。）
• uart_hello：跑到了 main 并在运行，但 banner 还读不出来。 固件确实启动、确实进了 main、确实在跑——但它的 UART banner 目前在真硅片上还读不到。怀疑是波特/时钟 假设的问题（对照上面的分歧类 1：UART 的 160 MHz 时钟基），正在排查中。 这正是 QEMU 抓不到、必须上板才暴露的那类——也正是为什么我们要 HIL。
• 其余例子（timer_irq / gpio_irq / reset_demo / SPI / I2C / DMA 等）：QEMU 已验证， 真机 bring-up 进行中。 QEMU 端这些的逻辑（中断投递、复位记录、DMA 握手、回环）都验过了； 真机这一侧在等逐例把 LOADERBOOT/串口监控参数按板填实、逐步推进。
• 连接性（阶段 4/5）：WS63 Wi-Fi 的 porting + 链接 + netif→smoltcp 已在 QEMU 软件在环 自测、符号闭合达成；真机连通仍待 HIL。BS2X 的 BLE/SLE 在 radio 层已论证不可行， 走 HCI 边界。

首板的第一目标就是跑通 uart_hello → timer_irq → reset_demo 这几步，确认“本轮的时钟修复 在真硅片上准确“（24 MHz 定时器、160 MHz UART 波特、SPI/I2C、GPIO/复位中断）——这正是 QEMU 数字验证不了、必须上板验的核心。uart_hello 的 banner 问题就是这条路上的当前关卡。

不夸大、不假装：逻辑这一层 QEMU 已经替我们筛得很干净，物理现实这一层才刚踩上第一块硅。 这恰恰是 HIL 这套框架存在的全部理由。

组件深入文档

这一节是 10 篇逐组件深入文档的索引。它们是每个组件的权威实现说明——讲这一个组件 内部到底怎么实现、设计上踩过哪些坑、架构评审发现了什么。和上一层的概念章节分工明确：

• 概念章节（架构 / 启动 / 工具链 / async / 安全启动 / QEMU / HIL）讲 “为什么、各组件怎么串成一个整体”；
• 这里的深入文档（deep dive）讲 “这一个组件内部怎么实现”。

概念章节会链接进这些深入文档；想建立全局图景先读概念章，想查某个组件的实现细节就来这里。

从这里开始

• 总体架构 overview.md——整个栈的全景：依赖链、核心设计模式、构建与目标、 多芯片支持、已知的全局性问题。想先看一篇就看这篇。

核心库栈（依赖链自下而上）

• ws63-svd.md——SVD 真值（CMSIS-SVD XML）+ 生成工具，整条链的最底层真值来源。
• ws63-pac.md——svd2rust 生成的裸寄存器访问层（含 BS2X 的 bs2x-pac）。
• hisi-riscv-hal.md——手写的安全驱动层，多芯片、可选 async/embassy。
• hisi-riscv-rt.md——运行时：启动汇编、中断向量、链接脚本、 critical-section 实现。
• async-embassy.md——HAL 异步层的实现细节：block_on/IrqSignal、 每驱动 on_interrupt 钩子、embassy-time Driver、代码地图与上游化路线 （概念总览见 async 与 embassy）。

应用与芯片支持

• ws63-examples.md——示例集合（blinky/uart/timer/gpio/dma/async/ embassy/连接性等）的组织与验证方式。
• ws63-flashboot.md——实验性 Rust 二级引导的架构与评审 （概念上的引导链见 启动流程）。
• ws63-RF.md——WS63 闭源 Wi-Fi/BT/BLE/SLE blob 与 Rust porting 层。

硬件手册

• ws63-guide.md——WS63 中文硬件手册（Sphinx）的说明（讲芯片，与讲代码的 overview.md 互补）。

ws63-rs 总体架构

这是 ws63-rs 的 Rust 代码架构文档（与硬件手册 ws63-guide 互补：手册讲芯片，本文讲代码）。 完整评审台账见 架构评审 2026-05，整改排期见 ROADMAP。

这是什么

ws63-rs 是面向 HiSilicon WS63 + BS2X（BS21/BS20/BS22）RISC-V SoC 族的 Rust 嵌入式生态。WS63 覆盖 Wi-Fi 6 / BLE / SLE/星闪，BS2X 覆盖 BLE/SLE（M1/M2）。 采用多仓库（git submodule）+ 单一 Cargo workspace 的组织方式。

组件与依赖链

┌─ crates/pac ────────────────────────────────────┐
│ ├─ ws63-pac/ws63-svd (CMSIS-SVD) ──svd2rust──┐ │
│ └─ bs2x-pac/bs2x-svd (CMSIS-SVD) ─────────────┤ │
│                                            ▼ ▼ │
│                    hisi-riscv-hal (多芯片 HAL，chip-ws63/chip-bs21 feature) ◀── embedded-hal 1.0
│                    │  ├─ feature "async"  ◀── embedded-hal-async / embedded-io-async
│                    │  │     asynch::block_on + IrqSignal + 各驱动 on_interrupt(中断→waker)
│                    │  └─ feature "embassy" ◀── embassy-time-driver / -queue-utils
│                    │        embassy::Driver  (now()=TCXO 64位计数器, alarm=TIMER 通道)
│                    ▼
│ examples/ws63/* (blinky/uart_hello/timer_irq/gpio_irq/reset_demo/dma_loopback/
│ examples/bs21/* (blinky/spi_loopback/i2c_scan/gadc_read/hid_demo/pwm_wdt/clock_rng/dma_mem)
│                    │    async_delay/async_bus/embassy_multitask/embassy_async_io/wifi_blob_link/rf_port_demo/semihost…
│                    ▲
│                    └── embassy-executor (platform-riscv32, thread mode)  ← embassy 示例
│ hisi-riscv-rt (启动/中断向量/链接脚本 + critical-section + 工具链原子垫片) ─┘（运行时）
│ chips/ws63/flashboot (实验性二级引导，独立，裸 MMIO)
│ chips/ws63/rf + ws63-RF (WS63 Wi-Fi/BT/BLE/SLE blob + Rust porting 层)
│ chips/ws63/guide (WS63 中文硬件手册，Sphinx)
│ chips/bs2x/guide (BS2X 中文硬件手册，Sphinx)
│
│ ws63-qemu (姊妹仓：`-M ws63/bs21/bs22/bs20` QEMU，WS63/BS2X 软件在环验证)
│ probe-rs fork hispark-rs/add-hisilicon-ws63-bs21（RISC-V-DM + HiSilicon DebugSequence + flash-algorithm）
└──────────────────────────────────────────────────┘

核心设计模式

调试支持

• probe-rs（新）：fork hispark-rs/probe-rs 分支 add-hisilicon-ws63-bs21，实现 RISC-V Debug Module + HiSilicon 厂商 DebugSequence（mem-AP DTM）+ flash-algorithm crate。软件完整，待硅片真机验证。用法：probe-rs run --chip ws63 <bin> 进行实时调试与 on-silicon 烧录。

• 外设单例 + 'd 生命周期：Peripherals::take()（PAC 单例，critical-section 保护）分发 'd 参数化的 ZST 外设令牌； 驱动经构造器消费令牌，借生命周期防 use-after-drop。

• 多实例外设（UART/I2C/SPI/DMA）：用 PhantomData<&'d T> + 每实例构造器（new_uart0/new_uart1…）区分。

• sealed trait（private.rs）：Sealed 超 trait 防外部实现 DmaWord/PeripheralInput/PeripheralOutput。

• #![no_std]：无堆、无 Vec，数据缓冲用定长数组。

• 寄存器访问 unsafe：裸 PAC 写封装在驱动方法内。

• 异步（async/embassy feature，见 async-embassy.md）：中断 + waker 驱动的 embedded-hal-async/embedded-io-async 驱动 + 一个 embassy-time Driver，跑在无原子的 WS63 上 （portable-atomic + critical-section 垫片）。驱动只暴露 on_interrupt 钩子、不自动装 ISR。

注意：早先评审里的“零消费者脚手架“（DMA 安全 trait、空的 async marker）已处理 —— async marker 已删， 真正的异步层已实现并验证（见上）；RAII 时钟守卫等仍按 ROADMAP 阶段 2 评估。详见各组件文档。

构建与目标（target）

• 默认 target / 工具链：riscv32imfc-unknown-none-elf（RV32IMFC，硬件单精度浮点 ilp32f，无原子）， 由自定义 hisi-riscv 工具链提供（stable rustc 把该 target 烤成 builtin，故无需 -Z build-std， 工具链自带预编译 core/alloc）。rust-toolchain.toml pin channel = "hisi-riscv"；安装见 https://github.com/hispark-rs/hisi-riscv-rust-toolchain（rustup toolchain link hisi-riscv …）。
  • WS63 核无原子（A）扩展：该 target 用 forced-atomics + no-CAS，原子 load/store 降为 ld/st、 RMW 走 portable-atomic 的 critical-section polyfill，不发 lr/sc/amo。原默认 riscv32imafc 会发原子指令、在硅片上触发非法指令陷阱，已弃用。
  • 历史：2026-05-31 阶段 0 曾先用 builtin riscv32imc（软浮点、stable、免 build-std）做过渡； 随后切到 ws63 硬浮点工具链（与 ilp32f vendor blob ABI 一致，为阶段 3 链接做准备）。
• 单一 PAC 实例：根 Cargo.toml 用 [patch.crates-io] 把 ws63-pac 的 registry 依赖重定向到本地 submodule， 保证全仓库只链接一个 PAC（否则 DEVICE_PERIPHERALS 单例静态重复、类型不兼容）。
• default-members = 库 + blinky（ws63-pac/hisi-riscv-hal/hisi-riscv-rt/examples/ws63/blinky）。 blinky 经 hisi-riscv-rt 导出的链接脚本可正常链接（hisi-riscv-rt/build.rs 用 cargo:rustc-link-search 导出脚本目录 + ws63-link.x 包装脚本，blinky 的 build.rs 以 -Tws63-link.x 引入）。实验性的 ws63-flashboot 不在默认构建里， 仍是 member，cargo check --workspace 覆盖。

常用命令：

cargo build --release          # 构建库（default-members）
cargo check --workspace        # 检查全部（含 blinky/flashboot，不链接）
cargo clippy --workspace --exclude ws63-flashboot -- -D warnings
cargo build -p blinky             # 示例（已可链接；包含在默认构建中）
cargo build -p ws63-flashboot     # 显式构建实验性 flashboot（包名是 ws63-flashboot）

已知的全局性问题（详见评审台账）

1. 连接性状态：
   • WS63 Wi-Fi（ROADMAP 阶段 3-5）：porting 层 + 链接 + netif→smoltcp 已实现并在 QEMU 自测（阶段 4），符号闭合已达成；真机连通待 HIL（阶段 5）。
   • BS2X BLE/SLE（已评估）：radio MMIO 模拟是死胡同（B_CTL 0x59000000 为 56 个写只 PHY 寄存器 + IRQ-26 blob 事件墙），HCI 边界为 blob-on-blob（无法干预）；完整分析见 hisi-riscv-qemu/docs/bs21-connectivity-feasibility.md。
2. 示例无法链接 （已修，阶段 1）；多芯片支持 （已实现）：hisi-riscv-hal 用 chip-ws63/chip-bs21 feature 区分，二选一；examples 分为 WS63（submodule）、BS2X（in-tree 独立工作区）。
3. 硬件在环（HIL）进度：QEMU 软件在环已成熟（WS63/BS21/BS22/BS20 均支持，全外设功能覆盖），HIL 脚手架已就位（烧录脚本 + 冒烟框架）；待真机板卡到位进行 blinky/UART/中断冒烟。
4. 正确性修复状态：中断（LOCIEN/LOCIPRI/LOCIPCLR）、SPI（两级时钟）、超时（wait_until 有界）、复位（GLB_CTL + SYS_RST_RECORD）等核心问题已修（ROADMAP 阶段 2）；QEMU 软件在环验证已覆盖中断、复位、DMA、timer；上板验证仍待硬件（时钟精度、外设时序）。

参考资料

多芯片支持细节

• PAC 组织：crates/pac/ws63-pac 和 crates/pac/bs2x-pac 各自独立（SVD 源→svd2rust 生成），root Cargo.toml 经 [patch.crates-io] 统一链接到本地实例（保证单一 PAC 版本）。

• HAL 多芯片：hisi-riscv-hal 通过 chip-ws63（default）和 chip-bs21 feature 区分，条件编译外设模块（WS63 含 Wi-Fi 相关，BS2X 含 GADC/KEYSCAN/QDEC/RTC/TRNG 等 M1 外设）。

• 示例组织：WS63 示例遵循原 submodule 路径 examples/ws63/；BS2X 示例为 in-tree 独立工作区 examples/bs21/ 和 examples/bs20/（避免 submodule 膨胀）。

• QEMU 支持：ws63-qemu 已支持 -M ws63（8 GB 地址空间）、-M bs21（不同时钟/外设）、-M bs22/-M bs20（M2/M1），完整的 QEMU 外设仿真（UART/GPIO/Timer/DMA/SDMA/SPI/I2C/WDT/PDM/USB DWC OTG 等）。

• fbb_ws63（/root/fbb_ws63）：官方 C SDK，寄存器/外设行为的真值来源。

• esp-hal（/root/esp-hal）：成熟 Rust HAL 参照（esp-radio/esp-rtos/embassy/众多示例）——WS63 的连接性轨迹可对标。

hisi-riscv-hal 架构与评审

本文是 ws63-rs 架构文档的一部分。完整评审台账见 架构评审 2026-05，整改排期见 ROADMAP。

2026-06 更新：HAL 现为多芯片 —— chip-ws63（默认）/ chip-bs21 特性。后者基于 bs2x-pac 服务 BS21/BS2X（BLE 5.4 + SLE/星闪）家族；BS2X 全部功能外设（SPI/GADC/I2C/KEYSCAN/QDEC/RTC/TRNG/WDT/DMA/PDM/USB）已在 QEMU -M bs21/bs22/bs20 上验证。crate 路径 crates/hisi-riscv-hal。

职责与边界

hisi-riscv-hal 是 WS63 SoC 的硬件抽象层（HAL），在 ws63-pac 的裸寄存器之上手写安全、符合 embedded-hal 习惯的驱动 API。

• 负责：
  • 为 35 个 PAC 外设提供生命周期化的安全单例封装（peripherals.rs），并在其上实现 35 个外设驱动模块（GPIO、UART、SPI、I2C、DMA、PWM、Timer、WDT、RTC、TRNG、Tsensor、SFC、I2S、LSADC、eFuse、以及 KM/PKE/SPACC 等加密外设）。
  • 时钟架构：时钟门控（clock.rs 的 ClockControl + Peripheral 枚举）、引导期时钟树初始化（clock_init.rs）。
  • GPIO 三层驱动模型、DMA 双控制器抽象、sealed trait 体系（private.rs）。
  • embedded-hal 1.0 / embedded-hal-nb 1.0 / embedded-io 0.6 / nb 的 trait 实现。
• 不负责：
  • 裸寄存器布局与地址映射（属 ws63-pac）。
  • 启动汇编、链接脚本、中断向量表（属 hisi-riscv-rt）。
  • 应用业务逻辑（属 ws63-examples）。
  • 连接性协议栈（WiFi/BLE/SLE）、porting 层、HCC IPC（尚未实现，见 ROADMAP 阶段 4-5）。

#![no_std]、无堆、无 Vec（lib.rs:20）。寄存器访问全部经 unsafe { w.bits(...) } 封装在驱动方法内部。

在依赖链中的位置

ws63-svd (XML)
   │ svd2rust 生成
   ▼
ws63-pac ──► hisi-riscv-hal ──► examples/ws63/*
                ▲
       hisi-riscv-rt（启动汇编 / 链接脚本 / 中断向量）并行提供运行期支撑

hisi-riscv-hal 是承上启下的核心层：向下消费 ws63-pac 的 RegisterBlock，向上为示例提供驱动。它不直接依赖 hisi-riscv-rt，但其中断子系统依赖 riscv crate 的 trap 模型，运行期向量表由 hisi-riscv-rt 的 device.x 提供。

依赖：embedded-hal 1.0、embedded-hal-nb 1.0、embedded-io 0.6、nb、portable-atomic、riscv。

关键设计

类型化配置 — “能编译就能上板”（0.5.0）

0.5.0 把配置面全面收紧为「能写出来的值就是能在硅上跑的值」：不存在能编译却被静默 clamp / 截断 / 没接时钟的参数。约定与 A/B/C/D 缺陷分类见 类型化配置，验收见 docs/review/0.5.0-acceptance.md。 两层结构：

• 配置/构造面（HAL 自有，可自由类型化）：受校验 newtype + 可失败构造子返回 Option/Result（SpiHz/DataBits/BaudRate/WdtTimeout/SampleCount 等），越界 在构造点拒绝；角色用 type-state（I2S new_master(非零派生分频)/new_slave()，零分频 Master 不可表达）；驱动在 new/configure 里自起本外设时钟门（construct→clocked， 如 PWM/I2S）。类型编码的是实测硅事实而非数据手册（如 pwm::PwmPeriod 是 u16， 因 WS63 pwm_freq_h 高半字在硅上不 latch）。
• 操作面（embedded-hal trait，固定签名）：SetDutyCycle/SpiBus/I2c/Read/Write 保留标准 u16/&[u8] + Result（Result 即 embedded-hal 的非法输入惯用法），不改 trait 签名。

危险外设（Wdt/PwmChannel/Output）实现 scoped Drop（停表/关输出/回高阻），逃生口 into_armed/into_running/into_latched（消费 self→零大小 marker）。DMA 提供拥有缓冲区的 Transfer guard（embedded_dma bound + 缓存维护折进类型），safe 代码里 use-after-free 不可表达。 每个收紧面都有 host newtype/property 测试，并在连接的真机经 HIL 套件（tests/hil.rs）复验。

外设单例 + 'd 生命周期

peripherals.rs 用两个宏生成全套封装：

• peripheral!($name, $pac_ty)（peripherals.rs:10-48）— 为每个外设生成零大小、'd 参数化的 ZST，提供 unsafe steal()、ptr()、register_block()。
• peripherals!(...)（peripherals.rs:50-87）— 生成 Peripherals 结构体，take() 经 PAC 单例校验（peripherals.rs:61-64），unsafe steal() 绕过校验。

全部 35 个 PAC 外设都有 HAL 封装（peripherals.rs:157-193）。'd 生命周期防止 Peripherals token 被释放后仍持有驱动，是这一层的核心安全不变量（评审优点）。

时钟架构

两套并存：

1. clock_init.rs（标杆） — 逐寄存器对照 fbb_ws63 C SDK 的启动时钟序列核实。文件头部完整记录了 CLDO_CRG_CLK_SEL 位图、寄存器地址映射、时钟树（clock_init.rs:1-74）。init_clocks()（clock_init.rs:197-253）实现 flash→PLL（bit 18）、UART0/1/2→PLL（bits 1/2/3）、SPI→PLL（bit 6）的切换，并经 REG_EXCEP_RO_RG bit 12 轮询 PLL 锁定（clock_init.rs:127-148）。TCXO 频率检测读 HW_CTL bit 0（clock_init.rs:103-107）。所有地址均注明 fbb_ws63 出处。
2. clock.rs 的 RAII 时钟门控 — ClockControl 封装 CldoCrg，提供 enable_uart()/enable_spi() 等直接方法（clock.rs:192-260），以及 PeripheralGuard 引用计数守卫（clock.rs:86-125），用 static REF_COUNTS: [AtomicU8; 17]（clock.rs:74-78）做并发安全的开/关计数。Peripheral::cken_info()（clock.rs:45-67）将每个外设映射到 (cken 寄存器索引, 位)，PWM 的 9 位连续门控（bits 2:10）特殊处理。

GPIO 三层模型

19 个引脚分布在 3 个 block（GPIO0 bits 0-7、GPIO1 bits 8-15、GPIO2 bits 16-18），block 映射为 pin / 8、位为 pin % 8（评审确认正确）。两层（0.5.0 删除了遗留的 type-state GpioPin<MODE>，统一到下面这一套）：

1. AnyPin<'d> — 类型擦除，经 unsafe steal(pin) 创建。
2. Input / Output / Flex — 由 AnyPin 经 init_input()/init_output()/init_flex() 派生；degrade() 可安全擦除回 AnyPin，Flex::set_as_input/set_as_output 提供显式方向。

InputConfig { pull } / OutputConfig { open_drain, initial_high } 为配置入口（均有 with_* builder）。Output 实现 scoped Drop（回 input/高阻），逃生口 into_latched()/into_flex()。embedded-hal digital trait 用 Infallible 错误类型实现。

DMA 双控制器

Dma0（0x4A00_0000）与 Sdma0（0x520A_0000）共享 dma::RegisterBlock，经 DmaInstance trait 提供 ptr()（dma.rs:25-44）。DmaDriver<'d, T: DmaInstance> 泛型于控制器（dma.rs:144）。DmaEligible（dma.rs:428-431）+ DmaChannelFor<P>（dma.rs:439）意图提供编译期通道-外设绑定安全（刻意不写 blanket impl 以保留约束语义）。

Sealed trait + 异步层

private.rs 定义 Sealed 超 trait，封印 DmaWord、PeripheralInput、PeripheralOutput。早先空壳的 DriverMode/Blocking/Async mode 标记（associated type 恒等、零消费者）已删除。

真正的异步层已实现（feature async/embassy，详见 async-embassy.md）：embedded-hal-async/embedded-io-async 的 DelayNs/digital::Wait/spi::SpiBus/i2c::I2c/Read/Write，加上 asynch::block_on + IrqSignal（中断→waker 桥）+ 各驱动的 on_interrupt 钩子（不自动装 ISR）；外加 LSADC/DMA 的自研异步。还提供一个 embassy-time Driver（now()=TCXO 64 位计数器、alarm=TIMER 通道），让 embassy-executor（platform-riscv32）跑 Timer::after + 多任务。全部跑在无原子的 WS63 上（portable-atomic + critical-section）。

embedded-hal trait 选型（评审优点）

• SPI 实现 SpiBus 而非 SpiDevice（spi.rs:135）— HAL 层不持有 CS，符合分层惯例。
• I2C transaction 在操作间发 repeated-START、仅末尾发 STOP（i2c.rs:215-265），符合 embedded-hal 契约。NACK 映射为 NoAcknowledge（i2c.rs:278-280）。
• UART 同时实现 embedded-io Read/Write 与 embedded-hal-nb serial（uart.rs:172-293）。

编译期断言（safety.rs）

const_assert! 宏（safety.rs:11-20）校验 MMIO 地址范围、PERIPHERAL_COUNT == 17、各类外设/通道计数常量。注意此文件的多数断言为恒真（见评审问题）。

评审发现

优点

• clock_init.rs 是全仓标杆：逐寄存器、逐位对照 fbb_ws63 C SDK 核实，地址与位含义均注明出处（clock_init.rs:36-74、197-253）。
• 外设单例 + 'd 生命周期健全：宏生成统一、take() 经 PAC 单例校验，生命周期防 use-after-drop（peripherals.rs:10-87）。
• embedded-hal/embedded-io/nb trait 选型正确：SpiBus（非 SpiDevice）、I2C repeated-START、ACK→NoAcknowledge 均符合各 trait 契约（spi.rs:135、i2c.rs:215-280）。
• GPIO block 映射正确：pin/8 分 block、pin%8 取位，与 3 block × 8 位的硬件布局一致（gpio.rs:86-88）。

问题

下表为 2026-05 评审快照；其后多数阶段 2 项已修（见各行状态），权威进度以 评审台账 为准。全部修复在姊妹仓 ws63-qemu 软件在环验证。

改进项与排期

按 ROADMAP（多数已完成，下记现状）：

• 阶段 1（bring-up + 链接脚本集成）：✅ 链接脚本集成已打通（hisi-riscv-rt 经 cargo:rustc-link-search + ws63-link.x，示例正常链接）；✅ 恒真式测试已由 ws63-qemu 软件在环大幅替代（smoke-test.sh 跑真实固件 + C SDK 交叉验证）；🟡 真机 HIL 冒烟仍待补。
• 阶段 2（死代码清理 + 正确性修复）：✅ 中断子系统已重写到 LOCIPRI/LOCIEN/LOCIPD CSR 模型；✅ I2C/SPI 超时并返回错误；✅ software_reset/reset_reason；✅ GPIO pull + 中断触发；✅ safety.rs 恒真断言 + 夸大措辞已删；✅ async marker / RAII 时钟守卫死代码已删。🟡 SPI trsm、eFuse/LSADC 逐寄存器复核仍在推进。
• 新增（超出原评审）：✅ 异步 HAL（async/embassy feature，见 async-embassy.md）—— embedded-hal-async/embedded-io-async 全套 + embassy-time Driver，全部 ws63-qemu 验证。
• 阶段 4-5（porting 层 + HCC IPC + 连接性）：HAL 之上接入 WiFi/BLE/SLE 协议栈所需的 porting 与 IPC 通道。
• 阶段 6（async）：在确有异步消费者后再恢复 Blocking/Async 类型状态（阶段 2 已先删除空壳）。

hisi-riscv-rt 架构与评审

本文是 ws63-rs 架构文档的一部分。完整评审台账见 架构评审 2026-05，整改排期见 ROADMAP。

2026-06 更新：同一 runtime 服务 WS63 与 BS2X（BS21/BS20）。BS2X 示例自带按芯片的 memory.x（BS21E/BS22 160K、BS20 128K L2RAM），见 examples/bs21 / examples/bs20。

职责与边界

hisi-riscv-rt 是 WS63（RISC-V RV32IMFC_Zicsr）的最小运行时（runtime），负责把芯片从复位状态带到可执行 Rust main() 的环境。

负责：

• 复位向量：reset_vector 作为链接到 PROGRAM 区最前端的入口（asm/startup.S:18-26、layout.ld:19 的 ENTRY(reset_vector)）。
• CPU 早期初始化：清 PMP、设 mtvec、关中断、开 FPU、清 fcsr、初始化 gp/sp、栈金丝雀填充（asm/startup.S:28-73）。
• trap/中断向量与汇编分发：异常入口 trap_entry、NMI、6 个 MIE 中断、60 个 local 中断的向量与寄存器保存/恢复（asm/startup.S:76-428）。
• 段重定位：ROM data/BSS、TCM text/data/BSS、SRAM text、.data、.bss 从 flash 拷到 RAM 并清零（src/startup.rs:75-193）。
• 缓存与 PMP：I/D cache 使能（src/startup.rs:59-69），PMP 由 startup.S 在复位时清零（doc 注释提到 PMP 配置，但当前仅做禁用）。
• 链接脚本：内存布局（memory.x）、段布局（layout.ld）、中断符号默认值（device.x）。build.rs 生成 ws63-link.x 包装脚本（按 memory→layout→device→symbols INCLUDE），下游 bin 用一个 -Tws63-link.x 引入。bundled-memory-x 默认 feature：hisi-riscv-rt 默认把自己的 memory.x 放上链接搜索路径（零配置）；需要自定义布局的 bin 设 default-features = false 自带 memory.x（见 examples/ws63/custom_memory）。
• 入口属性与 prelude：re-export riscv_rt::entry 与 PAC 中断类型（src/lib.rs:44-64）。
• 临界区基础设施：作为持有单一应用 hart 的 crate，启用 riscv 的 critical-section-single-hart，为全固件提供唯一的 critical-section 实现（Cargo.toml 依赖注释；支撑 PAC 的 Peripherals::take() 与 HAL 的 portable-atomic polyfill）。

不负责：

• 不实现中断控制器逻辑（SYS_CTL1 / LOCIPRI / LOCIEN 的优先级与使能仅在 device.x 给出占位符，实际派发模型有误，见评审）。
• 不提供堆分配器（.heap 段仅预留地址，无 allocator）。
• 不做镜像头/验签/AB 切换（属 flashboot 与下游范畴）。
• 不做 porting/HCC/blob 连接性相关初始化。

在依赖链中的位置

ws63-svd (XML) → ws63-pac (svd2rust 生成) → hisi-riscv-hal → examples/ws63/*
                                  hisi-riscv-rt ─┘  提供启动/向量/链接脚本

hisi-riscv-rt 是“横切”运行时：它不在 PAC→HAL→examples 这条数据流主线上，而是为最终的 bin（examples） 提供入口、trap 向量与链接脚本。它依赖 ws63-pac（仅为 re-export 中断类型与共享单一 PAC 实例）、riscv 与 riscv-rt。

链接脚本传播（已解决）：lib 依赖的 cargo:rustc-link-arg 不传播到下游 bin。早先这导致示例无法链接；现已修——build.rs 改为 cargo:rustc-link-search 导出 OUT_DIR + 生成 ws63-link.x，bin 用 -Tws63-link.x 引入（rustc-link-search 会传播）。见评审“问题”表「本轮已修」条。

关键设计

启动序列（标准 RV32 bring-up）

asm/startup.S 的复位流程对照 fbb_ws63 SDK 的 start.S，符合标准 RV32 裸机启动惯例：

1. 清 pmpcfg0..3（startup.S:30-37，EDA/仿真 workaround）。
2. la t0, trap_vector; csrw mtvec, t0（startup.S:40-41）。
3. 关中断：csrwi mstatus,0 + csrwi mie,0（startup.S:44-45）。
4. 开 FPU：mstatus.FS=0b11，清 fflags（startup.S:48-50）。
5. 初始化 gp（norelax 包裹，startup.S:53-56）与 sp = __stack_top__（startup.S:59）。
6. 栈金丝雀填充 0xefbeadde（startup.S:62-70）。
7. tail runtime_init（startup.S:73）→ Rust 侧做重定位/清 BSS/再开 mie（src/startup.rs:21-50）。

内存地址（BOOTROM 0x100000、ROM 0x109000、ITCM 0x14C000、DTCM 0x180000、FLASH 0x200000、PROGRAM 0x230300、SRAM 0xA00000）与 fbb_ws63 一致（memory.x:16-41）。

trap/异常/中断汇编分发

• 异常：trap_entry（startup.S:320）用 save_all（36 字，含 mcause/mbadaddr/ccause 自定义 CSR）保存上下文，通过 mscratch 切到 __exc_stack_top__（startup.S:327-328），按 mcause 索引 .rodata 中的 excp_vect_table（startup.S:132-153、335-342）分发；M-mode ecall 单独走 handle_ecall_m（startup.S:356-361）。
• NMI：切到 __nmi_stack_top__，调 nmi_handler（startup.S:369-383）。
• MIE 中断：mie_interrupt_handler 宏生成 6 个（bits 26-31），切到 __irq_stack_top__，call mie\n\()_interrupt_handler（startup.S:389-410）。
• local 中断：60 个向量统一进 local_interrupt_handler，调 local_isr_dispatch（startup.S:418-428）。

每条 trap 路径都做了 mscratch 栈切换 + 上下文保存，异常路径还按 mcause 做表驱动派发，结构清晰。

链接脚本布局

layout.ld 改编自 fbb_ws63 的 linker.prelds：ITCM 放 patch 表/ROM-RAM 回调/TCM text；DTCM 放 ROM data/BSS、TCM data/BSS；SRAM 放 SRAM text、.data、.bss、栈、堆；FLASH(PROGRAM) 放 .text/.rodata 与各初始化段 LMA。.startup 段 KEEP(*(.text.entry)) 确保复位向量在 PROGRAM 区最前（layout.ld:125-129）。栈区在 .stacks (NOLOAD) 内自高地址向下生长（layout.ld:189-216）。

ISA / 原子性

build.rs 设 RISCV_RT_BASE_ISA=rv32i（无原子扩展）。默认 target 是 builtin 的 riscv32imfc-unknown-none-elf（RV32IMFC，硬件单精度浮点 ilp32f）；无 A 扩展，原子由 portable-atomic 的 critical-section polyfill 提供，hisi-riscv-rt 启用 riscv 的 critical-section-single-hart 作为整个固件唯一的 CS 实现（Cargo.toml）。这套 CS 也支撑 hisi-riscv-hal 的 async/embassy 异步层。

评审发现

优点

• 标准 RV32 启动：PMP 清零、mtvec、关中断、FPU、gp/sp、栈金丝雀、BSS/data 重定位齐备，流程对照 fbb_ws63（asm/startup.S:28-73、src/startup.rs:75-193）。
• 内存地址权威：memory.x 各区起始/长度与 fbb_ws63 SDK 对齐（memory.x:16-41）。
• trap 汇编质量高：异常/IRQ/NMI 均有 mscratch 栈切换 + 分栈（exc/irq/nmi 独立栈），异常按 mcause 索引 excp_vect_table 表驱动分发（asm/startup.S:318-428、132-153）。
• 单一 CS 实现的依赖边界清晰：由持有 hart 的 hisi-riscv-rt 独家启用 critical-section-single-hart，避免多处重复实现（Cargo.toml 注释）。

问题

说明：构建完整性修复中与本组件相关的还包括——双 PAC 实例消除（根 [patch.crates-io] 指向本地，cargo tree 单一实例）、无原子 ISA 下实测产物零原子指令（lr/sc/amo）。默认 target 现为 ws63 工具链 builtin 的 riscv32imfc-unknown-none-elf（硬浮点；2026-05-31 曾过渡用 stable riscv32imc）。这些在仓库级评审中记录，本组件直接相关项已并入上表。

改进项与排期

• 阶段 1（链接脚本集成 ✅ 已完成 / 上板待硬件）：链接脚本不传播问题已解决（rustc-link-search + ws63-link.x 包装脚本 + blinky build.rs 引入），blinky 现可链接并产出 .bin。剩余：真机上板冒烟、用 readelf 核实 WS63 布局生效。
• 阶段 2（死代码清理 + 正确性修复）：修正 mtvec 模式与向量表的不一致（Direct vs Vectored）；为 trap 段在 layout.ld 增加显式输出段放置；统一 .stacks 布局与 memory.x 栈顶 fallback；并随中断子系统模型纠正（PLIC vs LOCIPRI/LOCIEN）一并处理。对应上表前两行。
• 其余仓库级排期（efuse/lsadc、flashboot 镜像头/验签/AB、porting+HCC+blob 连接性、async）见 ROADMAP 阶段 2-6，与本运行时组件无直接耦合。

ws63-pac 架构与评审

本文是 ws63-rs 架构文档的一部分。完整评审台账见 架构评审 2026-05，整改排期见 ROADMAP。

2026-06 更新：PAC crate 现归并在 crates/pac/ws63-pac（内嵌生成源 ws63-svd）。其 BS2X 同胞 crates/pac/bs2x-pac（由 bs2x-svd 生成）以同样的 svd2rust 流水线服务 BS21/BS2X 家族。

职责与边界

ws63-pac 是 WS63 SoC 的外设访问层（Peripheral Access Crate），由 svd2rust 从 SVD 描述生成。它的职责非常聚焦：

• 负责：为芯片上的 35 个外设提供 RegisterBlock 结构体与类型安全的寄存器读/写/改访问器；提供 Peripherals 单例（take() / steal()）；提供外部中断枚举 ExternalInterrupt；在 rt feature 下提供中断向量表 device.x。
• 不负责：任何驱动逻辑、时钟门控策略、引脚复用、外设初始化时序。这些全部上移到 hisi-riscv-hal。PAC 只暴露“裸寄存器 + 地址映射“，是 unsafe 寄存器写入的最底层封装边界。

crate 元数据齐全（Cargo.toml:1-9）：license = "MIT"、repository、keywords、categories，具备发布到 crates.io 的条件。

在依赖链中的位置

ws63-svd (XML)
   │ svd2rust 0.37.1 生成
   ▼
ws63-pac ──► hisi-riscv-hal ──► examples/ws63/*
   │
   └──► hisi-riscv-rt（rt feature 提供 device.x 中断向量 + RISCV_RT_BASE_ISA）

• 上游：ws63-svd 的 XML 描述，经 svd2rust v0.37.1 一次性生成（src/lib.rs:1 doc 注释标注版本）。
• 下游：hisi-riscv-hal（安全驱动）与 hisi-riscv-rt（启动/链接）均消费本 crate。两者通过 registry 版本依赖 version = "0.1" 声明（crates/hisi-riscv-hal/Cargo.toml:12、crates/hisi-riscv-rt/Cargo.toml:21），在 monorepo 内由根 Cargo.toml 的 [patch.crates-io] 重定向到本地路径（Cargo.toml:50-51），保证全工作区只链接单一 PAC 实例。

关键设计

• svd2rust 0.37.1 现代访问器：generic 层用 Periph<RB, const A: usize> 把外设基址作为 const 泛型参数编码（src/lib.rs:14-20），ptr() 是 const fn（src/lib.rs:23-25），Deref 直接解到寄存器块（src/lib.rs:45-51）。这是新版 svd2rust 的 const-fn 访问器风格，零运行时开销。
• Peripherals 单例：static mut DEVICE_PERIPHERALS: bool（src/lib.rs:31681）作为一次性标志；take() 在 critical-section 内检查并返回 Option<Self>（src/lib.rs:31760-31767），steal() 为 unsafe 无检查版本（src/lib.rs:31774-31813）。Peripherals 结构体逐字段持有 35 个外设的 ZST 句柄（src/lib.rs:31684-31755）。
• 35 外设覆盖：从 sys_ctl1、三路 gpio0/1/2、三路 uart0/1/2、双 i2c、双 spi、dma/sdma，到安全引擎 spacc/pke/km/trng 与时钟复位 cldo_crg 等全部映射（src/lib.rs:31685-31754）。
• 中断模型：ExternalInterrupt 枚举用 #[riscv::pac_enum(unsafe ExternalInterruptNumber)] 标注（src/lib.rs:902-904），中断号从 26 起（TIMER_INT0 = 26，src/lib.rs:906）。rt feature 下 build.rs 把 device.x 写入 OUT_DIR 并加入 link-search（build.rs:8-18），向量表用 PROVIDE(... = DefaultHandler) 提供弱默认（device.x:1-30）。
• feature 设计：default = ["critical-section"]，外加 rt（Cargo.toml:16-18）。take() 仅在 critical-section 下编译（src/lib.rs:31758），符合 svd2rust 约定。
• ISA 协同：rt feature 下 build.rs 导出 RISCV_RT_BASE_ISA=rv32i（build.rs:16），与本轮 ISA 修复（默认 target 切到 riscv32imc、产物零原子指令）一致。

评审发现

优点

• svd2rust 0.37.1 现代 const-fn 访问器，generic 层零开销（src/lib.rs:14-51）。
• 编译快（约 6s 过编译），单文件无复杂构建依赖。
• 工程化完备：device.x 中断向量、critical-section/rt feature（Cargo.toml:16-18）、crates.io 元数据齐全（Cargo.toml:1-9）。
• 单例语义正确：take()/steal() 配合 DEVICE_PERIPHERALS 标志在临界区内做一次性保护（src/lib.rs:31760-31775）。

问题

改进项与排期

本轮（2026-05-31，ROADMAP 阶段 0）已完成的构建完整性修复中，与本 crate 直接相关：

• 双 PAC 消除：hisi-riscv-hal/ws63-flashboot 改为 registry 版本依赖，根 Cargo.toml 用 [patch.crates-io] 统一指向本地（Cargo.toml:50-51），全工作区单实例。
• 版本对齐：0.1.0 → 0.1.1（与 tag 后新增的 KM 寄存器对齐），其后随各仓自有流水线发布到 0.1.3。
• ISA 协同：rt feature 导出 RISCV_RT_BASE_ISA=rv32i（build.rs:16），配合默认 target = builtin、无原子的 riscv32imfc-unknown-none-elf（硬件单精度浮点 ilp32f，原子由 portable-atomic critical-section polyfill 提供）。

仍需后续处理（指向 ROADMAP 对应阶段）：

• 手补寄存器回源（阶段 2）：把 KM keyslot 等人工添加的寄存器回填到 ws63-svd，使其由 svd2rust 重生成产出，消除“生成产物被手改“的维护风险；同阶段一并补齐 efuse / lsadc 等外设寄存器的正确性。
• 单文件体积：作为生成产物，按 svd2rust 惯例暂不拆分；若后续 SVD 重构，可评估按外设分模块生成。

ws63-svd 架构与评审

本文是 ws63-rs 架构文档的一部分。完整评审台账见 架构评审 2026-05，整改排期见 ROADMAP。

职责与边界

ws63-svd 是整个 ws63-rs 寄存器抽象链的上游真值（source of truth）。它由一份手写的 CMSIS-SVD 描述文件 WS63.svd 加少量 Python 工具构成，负责：

• 用 CMSIS-SVD 1.3 schema 描述 WS63 SoC 的外设、寄存器、字段、枚举值与地址布局（WS63.svd:2，schemaVersion="1.3"）。
• 提供针对官方 CMSIS XSD 的格式校验脚本（validate.py）。
• 承载 svd2rust 目标配置（ws63-settings.yaml，RV32IMFC_Zicsr 等 RISC-V 目标参数）。
• 驱动可复现的 SVD→PAC 生成流水线（regen.sh + postprocess.py，2026-05-31 起；见“关键设计/生成流水线”）。

它不负责：

• 托管 Rust 生成产物（产物 lib.rs 落在下游 ws63-pac；本组件提供并驱动生成流水线 regen.sh，产物归 PAC 仓）。
• 任何运行时逻辑或驱动语义（那是 hisi-riscv-hal 的职责）。
• 中断控制器的运行时模型（SVD 仅声明 <interrupt> 编号，控制器建模问题归 HAL/RT 层）。

寄存器定义来源为公开的 ws63-guide 文档与 fbb_ws63 HAL 头文件转录（WS63.svd:5-7 的 <licenseText>），属于手工建模而非厂商官方 SVD。

在依赖链中的位置

flowchart LR
    SVD["ws63-svd<br/>(WS63.svd 手写真值)"] -->|svd2rust 生成| PAC["ws63-pac<br/>(寄存器 RegisterBlock)"]
    PAC --> HAL["hisi-riscv-hal<br/>(安全驱动)"]
    HAL --> EX["examples/ws63/*"]
    RT["hisi-riscv-rt<br/>(启动/链接/向量)"] --> EX

ws63-svd 处于链条最上游：WS63.svd 经 svd2rust 生成 ws63-pac 的 lib.rs，再由 hisi-riscv-hal 封装为安全驱动，最终被 ws63-examples 使用。hisi-riscv-rt 提供启动代码与链接脚本，是与上述生成链平行的独立分支。

生成关系（2026-05-31 起可复现）：WS63.svd 经 regen.sh（svd2rust 0.37.1 + 确定性后处理 + cargo fix/fmt）生成 crates/pac/ws63-pac/src/lib.rs，幂等（同 SVD → 字节一致产物），内建 build+clippy 门禁。SVD 与 PAC 之间已是可复现的生成关系，不再“人工对照”。

关键设计

SVD 文件结构与建模质量

WS63.svd 约 1.07 万行（精确 10744 行）（WS63.svd:1-10744），device 头声明了 CPU 为 other、fpuPresent=true/fpuDP=false、width/size=32、nvicPrioBits=3（WS63.svd:9-18），description 中记录了 ISA rv32i2p1_m2p0_f2p2_c2p0_zicsr2p0 与 512KB ITCM / 288KB DTCM / 640KB 共享 SRAM 的内存规格（WS63.svd:4）。

建模规模与完整度（实测 2026-06-11）：

• 36 个 <peripheral> 元素（grep -c "<peripheral"），覆盖 SYS_CTL1、IO_CONFIG、GPIO0/1/2、UART0/1/2、I2C0/1、PWM、DMA、SFC_CFG、SPI0/1、I2S、LSADC、TSENSOR、TIMER、WDT、RTC、EFUSE、SYS_CTL0、GLB_CTL_M、SPACC、PKE、KM、TRNG、TCXO、CLDO_CRG、SDMA、ULP_GPIO、RF_WB_CTL、SHARE_MEM_CTL、FAMA_REMAP。
• 501 个非派生 <register> 定义（grep -c "<register>"；评审时为 497，本轮 eFuse/LSADC 修复 +4：eFuse 数据窗口 +1、LSADC 重写 +3；含 derivedFrom 展开后逻辑实例更多）。
• 920 个 <field>、44 处 <enumeratedValues>、36 个 <addressBlock>、2 处 <writeConstraint>、190 处 read-only 访问限定。
• 8 处 derivedFrom 复用。

UART/GPIO/KM 等外设建模质量较高：字段拆分、枚举值与访问属性齐全。例如 KM（Key Management，WS63.svd:9410，baseAddress 0x44112000）对 KLAD 派生、keyslot 锁定、RKP 根密钥保护建模到了字段级（KL_KEY_CFG 的 port_sel/key_enc/key_dec 等，flush_hmac_kslot_ind 字段亦已建模）。

校验工具

validate.py（validate.py:1-29）从 ARM CMSIS_5 仓库下载 CMSIS-SVD.xsd 缓存到 /tmp，用 xmlschema 对 WS63.svd 做 XSD 校验，PASS/FAIL 返回码区分。依赖在 pyproject.toml 声明为 xmlschema>=4.3.1，由 uv.lock 锁定。这是目前唯一真实可用的工具。

生成流水线（regen.sh，可复现）

regen.sh + postprocess.py（2026-05-31）把 WS63.svd 可复现地生成为 crates/pac/ws63-pac/src/lib.rs，固定工具版本 svd2rust@0.37.1 / form@0.13.0。五步：

1. svd2rust -i WS63.svd --target riscv --settings ws63-settings.yaml
2. rustfmt（svd2rust 原始输出未格式化，后续正则后处理依赖多行格式）
3. postprocess.py 两处确定性修补：删除 dim 重复生成的 5 个 TIMER 裸访问器（否则与索引访问器重复定义、编译失败）、#[no_mangle]→#[unsafe(no_mangle)]（edition 2024 硬错误）
4. cargo fix 自动套 unsafe_op_in_unsafe_fn（rt+critical-section 特性下 Peripherals::steal() 的 unsafe 包裹）
5. cargo fmt，随后 build + clippy 作为门禁

流水线幂等：同一 SVD 重跑产出字节一致的 lib.rs。ws63-settings.yaml 提供 svd2rust 目标设置（RV32IMFC_Zicsr、自定义中断控制器 SYS_CTL1 无标准 CLINT/PLIC、单 hart、240MHz）。main.py 仍是 uv 占位入口，实际生成走 regen.sh。主仓 PreToolUse hook 拦截对 crates/pac/ws63-pac/src/lib.rs 的手改，强制走重生成。

评审发现

优点

• 建模覆盖广：36 外设 / 497 寄存器，enumeratedValues、derivedFrom、writeConstraint、addressBlock 一应俱全，是一份结构完整、可被 svd2rust 直接消费的 1.3 版 SVD。
• 通过 derivedFrom 对同构外设（GPIO/UART/I2C/SPI/SDMA）做了正确复用，降低了维护面。
• 提供了针对官方 CMSIS XSD 的格式校验脚本，建模本身有质量门可依。
• UART/GPIO/KM 等关键外设建模到字段+枚举级，下游 HAL 可直接获得类型安全的位域访问。

问题