User Guide Getting Started

Getting Started

This guide walks you through building your first RTICX application using an existing distribution. RTICX supports single-binary multicore (e.g. dual-core RP2040); see the Multicore section in the Syntax Reference for multicore attributes.

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 rticx-cortex-m, 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: Supported Distributions

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

The rticx-cortex-m 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/rticx-cortex-m/examples-apps. You modify them, rebuild and run on qemu:

cd distributions/rticx-cortex-m/examples-apps && cargo run --target thumbv7m-none-eabi --example hello_rtic
cd distributions/rticx-cortex-m/examples-apps && cargo run --target thumbv6m-none-eabi --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

Create your own application

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

   [dependencies]
   rticx-distro = { path = "path/or/version/to/rticx-distro" }

2. Write an RTICX 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.
• Use Debugging and Inspection (cargo rticx-expand) to step through the generated code in GDB.