User Guide Getting Started

Getting Started

This guide walks you through building your first RTIC application using an existing distribution.

Prerequisites

• A working Rust toolchain (the latest stable release is recommended).
• The target toolchain for your chosen distribution. For example, for the RP2040 examples you need:

  rustup target add thumbv6m-none-eabi

  For cortex-m-rtic, add the target matching your device:

  # armv7-m and above (STM32F1, STM32F4, …)
  rustup target add thumbv7m-none-eabi
  # armv6-m (STM32F0, …)
  rustup target add thumbv6m-none-eabi

Choose a distribution

This repository ships several reference distributions. Pick one that matches your hardware or simulator:

Distribution	Target	Good for
cortex-m-rtic	Single-core Cortex-M (armv6-m / armv7-m)	Generic Cortex-M targets; runs under QEMU, supports BASEPRI and interrupt source-masking locking
rp2040-rtic	Raspberry Pi Pico / RP2040	Getting started, single-core and multicore examples
stm32-renode-rtic	Renode-simulated STM32F1C3-like	Multicore simulation
rtic-hippo	RISC-V Hippomenes	Single-core RISC-V experiments
atalanta-rtic	RISC-V Atalanta	Single-core RISC-V experiments

Try cortex-m-rtic under QEMU (no hardware required)

The cortex-m-rtic distribution ships a QEMU-runnable playground.

Install QEMU and the two Cortex-M targets:

# Linux (Debian/Ubuntu); macOS: `brew install qemu`
sudo apt-get install -y qemu-system-arm
rustup target add thumbv7m-none-eabi thumbv6m-none-eabi

Then, from the repository root:

make qemu          # runs both locking codepaths; fails if either misbehaves
make qemu-armv7m   # BASEPRI locking only
make qemu-armv6m   # interrupt source masking only

The examples are located in distributions/cortex-m-rtic/example-apps. You modify them, rebuild and run on qemu:

cd distributions/cortex-m-rtic/example-apps/armv7m-app && cargo run --example hello_rtic
cd distributions/cortex-m-rtic/example-apps/armv6m-app && cargo run --example hello_rtic

Expected output (each example):

tick 1: counter = 1
tick 2: counter = 2
tick 3: counter = 3
tick 4: counter = 4
SUCCESS: 4 spawns completed under RTIC locking

Create your own application

1. Create a new Rust binary crate that depends on one of the distributions, e.g.:

   [dependencies]
   xxx-rtic = { path = "path/or/version/to/distributions/xxx-rtic" }

2. Write an RTIC application using the attributes described in the Syntax Reference.
3. Build and flash/run as appropriate for your target.

Next steps

• Read the Syntax Reference to learn the supported attributes.
• Check the Supported Distributions page for feature flags and target details.