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 code from the kernel
• Tested: Thanks to portability, we can unit test the kernel on the host
• Use Rust language features to ensure memory and thread safety at compile time

User Guide

Architecture

The rucos crate is a collection of no_std data structures. It has no platform specific or unsafe code. The Kernel struct is designed to be used as a singleton in an embedded application.

The rucos crate would be difficult to use alone, as the embedded application needs a mutable reference to the Kernel singleton in every task. This is where the "port specific" crate comes in (e.g. rucos-cortex-m). The port specific crate creates wrappers around the Kernel APIs, dealing with platform specific details (e.g. stack initialization) and handling the Kernel singleton in a safe way (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;

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

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

rucos::init(&mut idle_stack, None);
rucos::create(0, 10, &mut my_task_stack, my_task, None);
rucos::start(...);

Developer Guide

Dependencies

• To build rucos, only the Rust toolchain is required
• To build rucos-cortex-m, the nightly Rust toolchain is required
• To run the rucos-cortex-m examples, probe-rs is required
• To debug the 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 note that the example code should be easily portable to other devices.

Ideally cargo test would be used to automate target testing via defmt-test, but the nature of RuCOS applications is that they do not terminate and or follow a serial sequence of steps we can assert on. Instead examples are used for testing and each one must be run manually:

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