FreeRTOS-in-Rust

FreeRTOS-in-Rust is a monolithic, no_std, pure-Rust translation of the FreeRTOS kernel. It links no FreeRTOS C code; only the small amount of architecture assembly needed for context switching remains non-Rust.

The goal of this project is to provide a "simple", but fully functional, RTOS in Rust for embedded systems. Embedded developers should be able to follow standard FreeRTOS design patterns with 100% of the supported feature surface available, while also gaining Rust syntax sugar.

The 0.3.x line combines two interfaces in one crate:

• freertos_in_rust::kernel is the close, C-shaped translation. It preserves FreeRTOS names, handles, storage rules, and control flow, and marks contracts that Rust cannot verify as unsafe.
• freertos_in_rust::sync is the safe Rust veneer. It adds owned handles, typed queues, stable static-storage borrows, checked parameters, and an explicit task-context capability without redesigning the kernel.

See RUST_WRAPPER.md for details on the veneer API and its safety model. The crate remains under active development, so 0.3.x APIs may still evolve.

Translation baseline

This is a source translation and derivative of the MIT-licensed FreeRTOS kernel, not a wrapper or a clean-room reimplementation. The translation target is pinned to upstream commit 3ace38969bd05558918f815ae75528cb656c64b0 (git describe: V10.4.3-744-g3ace38969). Upstream notices and amendment comments are retained in the Rust sources. The reference FreeRTOS-Kernel/ tree is excluded from crate packages and is not compiled.

Version 0.3.x is single-core. Separate SMP work remains experimental on the smp branch. Its early boot scaffolding has run in QEMU, but it has not passed the two-core scheduler gate and is not part of the 0.3.0 crate API or the qualification below.

Feature support

The supported single-core FreeRTOS feature surface is implemented. The concise table below is backed by the symbol-by-symbol source audit in PARITY.md; the later qualification table distinguishes compilation coverage from code actually exercised in QEMU or on hardware.

Legend: ✅ implemented · ⚠️ partial/experimental · ➖ deliberately out of scope

Configure a target

The default feature is only port-dummy, a compile-only scaffold that cannot start a scheduler. Every production dependency must disable defaults and select exactly one hardware port:

[dependencies]
freertos-in-rust = { version = "0.3", default-features = false, features = [
    "port-cortex-m0",
    "heap-4",
    "user-config",
    "task-delete",
    "task-suspend",
    "use-mutexes",
    "timers",
    "stream-buffers",
] }

The port features are:

• port-cortex-m0, port-cortex-m3, port-cortex-m4f, port-cortex-m7
• port-riscv32
• port-cortex-a9, port-cortex-a53

Port features are mutually exclusive and automatically select both the native integer width and tick width. Applications should not add arch-* or tick-* features themselves.

All 32-bit ports use u32 TickType_t. Cortex-A53 uses 64-bit architecture types and u64 TickType_t. This policy avoids the unsupported 16-bit tick combinations and lets event-group reserved bits and timer arithmetic follow the selected tick type consistently.

Optional kernel capabilities map the corresponding FreeRTOS configuration switches. The available names are defined in Cargo.toml, including task-delete, task-suspend, abort-delay, task-priority-set, use-mutexes, timers, stream-buffers, queue-sets, queue-registry, pend-function-call, thread-local-storage, tickless-idle, and generate-run-time-stats. all-kernel-features is a test aggregate; it does not select a port, width, allocator, or SMP mode.

Hardware configuration

Enable user-config for production hardware and define its clock symbols in the final application:

#[no_mangle]
pub static FREERTOS_CONFIG_CPU_CLOCK_HZ: u32 = 32_000_000;

// Required as well for port-riscv32.
#[no_mangle]
pub static FREERTOS_CONFIG_MTIME_HZ: u32 = 10_000_000;

Without user-config, the crate uses the repository's test-oriented defaults: 80 MHz for the CPU clock and, on RV32, 32.768 kHz for MTIME. Those values must not be assumed correct for a board. Other numeric FreeRTOS configuration values currently live in src/config.rs, including a 1 kHz kernel tick.

Raw kernel and safe veneer

The raw layer is useful for direct FreeRTOS ports and for comparing behavior with the C kernel:

use freertos_in_rust::kernel::tasks::{vTaskDelay, xTaskGetTickCount};

