Skip to content

User Guide

Jump to bottom
Zakaria Madaoui edited this page Aug 18, 2026 · 9 revisions

User Guide

This guide is for application developers who want to write real-time Rust applications using an existing RTICX distribution.

What is RTICX?

RTICX is a Rust framework for building event-driven, real-time embedded applications. It uses a set of attributes (#[rticx-distro::app], #[task], #[shared], etc.) to generate code that implements the Stack Resource Policy (SRP) for safe resource sharing between tasks and interrupts.

Core concepts

  • Tasks: units of work that can be triggered by interrupts or by other tasks.
  • Shared resources: data protected by the SRP ceiling protocol.
  • Priorities: RTICX assigns ceilings based on task priorities so that higher-priority tasks can preempt safely.
  • Init/PostInit: the startup tasks that run once and return the initial shared resources together with the TaskInits struct holding every task.
  • Idle: the loop that runs when no task is active.
  • Multicore: RTICX supports single-binary multicore (e.g. dual-core RP2040). Tasks are assigned to cores via core = N and communicate through cross-core task spawning. See the Multicore section in the Syntax Reference and the Architecture page for the underlying design.

Should you block in an interrupt?

The classic embedded rule "never block in an interrupt" does not hold as an absolute in RTIC/X, because the framework's scheduling policy is built on interrupts: priorities, preemption and locking are all defined in terms of them. That does not mean the rule should be ignored entirely; the system still needs to be designed with care. What changes is that blocking becomes a per-task decision: whether a task can block safely is determined by the priorities of the tasks and resources around it.

RTICX adds context and state to an interrupt handler. A hardware task keeps its own state across the whole application lifetime and gets safe, worry-free access to shared resources through a priority-backed locking discipline (the SRP ceiling model). This turns a bare interrupt line into a building block that can express quite powerful system designs.

When talking about interrupts in RTICX, two kinds must be distinguished:

  • Interrupts for real hardware events: handled with hardware tasks. A real hardware event needs to be processed in a timely manner, with an urgency that is relative to the other events of the system. As with the general rule for interrupts, these tasks usually should not block. But if priorities are chosen correctly, some of them can block while others do not: a task that blocks only stalls work at or below its own priority (and the resource ceilings it holds).
  • Unused interrupt lines (e.g. software-triggerable lines): these can be repurposed as dispatchers/executors for software and async tasks. This is what makes deferring work and running rich async/await code possible, all under the same scheduling and fearless-concurrency guarantees inherited from the SRP model as hardware tasks enjoy.

This combination is the power of RTICX: rich, real-time applications free of concurrency worries, and if priorities are chosen correctly, performance and overhead that will easily outperform any round-robin scheduler. All of it is written in a modern, memory-safe language (Rust), and the proc macro generates all of the interrupt logic and configuration needed, beating a handwritten bare-metal application on correctness and productivity alike. RTICX is therefore an all-purpose concurrency framework, suited to low-level bare-metal and hard real-time applications as well as higher-level application code.

Next steps

Clone this wiki locally