Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
R3-OS (or simply R3) is an experimental static RTOS that utilizes Rust's compile-time function evaluation mechanism for static configuration (creation of kernel objects and memory allocation) and const traits to decouple kernel interfaces from implementation.
- All kernel objects are defined statically for faster boot times, compile-time checking, predictable execution, reduced RAM consumption, no runtime allocation failures, and extra security.
- A kernel and its configurator don't require an external build tool or a specialized procedural macro, maintaining transparency and inter-crate composability.
- The kernel API is not tied to any specific kernel implementations. Kernels are provided as separate crates, one of which an application chooses and instantiates using the trait system.
- Leverages Rust's type safety for access control of kernel objects. Safe code can't access an object that it doesn't own.
R3 API
-
Tasks are the standard way to spawn application threads. They are kernel objects encapsulating the associated threads' execution states and can be activated by application code or automatically at boot time. Tasks have dynamic priorities and can block to relinquish the processor for lower-priority tasks.
-
R3 provides a unified interface to control interrupt lines and register interrupt handlers. Some kernels (e.g., the Arm M-Profile port of the original kernel) support unmanaged interrupt lines, which aren't masked when the kernel is handling a system call and thus provide superior real-time performance.
-
R3 supports common synchronization primitives such as mutexes, semaphores, and event groups. The mutexes can use the priority ceiling protocol to avoid unbounded priority inversion and mutual deadlock. Tasks can park themselves.
-
The kernel timing mechanism drives software timers and a system-global clock with microsecond precision. The system clock can be rewound or fast-forwarded for drift compensation.
-
Bindings are a statically-defined storage with runtime initialization and configuration-time borrow checking. They can be bound to tasks and other objects to provide safe mutable access.
-
Procedural kernel configuration facilitates componentization. The utility library includes safe container types such as
Mutex
andRecursiveMutex
, which are built upon low-level synchronization primitives.
The Kernel
The R3 original kernel is provided as a separate package r3_kernel
.
-
Traditional uniprocessor tickless real-time kernel with preemptive scheduling
-
Implements a software-based scheduler supporting a customizable number of task priorities (up to 2¹⁵ levels on a 32-bit target, though the implementation is heavily optimized for a smaller number of priorities) and an unlimited number of tasks.
-
Provides a scalable kernel timing mechanism with a logarithmic time complexity. This implementation is robust against a large interrupt processing delay.
-
Supports Arm M-Profile (all versions shipped so far), Armv7-A (no FPU), RISC-V as well as the simulator port that runs on a host system.
Example
// ----------------------------------------------------------------
// Instantiate the Armv7-M port
use r3_port_arm_m as port;
type System = System;
use_port!
Explore the examples
directory for example projects.
Prerequisites
You need a Nightly Rust compiler. This project is heavily reliant on unstable features, so it might or might not work with a newer compiler version. See the file rust-toolchain
to find out which compiler version this project is currently tested with.
You also need to install Rust's cross-compilation support for your target architecture. If it's not installed, you will see a compile error like this:
error[E0463]: can't find crate for `core`
|
= note: the `thumbv7m-none-eabi` target may not be installed
In this case, you need to run rustup target add thumbv7m-none-eabi
.