Software tasks

In addition to hardware tasks, which are invoked by the hardware in response to hardware events, RTIC also supports software tasks which can be spawned by the application from any execution context.

Software tasks can also be assigned priorities and, under the hood, are dispatched from interrupt handlers. RTIC requires that free interrupts are declared in an extern block when using software tasks; some of these free interrupts will be used to dispatch the software tasks. An advantage of software tasks over hardware tasks is that many tasks can be mapped to a single interrupt handler.

Software tasks are also declared using the task attribute but the binds argument must be omitted. To be able to spawn a software task from a context the name of the task must appear in the spawn argument of the context attribute (init, idle, task, etc.).

The example below showcases three software tasks that run at 2 different priorities. The three software tasks are mapped to 2 interrupts handlers.

#![allow(unused)]
fn main() {
//! examples/task.rs

#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]

use cortex_m_semihosting::{debug, hprintln};
use panic_semihosting as _;

#[rtic::app(device = lm3s6965)]
const APP: () = {
    #[init(spawn = [foo])]
    fn init(c: init::Context) {
        c.spawn.foo().unwrap();
    }

    #[task(spawn = [bar, baz])]
    fn foo(c: foo::Context) {
        hprintln!("foo - start").unwrap();

        // spawns `bar` onto the task scheduler
        // `foo` and `bar` have the same priority so `bar` will not run until
        // after `foo` terminates
        c.spawn.bar().unwrap();

        hprintln!("foo - middle").unwrap();

        // spawns `baz` onto the task scheduler
        // `baz` has higher priority than `foo` so it immediately preempts `foo`
        c.spawn.baz().unwrap();

        hprintln!("foo - end").unwrap();
    }

    #[task]
    fn bar(_: bar::Context) {
        hprintln!("bar").unwrap();

        debug::exit(debug::EXIT_SUCCESS);
    }

    #[task(priority = 2)]
    fn baz(_: baz::Context) {
        hprintln!("baz").unwrap();
    }

    // RTIC requires that unused interrupts are declared in an extern block when
    // using software tasks; these free interrupts will be used to dispatch the
    // software tasks.
    extern "C" {
        fn SSI0();
        fn QEI0();
    }
};
}

$ cargo run --example task
foo - start
foo - middle
baz
foo - end
bar

Message passing

The other advantage of software tasks is that messages can be passed to these tasks when spawning them. The type of the message payload must be specified in the signature of the task handler.

The example below showcases three tasks, two of them expect a message.

#![allow(unused)]
fn main() {
//! examples/message.rs

#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]

use cortex_m_semihosting::{debug, hprintln};
use panic_semihosting as _;

#[rtic::app(device = lm3s6965)]
const APP: () = {
    #[init(spawn = [foo])]
    fn init(c: init::Context) {
        c.spawn.foo(/* no message */).unwrap();
    }

    #[task(spawn = [bar])]
    fn foo(c: foo::Context) {
        static mut COUNT: u32 = 0;

        hprintln!("foo").unwrap();

        c.spawn.bar(*COUNT).unwrap();
        *COUNT += 1;
    }

    #[task(spawn = [baz])]
    fn bar(c: bar::Context, x: u32) {
        hprintln!("bar({})", x).unwrap();

        c.spawn.baz(x + 1, x + 2).unwrap();
    }

    #[task(spawn = [foo])]
    fn baz(c: baz::Context, x: u32, y: u32) {
        hprintln!("baz({}, {})", x, y).unwrap();

        if x + y > 4 {
            debug::exit(debug::EXIT_SUCCESS);
        }

        c.spawn.foo().unwrap();
    }

    // RTIC requires that unused interrupts are declared in an extern block when
    // using software tasks; these free interrupts will be used to dispatch the
    // software tasks.
    extern "C" {
        fn SSI0();
    }
};
}

$ cargo run --example message
foo
bar(0)
baz(1, 2)
foo
bar(1)
baz(2, 3)

Capacity

RTIC does not perform any form of heap-based memory allocation. The memory required to store messages is statically reserved. By default the framework minimizes the memory footprint of the application so each task has a message "capacity" of 1: meaning that at most one message can be posted to the task before it gets a chance to run. This default can be overridden for each task using the capacity argument. This argument takes a positive integer that indicates how many messages the task message buffer can hold.

The example below sets the capacity of the software task foo to 4. If the capacity is not specified then the second spawn.foo call in UART0 would fail (panic).

#![allow(unused)]
fn main() {
//! examples/capacity.rs

#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]

use cortex_m_semihosting::{debug, hprintln};
use lm3s6965::Interrupt;
use panic_semihosting as _;

#[rtic::app(device = lm3s6965)]
const APP: () = {
    #[init]
    fn init(_: init::Context) {
        rtic::pend(Interrupt::UART0);
    }

    #[task(binds = UART0, spawn = [foo, bar])]
    fn uart0(c: uart0::Context) {
        c.spawn.foo(0).unwrap();
        c.spawn.foo(1).unwrap();
        c.spawn.foo(2).unwrap();
        c.spawn.foo(3).unwrap();

        c.spawn.bar().unwrap();
    }

    #[task(capacity = 4)]
    fn foo(_: foo::Context, x: u32) {
        hprintln!("foo({})", x).unwrap();
    }

    #[task]
    fn bar(_: bar::Context) {
        hprintln!("bar").unwrap();

        debug::exit(debug::EXIT_SUCCESS);
    }

    // RTIC requires that unused interrupts are declared in an extern block when
    // using software tasks; these free interrupts will be used to dispatch the
    // software tasks.
    extern "C" {
        fn SSI0();
    }
};
}

$ cargo run --example capacity
foo(0)
foo(1)
foo(2)
foo(3)
bar

Error handling

The spawn API returns the Err variant when there's no space to send the message. In most scenarios spawning errors are handled in one of two ways:

Panicking, using unwrap, expect, etc. This approach is used to catch the programmer error (i.e. bug) of selecting a capacity that was too small. When this panic is encountered during testing choosing a bigger capacity and recompiling the program may fix the issue but sometimes it's necessary to dig deeper and perform a timing analysis of the application to check if the platform can deal with peak payload or if the processor needs to be replaced with a faster one.
Ignoring the result. In soft real-time and non real-time applications it may be OK to occasionally lose data or fail to respond to some events during event bursts. In those scenarios silently letting a spawn call fail may be acceptable.

It should be noted that retrying a spawn call is usually the wrong approach as this operation will likely never succeed in practice. Because there are only context switches towards higher priority tasks retrying the spawn call of a lower priority task will never let the scheduler dispatch said task meaning that its message buffer will never be emptied. This situation is depicted in the following snippet:

#![allow(unused)]
fn main() {
#[rtic::app(..)]
const APP: () = {
    #[init(spawn = [foo, bar])]
    fn init(cx: init::Context) {
        cx.spawn.foo().unwrap();
        cx.spawn.bar().unwrap();
    }

    #[task(priority = 2, spawn = [bar])]
    fn foo(cx: foo::Context) {
        // ..

        // the program will get stuck here
        while cx.spawn.bar(payload).is_err() {
            // retry the spawn call if it failed
        }
    }

    #[task(priority = 1)]
    fn bar(cx: bar::Context, payload: i32) {
        // ..
    }
};
}

Real-Time Interrupt-driven Concurrency

Software tasks

Message passing

Capacity

Error handling