lib.rs

//! Real Time For the Masses (RTFM), a framework for building concurrent
//! applications, for ARM Cortex-M microcontrollers
//!
//! This crate is based on [the RTFM framework] created by the Embedded Systems
//! group at [Luleå University of Technology][ltu], led by Prof. Per Lindgren,
//! and uses a simplified version of the Stack Resource Policy as scheduling
//! policy (check the [references] for details).
//!
//! [the RTFM framework]: http://www.rtfm-lang.org/
//! [ltu]: https://www.ltu.se/?l=en
//! [per]: https://www.ltu.se/staff/p/pln-1.11258?l=en
//! [references]: ./index.html#references
//!
//! # Features
//!
//! - **Event triggered tasks** as the unit of concurrency.
//! - Support for prioritization of tasks and, thus, **preemptive
//!   multitasking**.
//! - **Efficient and data race free memory sharing** through fine grained *non
//!   global* critical sections.
//! - **Deadlock free execution** guaranteed at compile time.
//! - **Minimal scheduling overhead** as the scheduler has no "software
//!   component": the hardware does all the scheduling.
//! - **Highly efficient memory usage**: All the tasks share a single call stack
//!   and there's no hard dependency on a dynamic memory allocator.
//! - **All Cortex M3, M4 and M7 devices are fully supported**. M0(+) is
//!   partially supported as the whole API is not available due to missing
//!   hardware features.
//! - The number of task priority levels is configurable at compile time through
//!   the `P2` (4 levels), `P3` (8 levels), etc. Cargo features. The number of
//!   priority levels supported by the hardware is device specific but this
//!   crate defaults to 16 as that's the most common scenario.
//! - This task model is amenable to known WCET (Worst Case Execution Time)
//!   analysis and scheduling analysis techniques. (Though we haven't yet
//!   developed Rust friendly tooling for that.)
//!
//! # Requirements
//!
//! - Tasks must run to completion. That's it, tasks can't contain endless
//!   loops.
//! - Task priorities must remain constant at runtime.
//!
//! # Dependencies
//!
//! - A device crate generated using [`svd2rust`] v0.7.x
//! - A `start` lang time: Vanilla `main` must be supported in binary crates.
//!   You can use the [`cortex-m-rt`] crate to fulfill the requirement
//!
//! [`svd2rust`]: https://docs.rs/svd2rust/0.7.0/svd2rust/
//! [`cortex-m-rt`]: https://docs.rs/cortex-m-rt/0.1.1/cortex_m_rt/
//!
//! # Examples
//!
//! Ordered in increasing level of complexity:
//!
//! - [Zero tasks](./index.html#zero-tasks)
//! - [One task](./index.html#one-task)
//! - [Two "serial" tasks](./index.html#two-serial-tasks)
//! - [Preemptive multitasking](./index.html#preemptive-multitasking)
//! - [Peripherals as resources](./index.html#peripherals-as-resources)
//!
//! ## Zero tasks
//!
//! ``` ignore
//! #![feature(used)]
//! #![no_std]
//!
//! #[macro_use] // for the `hprintln!` macro
//! extern crate cortex_m;
//!