Crate r3

source ·
Expand description

R3 Real-Time Operating System

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.

See r3_core’s crate-level documentation for a general description of kernel features and concepts used in R3.

Package Ecosystem

The R3 ecosystem revolves around the r3_core package. Applications and libraries, including this r3 package, are built on top of r3_core’s application-side API. This is in contrast with the kernel-side API, which intentionally has a weaker stability guarantee for continuous optimization and improvement.

The following diagram shows a possible package configuration of an R3 application.

Application code Application Library Library ...
Façade API r3 1.0¹ r3 2.0 ...
Core API definition r3_core 1.0
Kernel (API implementor)² r3_kernel
Ports² r3_port_std || _arm || _arm_m || _riscv

¹ Version numbers shown here are illustrative.

² Application code chooses kernel and port implementations.

Notes: Many items of this crate are re-exported from r3_core, and consequently their example code refers to them through paths starting with r3_core::. You can replace them with r3:: in your application code.

Stability

This package is versioned in accordance with the Semantic Versioning 2.0.0. Requiring a newer version of r3_core that breaks the application-side API stability guarantee is considered a breaking change.

Increasing the minimum supported Rust version (MSRV) is not considered a breaking change.

Cargo Features

This package also exposes the Cargo features of r3_core. Please refer to its documentation.

Modules

Changelog
A heterogeneous collection to store property values.
Bindings (Bind), a static storage with runtime initialization and configuration-time borrow checking.
Type-safe hunks
The kernel interface.
The prelude module.
syncsync
Safe synchronization primitives.
Temporal quantification for R3-OS.
Utilities. This module re-exports items from r3_core::utils that are subject to the application-side API stability guarantee.