SDK 架构

SDK 目录结构

rust/
├── ameba-hal/          HAL 驱动层：GPIO、I2C、SPI、UART、Timer 等外设抽象
│   ├── src/
│   ├── ld/             主链接脚本（ameba.x）及内存布局定义
│   └── pac/            amebagreen2-pac（svd2rust 生成的寄存器访问层）
├── ameba-rom-sys/      ROM FFI 绑定层：extern "C" 声明 + ROM 符号链接脚本
│   ├── src/
│   ├── ld/             ameba_rom_symbol.x（ROM 函数地址映射）
│   └── bin/            预编译固件缓存（boot.bin、WiFi 核固件）
├── ameba-rt/           运行时层：Bootloader 入口表、cortex-m-rt 扩展
├── ameba-wifi/         WiFi 网络层：WHC IPC 驱动 + smoltcp 协议栈
│   └── ld/             ameba_rom_symbol_wifi.x（WiFi ROM 符号地址映射）
├── examples/           示例工程（hello-world、gpio、tim、shell、wifi-connect）
├── xtask/              编译编排工具（cargo xtask build-amebagreen2）
├── scripts/            辅助脚本（工具链安装等）
├── doc/                SDK 内部技术文档
├── rust-toolchain.toml 锁定 nightly 工具链版本及交叉编译 target
└── Cargo.toml          workspace 根配置

Crate 分层

SDK 按职责分为五层，从上到下依次为：

Crate	层次	职责
`ameba-wifi`	网络层	WHC IPC 通道驱动（AP ↔ NP 核间通信）+ smoltcp 协议栈（DHCP、TCP、UDP）
`ameba-hal`	硬件抽象层	封装 GPIO、I2C、SPI、UART、Timer 等外设，实现 `embedded-hal 1.0` trait
`amebagreen2-pac`	外设访问层	svd2rust 生成的寄存器类型安全访问，含 `device.x` 中断处理、函数链接声明等
`ameba-rom-sys`	FFI 绑定层	裸 `extern "C"` 声明 ROM 函数，通过链接脚本将符号名解析为 ROM 固定地址
`ameba-rt`	运行时层	提供 Bootloader 入口表、VTOR pre_init``（``cortex-m-rt 扩展）

编译流水线

cargo xtask build-amebagreen2 完成以下三个阶段：

阶段	工具	输出
1	`cargo build`	ELF 固件（含调试符号）
2	`arm-none-eabi-nm` + `arm-none-eabi-objcopy`	`km4tz_image2_all.bin` （image2 格式，Bootloader 可识别）
3	`axf2bin.py fw_pack`	`app.bin` （合并 Bootloader + NP 核固件 + AP 核固件，最终烧录文件）

ROM FFI 机制

SDK 底层通过 FFI 直接调用芯片 ROM 中固化的 C 函数。链接时，ameba_rom_symbol.x 将函数名解析为 ROM 固定地址，Rust 调用最终编译为一条跳转指令，无额外开销。

// ameba-rom-sys 中的声明
extern "C" {
    pub fn DiagPrintf(fmt: *const u8, ...) -> i32;
}

// 用户代码调用（需 unsafe）
unsafe { ameba_rom_sys::DiagPrintf(b"Hello\n\0".as_ptr()); }

ameba-hal 将 ROM 调用封装在内部，对外提供安全的 Rust API，用户通常无需直接使用 unsafe。