SDK Architecture
SDK Directory Structure
rust/
├── ameba-hal/ HAL driver layer: GPIO, UART, SPI, I2C, Timer, ADC, DMA, Ethernet and other peripherals
│ ├── src/
│ ├── ld/ Main linker script (ameba.x) and memory layout definitions
│ └── pac/rtl8721f/ rtl8721f-pac (svd2rust-generated register access layer)
├── ameba-rt/ Runtime layer: Bootloader entry table, VTOR setup, panic handler
├── ameba-wifi/ Wi-Fi layer: WHC IPC driver, STA/SoftAP control, embassy-net driver
│ └── ld/ ameba_rom_symbol_wifi.x (Wi-Fi ROM symbol address map)
├── ameba-storage/ Storage layer: NOR Flash driver (embedded-storage traits)
├── ameba-ota/ OTA layer: dual-slot (A/B) image update with HTTP transport
├── ameba-rom-sys/ ROM symbol table for the linker + prebuilt binaries
│ ├── ld/ ameba_rom_symbol.x (ROM function address map)
│ └── bin/rtl8721f/ boot.bin, km4ns_image2_all.bin, floader_rtl8721f.bin, np_api_ids.txt
├── ameba-flash/ Host-side image packaging and UART flashing (library + CLI)
├── examples/ Example projects, each with its own README
├── xtask/ Host-side build tool (cargo xtask build / run / check / lint / fmt / ci)
├── scripts/ Helper scripts (toolchain installation)
├── rust-toolchain.toml Pins the stable toolchain channel and cross-compilation targets
└── Cargo.toml Root workspace, containing only xtask
The root Cargo workspace contains only xtask. Every firmware crate (including each example) is an
independent mini-workspace with its own Cargo.lock and .cargo/config.toml, so each builds for the
embedded target without the host tool interfering. As a result, a plain cargo clippy at the
repository root covers only xtask: use cargo xtask check / lint / fmt to cover every crate.
Crate Layers
The firmware-side crates, from top to bottom:
Crate |
Layer |
Responsibility |
|---|---|---|
|
Network |
WHC IPC channel driver (AP ↔ NP inter-core communication), STA (Open / WPA2-PSK) and SoftAP control, and an |
|
OTA |
Downloads a new application image over a caller-supplied transport and programs it into the inactive A/B slot |
|
HAL |
Wraps GPIO, I2C, SPI, UART, Timer, and other peripherals, and implements |
|
PAC |
svd2rust-generated type-safe register access, and includes |
|
Storage |
NOR Flash driver with cross-core IPC flash lock, and implements |
|
Runtime |
Provides the Bootloader entry table and VTOR |
|
ROM symbols |
Provides the ROM symbol linker script |
The host-side crates, which run on the development machine:
Crate |
Responsibility |
|---|---|
|
Extracts the loadable sections of a firmware ELF, packages |
|
Build orchestration ( |
Build Pipeline
cargo xtask build example runs the following stages on the host:
Stage |
Step |
Output |
|---|---|---|
1 |
Prebuilt check |
Confirms |
2 |
|
ELF firmware |
3 |
|
|
4 |
|
|
cargo xtask run example then flashes over UART: it loads the flash loader into SRAM through the
chip’s ROM download mode, writes boot.bin to 0x08000000 and app.bin to 0x08040000,
resets the board and opens a serial monitor.
Note
Packaging covers only images built with secure boot and flash encryption (RSIP/RDP) disabled, which is the default configuration of this chip. No hashing, signing or encryption is performed, so an image packaged this way will not boot on a part provisioned to require a signature.
ROM FFI Mechanism
Where a driver needs a C function fixed in chip ROM, it calls it directly through FFI. At link time, a linker script resolves the function name to its fixed ROM address, so the call compiles to a single branch instruction with no additional overhead:
// extern "C" declaration, declared locally by the driver
unsafe extern "C" {
fn SomeRomFunction(arg: u32);
}
// Calling from driver code (requires unsafe)
unsafe { SomeRomFunction(100); }
Drivers access hardware either through the PAC registers or through ROM FFI, and any driver that uses ROM FFI wraps the call internally and exposes a safe Rust API, so user code typically does not need to use unsafe directly.