SDK 架构

SDK 目录结构

rust/
├── ameba-hal/          HAL 驱动层:GPIO、UART、SPI、I2C、Timer、ADC、DMA、Ethernet 等外设
│   ├── src/
│   ├── ld/             主链接脚本(ameba.x)及内存布局定义
│   └── pac/rtl8721f/   rtl8721f-pac(svd2rust 生成的寄存器访问层)
├── ameba-rt/           运行时层:Bootloader 入口表、VTOR 设置、panic handler
├── ameba-wifi/         Wi-Fi 层:WHC IPC 驱动、STA/SoftAP 控制、embassy-net 驱动
│   └── ld/             ameba_rom_symbol_wifi.x(Wi-Fi ROM 符号地址映射)
├── ameba-storage/      存储层:NOR Flash 驱动(embedded-storage trait)
├── ameba-ota/          OTA 层:双分区(A/B)固件升级及 HTTP 传输
├── ameba-rom-sys/      供链接器使用的 ROM 符号表 + 预编译固件
│   ├── ld/             ameba_rom_symbol.x(ROM 函数地址映射)
│   └── bin/rtl8721f/   boot.bin、km4ns_image2_all.bin、floader_rtl8721f.bin、np_api_ids.txt
├── ameba-flash/        主机端固件打包与串口烧录(库 + 命令行工具)
├── examples/           示例工程,每个示例都有自己的 README
├── xtask/              主机端编译工具(cargo xtask build / run / check / lint / fmt / ci)
├── scripts/            辅助脚本(工具链安装)
├── rust-toolchain.toml 锁定 stable 工具链及交叉编译 target
└── Cargo.toml          根 workspace,仅包含 xtask

根 Cargo workspace 只包含 xtask。每个固件 crate(包括每个示例)都是独立的小 workspace,各自带有 Cargo.lock 和 .cargo/config.toml,因此各自面向嵌入式 target 编译,不会与主机端工具互相干扰。也正因如此,在仓库根目录直接执行 cargo clippy 只会检查 xtask,要覆盖所有 crate 请使用 cargo xtask check / lint / fmt。

Crate 分层

固件侧 crate 从上到下依次为:

Crate

层次

职责

ameba-wifi

网络层

WHC IPC 通道驱动(AP ↔ NP 核间通信)、STA(Open / WPA2-PSK)与 SoftAP 控制,并实现 embassy-net-driver,应用可直接使用 embassy-net socket(DHCP、TCP、UDP)

ameba-ota

OTA 层

通过调用方提供的传输通道下载新的应用固件,并写入未运行的 A/B 分区

ameba-hal

硬件抽象层

封装 GPIO、I2C、SPI、UART、Timer 等外设,实现 embedded-hal 1.0 trait。尚未在硬件上验证的驱动需开启 unstable feature 才能使用

rtl8721f-pac

外设访问层

svd2rust 生成的寄存器类型安全访问,含 device.x 中断处理、函数链接声明等

ameba-storage

存储层

NOR Flash 驱动,含跨核 IPC flash 锁,实现 embedded-storage trait

ameba-rt

运行时层

提供 Bootloader 入口表、VTOR pre_init ( cortex-m-rt 扩展)

ameba-rom-sys

ROM 符号层

提供 ROM 符号链接脚本 ameba_rom_symbol.x:其 build script 将其加入链接搜索路径,使链接器能把 ROM 函数名解析为固定地址;同时在 bin/ 下存放预编译固件

主机侧 crate,运行在开发主机上:

Crate

职责

ameba-flash

提取固件 ELF 中的可加载段,打包 app.bin 和 ota_all.bin,并实现串口烧录协议和串口监视。预编译的 boot.bin、Wi-Fi 核固件和 Flash Loader 已内嵌其中。既可作为库调用,也可作为命令行 cargo runner ameba-flash 使用

xtask

编译编排( cargo xtask ):编译示例,调用 ameba-flash 完成打包与烧录,并对所有固件 crate 执行 check / lint / fmt / build doc / ci 检查

编译流水线

cargo xtask build example 在主机上依次执行以下阶段:

阶段

步骤

输出

1

预编译固件检查

确认 ameba-rom-sys/bin/rtl8721f/ 下存在 boot.bin 和 km4ns_image2_all.bin,并将 ameba-wifi 调用的每个 Wi-Fi API ID 与 np_api_ids.txt 比对,使预编译 Wi-Fi 核固件无法处理的调用在编译期报错,而不是在硬件上卡死

2

cargo build --release

ELF 固件

3

ameba-flash 提取 ELF

km4tz_image2_all.bin (ELF 的 XIP、SRAM、PSRAM 段,各自带有 Bootloader 可识别的 image2 段头)

4

ameba-flash 打包

app.bin (证书 + manifest + Wi-Fi 核固件 + 应用固件),以及 ota_all.bin (加了 OTA 头的 app.bin )

cargo xtask run example 随后通过串口烧录:借助芯片 ROM 下载模式将 Flash Loader 加载到 SRAM,把 boot.bin 写入 0x08000000、 app.bin 写入 0x08040000,然后复位开发板并打开串口监视。

备注

打包仅支持关闭安全启动和 Flash 加密(RSIP/RDP)的固件,这也是该芯片的默认配置。打包过程不做任何哈希、签名或加密,因此这样打包的固件无法在已配置为强制校验签名的芯片上启动。

ROM FFI 机制

当某个驱动需要调用芯片 ROM 中固化的 C 函数时,会直接通过 FFI 调用。链接时,链接脚本将函数名解析为 ROM 固定地址,调用最终编译为一条跳转指令,无额外开销:

// extern "C" 声明,由驱动自行声明
unsafe extern "C" {
    fn SomeRomFunction(arg: u32);
}

// 驱动代码中调用(需 unsafe)
unsafe { SomeRomFunction(100); }

驱动通过 PAC 寄存器或 ROM FFI 两种方式访问硬件,使用 ROM FFI 的驱动会将调用封装在内部,对外提供安全的 Rust API,用户通常无需直接使用 unsafe。