API overview
The full, always-current API reference is the generated rustdoc:
flintos API docs. It is built
from the doc comments on every push to main, so it never drifts from the code.
This page is the map — what each part is and where to start. rustdoc answers what’s callable; this answers where to look.
Writing an application — the system API
Section titled “Writing an application — the system API”Everything an application calls lives in the api crate.
| Module | What it gives you |
|---|---|
api::prelude |
use api::prelude::*; — one glob for the logging macros, the Task builder, sleep_ms/exit/wait_until, Error/Result, the sync cells and the bus/pin/stream surface |
api::task |
The Task builder (Task::new(name, entry).priority(..).stack(..).on_core(..).spawn()), plus spawn/spawn_on free fns, sleep_ms, yield_now, exit, wait_until |
api::queue |
Typed, bounded queues; send/recv with timeout, send_isr from an interrupt |
api::mutex |
Mutex with priority inheritance; lock returns a guard |
api::sync |
Once and CsCell shared-static cells (also re-exported at the crate root) |
api::timer |
now_ms and the monotonic tick |
api::time |
now_us — microsecond monotonic clock, for timing shorter than a tick |
api::interrupt |
connect(source, handler) — route a peripheral IRQ to a top-half |
api::dma |
alloc/begin/await_transfer for drivers that move blocks |
api::Error / api::Result |
The one error type an application ?s into (re-exported from hal) |
api::debug |
log_error!…log_trace!, metrics, stack high-water marks, panic capture |
Start with Tutorial: Hello World.
Writing a driver — the layer contracts
Section titled “Writing a driver — the layer contracts”A driver implements one trait for its layer and calls only the layer below. The traits are the contract; the rustdoc carries the exact signatures.
| You are writing | Implement | Reference |
|---|---|---|
| A sensor / display / LED (Layer 3) | uses a BusHandle, or a lib/ device trait like LedStrip |
hal::bus::BusHandle, led_strip |
| A protocol bus (Layer 2) | api::bus::Bus |
e.g. spi_bus, i2c_bus |
| A peripheral register driver (Layer 1) | hal::bus::PhysicalBus |
the esp32-* driver crates |
Start with Writing a Driver, which walks one example per layer.
Portable libraries
Section titled “Portable libraries”The lib/ crates —
led-strip, led-matrix, crypto, wpa, kvstore, heap — hold device-class
contracts and pure code with no hardware. See Libraries.
What’s not here
Section titled “What’s not here”The reference covers the crates that build on the host: the api surface, the
driver/bus traits, the logical drivers, and lib/*. Architecture- and
chip-specific internals (arch/*, soc/*) are documented in their own source
and in the Hardware pages, not in this reference.