User Guide Syntax

Syntax Reference

This page describes the RTICX attributes currently supported by the core pass (rticx-core) and the software-tasks pass (rticx-sw-pass). Other officially supported passes may add their own attributes; those will be documented as they are added.

Application-level attributes: #[app(...)]

The #[<distro>::app(...)] attribute is placed on the module that contains your application.

Common arguments

#[<distro>::app(device = rp2040_hal::pac, dispatchers = [DMA_IRQ_0])]
mod my_app { ... }

• device = path — path to the PAC (Peripheral Access Crate) for the target.
• cores = N — number of cores (default is 1).
• dispatchers = [...] — single-core list of interrupt dispatchers for software tasks.
• dispatchers = [[...], [...]] — per-core dispatcher lists for software tasks on multicore targets.

Shared resources: #[shared]

#[shared]
struct SharedResources {
    alarm: Alarm0,
    led: LedOutPin,
}

Fields of SharedResources are accessed inside tasks via self.shared().name and locked with .lock(|resource| { ... }).

Init: #[init]

#[init]
fn system_init() -> SharedResources {
    // setup code
    SharedResources { alarm, led }
}

The init function runs once at startup and returns the initial shared resources. On multicore targets, use #[init(core = N)].

Idle: #[idle]

#[idle]
struct MyIdleTask;
impl RticIdleTask for MyIdleTask {
    fn init() -> Self { Self }
    fn exec(&mut self) -> ! {
        loop { /* low-power or background work */ }
    }
}

On multicore targets, use #[idle(core = N)].

Hardware tasks: #[task(...)]

#[task(binds = TIMER_IRQ_0, priority = 3, shared = [alarm, led])]
struct MyTask;
impl RticTask for MyTask {
    fn init() -> Self { Self }
    fn exec(&mut self) { /* handler code */ }
}

• binds = IRQ — interrupt line that triggers this task.
• priority = N — task priority. Higher values preempt lower values.
• shared = [...] — list of shared resource fields this task accesses.
• core = N — on multicore targets, the core on which the interrupt lives.

Software tasks: #[sw_task(...)]

Software tasks are provided by the rticx-sw-pass compilation pass. They are triggered by other tasks via message queues instead of direct interrupts.

#[sw_task(priority = 2, shared = [led], spawn_by = 0, core = 0)]
struct MySwTask;
impl RticSwTask for MySwTask {
    type SpawnInput = u16;
    fn init() -> Self { Self }
    fn exec(&mut self, input: u16) { /* handler code */ }
}

• priority = N — dispatcher hardware task priority.
• shared = [...] — shared resources this task accesses.
• core = N — the core on which this task executes.
• spawn_by = N — the only core allowed to spawn this task. If omitted, any core may spawn it.

Spawning software tasks

• MySwTask::spawn(value) — spawn from the same core.
• MySwTask::spawn_from(core, value) — spawn from another core, when allowed.

Resource locking

Inside a task, shared resources are accessed through the shared proxy and locked to obtain a mutable reference:

self.shared().led.lock(|led| {
    let _ = led.set_high();
});

The lock implementation is target-specific and generated by the distribution backend.

Other officially supported passes

The following passes are available but may add their own attributes. Detailed syntax for each will be added as the documentation expands:

• rticx-deadline-pass — converts deadline = D attributes into RTICX priorities.
• rticx-auto-assign — automatically assigns core = N based on shared resource usage.
• Future async pass — planned for asynchronous task support.

See the Supported Distributions page to know which passes are enabled by each distribution.

Next steps

• Supported Distributions — feature flags per distribution.
• Distributor Guide — how these attributes are processed internally.