Merge branch '💥-traitize' into 🦆

Author: yvt

.github/workflows/ci.yml

@@ -127,7 +127,7 @@ jobs:
         run: |
           features='${{ matrix.features }}'
           if [ "$features" ]; then
-            features="--features r3_test_suite/$features"
+            features="--features r3_test_suite/$features --features r3_kernel/$features"
           fi
           echo "features_param=$features" >> $GITHUB_ENV
 

Cargo.lock

@@ -9,6 +9,7 @@ members = [
     "examples/smp_rp_pico",
     "src/arm_semihosting",
     "src/r3",
+    "src/r3_kernel",
     "src/r3_port_arm",
     "src/r3_port_arm_m",
     "src/r3_port_arm_m_test_driver",

Cargo.toml

@@ -10,30 +10,36 @@
 <a href="https://repl.it/@yvt/R3-Kernel-Hosted-Port#main.rs"><b>Try it on Repl.it</b></a>
 </p>
 
-R3 is a proof-of-concept of a static RTOS that utilizes Rust's compile-time function evaluation mechanism for static configuration (creation of kernel objects and memory allocation).
+R3 is a proof-of-concept of a 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.
-- The kernel and its configurator **don't require an external build tool or a specialized procedural macro**, maintaining transparency.
-- The kernel is split into a target-independent portion and a target-specific portion. The target-specific portion (called *a port*) is provided as a separate crate. An application **combines them using the trait system**.
+- 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 a specific kernel implementation**. 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.
 
-## Features
-
-- Traditional uniprocessor tickless real-time kernel with preemptive scheduling
+## R3 API
 
 - **Tasks** are kernel objects associated with application threads and encapsulate their execution states. Tasks can be activated by application code or automatically at boot time. Tasks are assigned priorities (up to 2¹⁵ levels on a 32-bit target, though the implementation is heavily optimized for a smaller number of priorities), which can be changed at runtime. A task can enable **Priority Boost** to temporarily raise its priority to higher than any other tasks. The number of tasks is only limited by memory available.
 
-- This kernel provides a unified interface to control **interrupt lines** and register **interrupt handlers**. In addition, the Arm M-Profile port supports **unmanaged interrupt lines**, which aren't masked when the kernel is handling a system call.
+- R3 provides a unified interface to control **interrupt lines** and register **interrupt handlers**. In addition, the Arm M-Profile port supports **unmanaged interrupt lines**, which aren't masked when the kernel is handling a system call.
 
-- This kernel 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.
+- 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. The timing algorithm has a logarithmic time complexity and is therefore scalable. The implementation is robust against a large interrupt processing delay.
 
 - The utility library includes safe container types such as **`Mutex`** and **`RecursiveMutex`**, which are built upon low-level synchronization primitives.
 
+[the priority ceiling protocol]: https://en.wikipedia.org/wiki/Priority_ceiling_protocol
+
+## The Kernel
+
+The R3 original kernel is provided as a separate package [`r3_kernel`][].
+
+- Traditional uniprocessor tickless real-time kernel with preemptive scheduling
+
 - 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.
 
-[the priority ceiling protocol]: https://en.wikipedia.org/wiki/Priority_ceiling_protocol
+[`r3_kernel`]: https://crates.io/crates/r3_kernel
 
 ## Example
 
@@ -42,6 +48,7 @@ R3 is a proof-of-concept of a static RTOS that utilizes Rust's compile-time func
 #![feature(const_fn_trait_bound)]
 #![feature(const_mut_refs)]
 #![feature(const_fn_fn_ptr_basics)]
+#![feature(const_trait_impl)]
 #![no_std]
 #![no_main]
 
@@ -50,30 +57,31 @@ R3 is a proof-of-concept of a static RTOS that utilizes Rust's compile-time func
 // Instantiate the Armv7-M port
 use r3_port_arm_m as port;
 
-port::use_port!(unsafe struct System);
-port::use_rt!(unsafe System);
-port::use_systick_tickful!(unsafe impl PortTimer for System);
+type System = r3_kernel::System<SystemTraits>;
+port::use_port!(unsafe struct SystemTraits);
+port::use_rt!(unsafe SystemTraits);
+port::use_systick_tickful!(unsafe impl PortTimer for SystemTraits);
 
-impl port::ThreadingOptions for System {}
+impl port::ThreadingOptions for SystemTraits {}
 
-impl port::SysTickOptions for System {
+impl port::SysTickOptions for SystemTraits {
     // STMF401 default clock configuration
     // SysTick = AHB/8, AHB = HSI (internal 16-MHz RC oscillator)
     const FREQUENCY: u64 = 2_000_000;
 }
 
 // ----------------------------------------------------------------
 
-use r3::kernel::{Task, cfg::CfgBuilder};
+use r3::kernel::Task;
 
 struct Objects {
     task: Task<System>,
 }
 
 // Instantiate the kernel, allocate object IDs
-const COTTAGE: Objects = r3::build!(System, configure_app => Objects);
+const COTTAGE: Objects = r3_kernel::build!(SystemTraits, configure_app => Objects);
 
-const fn configure_app(b: &mut CfgBuilder<System>) -> Objects {
+const fn configure_app(b: &mut r3_kernel::Cfg<SystemTraits>) -> Objects {
     System::configure_systick(b);
 
     Objects {

README.md

@@ -61,17 +61,15 @@ Exceptions:
 
 ### Optional features should be documented properly (CC-DOC-OPT-FEATURES)
 
-All optional features of `r3` must be listed and explained in the crate-level documentation.
+All optional features of `r3` and `r3_kernel` must be listed and explained in the crate-level documentation.
 
 In addition, every public item gated by such features must have [`#[doc(cfg(feature = ...))]` attribute](https://github.com/rust-lang/rust/issues/43781), which displays the required feature on the generated documentation.
 
 ```rust
-/// Get the current [system time].
-///
-/// [system time]: crate#kernel-timing
+/// Get the current system time.
 #[cfg(feature = "system_time")]
 #[doc(cfg(feature = "system_time"))]
-fn time() -> Result<Time, TimeError>;
+pub fn time() -> Result<Time, TimeError>;
 ```
 
 ## Testing
@@ -107,18 +105,18 @@ The runtime overhead caused by unused features should be minimized or eliminated
 
   Example: If no startup hooks are defined, the compiler will simply remove the startup hook initialization loop because it can figure out that `STARTUP_HOOKS` has no elements.
 
-- If the usage of such features can be detected statically in a configuration macro (e.g., `r3::build!`), the macro should control the type choices based on that.
+- If the usage of such features can be detected statically in a configuration macro (e.g., `r3_kernel::build!`), the macro should control the type choices based on that.
 
   Examples:
 
   - `r3_portkit::tickful::TickfulState` (used by timer drivers) chooses the optimal algorithm based on parameters.
 
   - Kernel objects are defined statically and their control blocks are stored in static arrays.
 
-- If the above options are infeasible, expose either a `CfgBuilder` method or a Cargo feature to let downstream crates and application developers specify whether a feature should be compiled in.
+- If the above options are infeasible, expose either a method in `Cfg` or a Cargo feature to let downstream crates and application developers specify whether a feature should be compiled in.
 
   Examples:
 
   - The system clock is controlled by `system_time` feature. The system time is tracked by an internal variable that is updated on timer interrupts, and there's no hope of the compiler optimizing this out. It's impossible for `build!` to detect the usage of `System::time()`. The system clock is not tied to any particular kernel objects, so the software components dependent on the system clock might not have a configuration function. On the other hand, Cargo features are designed exactly for this use case.
 
-  - Application code can change task priorities at runtime. The maximum (lowest) priority affects the size of internal kernel structures, but it's impossible for `build!` to figure that out. Therefore, `CfgBuilder` exposes `num_task_priority_levels` method.
+  - Application code can change task priorities at runtime. The maximum (lowest) priority affects the size of internal kernel structures, but it's impossible for `build!` to figure that out. Therefore, `Cfg` exposes `num_task_priority_levels` method.

doc/guidelines.md

@@ -7,6 +7,7 @@ publish = false
 
 [dependencies]
 r3_port_std = { path = "../../src/r3_port_std" }
-r3 = { path = "../../src/r3", features = ["system_time"] }
+r3_kernel = { path = "../../src/r3_kernel", features = ["system_time"] }
+r3 = { path = "../../src/r3" }
 
 log = { version = "0.4.8" }

examples/basic/Cargo.toml

@@ -1,15 +1,17 @@
 #![feature(const_fn_trait_bound)]
 #![feature(const_fn_fn_ptr_basics)]
 #![feature(const_mut_refs)]
+#![feature(const_trait_impl)]
 #![deny(unsafe_op_in_unsafe_fn)]
 #![deny(unsupported_naked_functions)]
 use r3::{
-    kernel::{cfg::CfgBuilder, Task},
+    kernel::{prelude::*, traits, Task},
     prelude::*,
     sync::Mutex,
 };
 
-r3_port_std::use_port!(unsafe struct System);
+type System = r3_kernel::System<SystemTraits>;
+r3_port_std::use_port!(unsafe struct SystemTraits);
 
 #[derive(Debug)]
 struct Objects {
@@ -18,9 +20,9 @@ struct Objects {
     mutex1: Mutex<System, u32>,
 }
 
-const COTTAGE: Objects = r3::build!(System, configure_app => Objects);
+const COTTAGE: Objects = r3_kernel::build!(SystemTraits, configure_app => Objects);
 
-const fn configure_app(b: &mut CfgBuilder<System>) -> Objects {
+const fn configure_app(b: &mut r3_kernel::Cfg<'_, SystemTraits>) -> Objects {
     b.num_task_priority_levels(4);
 
     let task1 = Task::build()

examples/basic/src/main.rs

@@ -8,7 +8,8 @@ publish = false
 [dependencies]
 r3_support_rza1 = { path = "../../src/r3_support_rza1", features = ["semver-exempt"] }
 r3_port_arm = { path = "../../src/r3_port_arm" }
-r3 = { path = "../../src/r3", features = ["system_time"] }
+r3_kernel = { path = "../../src/r3_kernel", features = ["system_time"] }
+r3 = { path = "../../src/r3" }
 
 rtt-target = { version = "0.2.0" }
 rza1 = { version = "0.2.0", features = ["cpg", "gpio", "scif"] }