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 |
层次 |
职责 |
|---|---|---|
|
网络层 |
WHC IPC 通道驱动(AP ↔ NP 核间通信)、STA(Open / WPA2-PSK)与 SoftAP 控制,并实现 |
|
OTA 层 |
通过调用方提供的传输通道下载新的应用固件,并写入未运行的 A/B 分区 |
|
硬件抽象层 |
封装 GPIO、I2C、SPI、UART、Timer 等外设,实现 |
|
外设访问层 |
svd2rust 生成的寄存器类型安全访问,含 |
|
存储层 |
NOR Flash 驱动,含跨核 IPC flash 锁,实现 |
|
运行时层 |
提供 Bootloader 入口表、VTOR |
|
ROM 符号层 |
提供 ROM 符号链接脚本 |
主机侧 crate,运行在开发主机上:
Crate |
职责 |
|---|---|
|
提取固件 ELF 中的可加载段,打包 |
|
编译编排( |
编译流水线
cargo xtask build example 在主机上依次执行以下阶段:
阶段 |
步骤 |
输出 |
|---|---|---|
1 |
预编译固件检查 |
确认 |
2 |
|
ELF 固件 |
3 |
|
|
4 |
|
|
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。