RuCOS

Rust Microcontroller Operating System (RuCOS, pronounced roo-cos) is a real-time kernel for embedded Rust applications (no_std).

Design Goals

• Provide a feature set similar to uC/OS-III or FreeRTOS
• Easy integration: No custom build system or special project structure
• Do not use the async/await pattern
• Do not require memory management or protection hardware
• Do not use experimental language features: Compile on stable
• Portable: Clearly separate platform specific and generic code
• Tested: Thanks to portability, we can unit test the kernel on the host

User Guide

Architecture

The rucos crate is a collection of no_std data structures and a very simple scheduler. It has no platform specific or unsafe code. The rucos crate is not designed for direct use in an application. Instead, a "port specific" crate, like rucos-cortex-m, should be used. The port specific crate handles architecture details like context switching and ensures scheduling is done safely (e.g. disabling interrupts).

Getting Started

Using RuCOS is as simple as adding the port specific crate to Cargo.toml and calling a few APIs.

use rucos_cortex_m as rucos;

// ID = 6, Priority = 0 (highest priority)
static MY_TASK: rucos::Task = rucos::Task::new(6, 0);

let my_task = |_: u32| -> ! {
    loop {
        info!("Hello from Task {}", rucos::get_current_task());
        rucos::sleep(TICK_RATE_HZ);
    }
};

let idle_stack: [u8; IDLE_STACK_SIZE] = [0; IDLE_STACK_SIZE];
let my_task_stack: [u8; TASK_STACK_SIZE] = [0; TASK_STACK_SIZE];

rucos::init(&idle_stack, None);
rucos::create(&MY_TASK, &my_task_stack, my_task, None);
rucos::start(...);

Developer Guide

Dependencies

• To build rucos and rucos-cortex-m, the Rust toolchain is required
• To run rucos-cortex-m examples, probe-rs is required
• To debug rucos-cortex-m examples, the probe-rs VS Code extension is required

Building

./build_all

Testing

rucos

cd kernel && cargo test

rucos-cortex-m

Testing rucos-cortex-m requires targeting a particular device. The STM32F767 microcontroller is used as the test platform, but the example code should be easily portable to other devices.

Ideally cargo test would be used to automate on-device testing with defmt-test, but RuCOS applications do not terminate or have a serial sequence of steps we can assert on. Instead, examples are used for on-device testing. Each one must be run manually:

cd cortex-m && cargo run --example <name>