## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

RTIC

# Real-Time Interrupt-driven Concurrency

A concurrency framework for building real-time systems

# Preface

This book contains user level documentation for the Real-Time Interrupt-driven Concurrency (RTIC) framework. The API reference is available here.

Formerly known as Real-Time For the Masses.

This is the documentation of v1.0.x of RTIC; for the documentation of version

- v0.5.x go here.
- v0.4.x go here.

## Is RTIC an RTOS?

A common question is whether RTIC is an RTOS or not, and depending on your background the answer may vary. From RTIC's developers point of view; RTIC is a hardware accelerated RTOS that utilizes the NVIC in Cortex-M MCUs to perform scheduling, rather than the more classical software kernel.

Another common view from the community is that RTIC is a concurrency framework as there is no software kernel and that it relies on external HALs.

## Features

- Tasks as the unit of concurrency 1. Tasks can be event triggered (fired in response to asynchronous stimuli) or spawned by the application on demand.

- Message passing between tasks. Specifically, messages can be passed to software tasks at spawn time.

- A timer queue 2. Software tasks can be scheduled to run at some time in the future. This feature can be used to implement periodic tasks.

- Support for prioritization of tasks and, thus, preemptive multitasking.

- Efficient and data race free memory sharing through fine grained priority based critical sections 1.

- Deadlock free execution guaranteed at compile time. This is a stronger guarantee than what's provided by the standard `Mutex` abstraction.

- Minimal scheduling overhead. The task scheduler has minimal software footprint; the hardware does the bulk of 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-M devices are fully supported.

- This task model is amenable to known WCET (Worst Case Execution Time) analysis and scheduling analysis techniques.

### Crate `cortex-m` 0.6 vs 0.7 in RTIC 0.5.x

The crate `cortex-m` 0.7 started using trait `InterruptNumber` for interrupts instead of `Nr` from `bare-metal`. In order to preserve backwards compatibility, RTIC 0.5.x will keep using `cortex-m` 0.6 by default. `cortex-m` 0.7 can be enabled using the feature `cortex-m-7` and disabling default features:

    cortex-m-rtic = { version = "0.5.8", default-features = false, features = ["cortex-m-7"] }

RTIC 1.0.0 already uses `cortex-m` 0.7 by default.

## User documentation

Documentation for the development version.

## API reference

## Community provided examples repo

## Chat

Join us and talk about RTIC in the Matrix room.

Weekly meeting notes can be found over at HackMD

## Contributing

New features and big changes should go through the RFC process in the dedicated RFC repository.

## Running tests locally

To check all `Run-pass tests` locally on your `thumbv6m-none-eabi` or `thumbv7m-none-eabi` target device, run

    $ cargo xtask --target <your target>
    #                       ˆˆˆˆˆˆˆˆˆˆˆˆ
    #                   e.g. thumbv7m-none-eabi

## Acknowledgments

This crate is based on the Real-Time For the Masses language created by the Embedded Systems group at Luleå University of Technology, led by Prof. Per Lindgren.

## References

## License

All source code (including code snippets) is licensed under either of

- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

The written prose contained within the book is licensed under the terms of the Creative Commons CC-BY-SA v4.0 license (LICENSE-CC-BY-SA or https://creativecommons.org/licenses/by-sa/4.0/legalcode).

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

1. Eriksson, J., Häggström, F., Aittamaa, S., Kruglyak, A., & Lindgren, P. (2013, June). Real-time for the masses, step 1: Programming API and static priority SRP kernel primitives. In Industrial Embedded Systems (SIES), 2013 8th IEEE International Symposium on (pp. 110-113). IEEE. ↩ ↩2

2. Lindgren, P., Fresk, E., Lindner, M., Lindner, A., Pereira, D., & Pinho, L. M. (2016). Abstract timers and their implementation onto the arm cortex-m family of mcus. ACM SIGBED Review, 13(1), 48-53. ↩