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

ameba-wifi

Network

WHC IPC channel driver (AP ↔ NP inter-core communication), STA (Open / WPA2-PSK) and SoftAP control, and an embassy-net-driver implementation so applications can use embassy-net sockets (DHCP, TCP, UDP)

ameba-ota

OTA

Downloads a new application image over a caller-supplied transport and programs it into the inactive A/B slot

ameba-hal

HAL

Wraps GPIO, I2C, SPI, UART, Timer, and other peripherals, and implements embedded-hal 1.0 traits. Drivers not yet verified on hardware are gated behind the unstable feature

rtl8721f-pac

PAC

svd2rust-generated type-safe register access, and includes device.x interrupt handler link declarations

ameba-storage

Storage

NOR Flash driver with cross-core IPC flash lock, and implements embedded-storage traits

ameba-rt

Runtime

Provides the Bootloader entry table and VTOR pre_init (cortex-m-rt extension)

ameba-rom-sys

ROM symbols

Provides the ROM symbol linker script ameba_rom_symbol.x: its build script adds it to the link search path so the linker can resolve ROM function names to fixed addresses. Also holds the prebuilt binaries under bin/

The host-side crates, which run on the development machine:

Crate

Responsibility

ameba-flash

Extracts the loadable sections of a firmware ELF, packages app.bin and ota_all.bin, and implements the UART flashing protocol and serial monitor. The prebuilt boot.bin, Wi-Fi core firmware and flash loader are embedded in it. Usable as a library and as the ameba-flash command-line cargo runner

xtask

Build orchestration (cargo xtask): builds examples, calls ameba-flash to package and flash, and runs the check / lint / fmt / build doc / ci gates across every firmware crate

Build Pipeline

cargo xtask build example runs the following stages on the host:

Stage

Step

Output

1

Prebuilt check

Confirms boot.bin and km4ns_image2_all.bin are present under ameba-rom-sys/bin/rtl8721f/, and checks every Wi-Fi API ID called by ameba-wifi against np_api_ids.txt, so a call the prebuilt Wi-Fi core firmware cannot handle fails the build instead of hanging on hardware

2

cargo build --release

ELF firmware

3

ameba-flash ELF extraction

km4tz_image2_all.bin (the ELF’s XIP, SRAM and PSRAM sections, each with an image2 section header recognized by the Bootloader)

4

ameba-flash packaging

app.bin (certificate + manifest + Wi-Fi core firmware + application firmware), and ota_all.bin (app.bin with an OTA header)

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.