let before = xTaskGetTickCount();
// SAFETY: this runs in a live task with the scheduler running and unsuspended.
unsafe { vTaskDelay(10) };

Safe task-only operations require &TaskContext. Constructing the capability is the explicit assertion that execution is in a task, or in exclusive startup before interrupts and the scheduler can race it:

use freertos_in_rust::sync::{Queue, TaskContext};

// SAFETY: single-threaded startup; kernel interrupts are still masked.
let context = unsafe { TaskContext::assume() };
let queue = Queue::<u32>::new(&context, 8).expect("queue allocation failed");
assert!(queue.send(&context, &42));

freertos_in_rust::start_scheduler(context)

Create a fresh TaskContext at each task entry. It is neither Send nor Sync. ISR APIs remain a separate, mostly unsafe boundary because Rust types cannot prove interrupt priority, wake flags, or platform dispatch contracts.

Allocation policy

Select at most one allocator feature:

For heap-4 or heap-5, the provided adapter can back Rust allocation:

#[global_allocator]
static ALLOCATOR: freertos_in_rust::memory::FreeRtosAllocator =
    freertos_in_rust::memory::FreeRtosAllocator;

Static veneer constructors borrow their stack, data, and control storage for the complete object lifetime. Do not form references to uninitialized control blocks; initialize them with their const fn new() constructors.

Port qualification

“Build” and “QEMU” below are deliberately separate. A target check proves that a configuration cross-compiles; a bounded QEMU guest additionally exercises the stated runtime behavior. Neither is a substitute for qualification on a particular board, clock tree, interrupt controller, and compiler profile.

The recovered LP-MSPM0G5187 application is preserved under hardware-tests/mspm0g5187 and is cross-compiled in CI. The 0.3 repair was programmed, byte-for-byte verified, and run through the board's onboard XDS110 with TI UniFlash 9.4. Its four-task RGB pattern exercised dynamic allocation, queue blocking, timed delays, and an event-group rendezvous on the MSPM0G5187.

Current QEMU qualification covers tickless idle on every registered single-core port. Each Cortex-M tickless guest suppresses 200 ticks, wakes at tick 180, and observes two SysTick interrupts across the test.

Test driver

Use the repository test driver instead of assembling ad-hoc QEMU command lines:

# Deterministic host tests in debug and release modes.
cargo run --manifest-path xtask/Cargo.toml -- test host

# Required feature/allocator/port matrix, docs, and expected-failure checks.
cargo run --manifest-path xtask/Cargo.toml -- check-features

# One bounded guest.
cargo run --manifest-path xtask/Cargo.toml -- \
  qemu-test --arch cortex-a53 --suite tickless

# The registered suites for one architecture.
cargo run --manifest-path xtask/Cargo.toml -- \
  qemu-test --arch cortex-a53 --suite all

# The smoke suite on every registered single-core architecture.
cargo run --manifest-path xtask/Cargo.toml -- \
  qemu-test --arch all --suite smoke

Each firmware run has a 25-second default timeout and writes a diagnostic log under target/xtask/qemu-logs/. Override the bound with FREERUSTOS_QEMU_TIMEOUT_SECS when necessary.

Install the Rust targets used by the ports before running the complete matrix:

rustup target add \
  thumbv6m-none-eabi \
  thumbv7m-none-eabi \
  thumbv7em-none-eabihf \
  riscv32imac-unknown-none-elf \
  armv7a-none-eabi \
  aarch64-unknown-none

The QEMU matrix requires qemu-system-arm, qemu-system-aarch64, and qemu-system-riscv32. The demo/ applications remain useful for manual inspection, but passing a demo build is not counted as runtime qualification in the table above.

Repository layout

src/
├── kernel/     # C-shaped translations of tasks, queues, lists, timers, etc.
├── sync/       # Checked Rust veneer and ownership/context types
├── port/       # Cortex-M, Cortex-A, RV32, test, and dummy ports
├── memory/     # Static stubs, heap_4, heap_5, and global-allocator bridge
├── config.rs   # FreeRTOSConfig.h equivalent
├── types.rs    # Port-selected FreeRTOS scalar and handle types
└── lib.rs
tests/qemu/     # Bounded bare-metal QEMU firmware suites
xtask/          # Host, feature-matrix, and QEMU test driver

License

MIT, matching the upstream FreeRTOS kernel. See LICENSE.