Real-Time Interrupt-driven Concurrency

Обобщенное программирование (Generics)

Все объекты, предоставляющие ресурысы реализуют трейт rtic::Mutex. Если ресурс не реализует его, можно обернуть его в новый тип rtic::Exclusive, который реализует трейт Mutex. С помощью этого нового типа можно написать обобщенную функцию, которая работает с обобщенным ресурсом и вызывать его из различных задач, чтобы производить однотипные операции над похожим множеством ресурсов. Вот один такой пример:

#![allow(unused)]

fn main() {

//! examples/generics.rs

#![deny(unsafe_code)]

#![deny(warnings)]

#![no_main]

#![no_std]

use cortex_m_semihosting::hprintln;

use panic_semihosting as _;

use rtic::Mutex;

#[rtic::app(device = lm3s6965)]

mod app {

use cortex_m_semihosting::{debug, hprintln};

use lm3s6965::Interrupt;

#[shared]

struct Shared {

shared: u32,

}

#[local]

struct Local {}

#[init]

fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {

rtic::pend(Interrupt::UART0);

rtic::pend(Interrupt::UART1);

(Shared { shared: 0 }, Local {}, init::Monotonics())

}

#[task(binds = UART0, shared = [shared], local = [state: u32 = 0])]

fn uart0(c: uart0::Context) {

hprintln!("UART0(STATE = {})", *c.local.state).unwrap();

// second argument has type `shared::shared`

super::advance(c.local.state, c.shared.shared);

rtic::pend(Interrupt::UART1);

debug::exit(debug::EXIT_SUCCESS);

}

#[task(binds = UART1, priority = 2, shared = [shared], local = [state: u32 = 0])]

fn uart1(c: uart1::Context) {

hprintln!("UART1(STATE = {})", *c.local.state).unwrap();

// second argument has type `shared::shared`

super::advance(c.local.state, c.shared.shared);

}

}

// the second parameter is generic: it can be any type that implements the `Mutex` trait

fn advance(state: &mut u32, mut shared: impl Mutex) {

*state += 1;

let (old, new) = shared.lock(|shared: &mut u32| {

let old = *shared;

*shared += *state;

(old, *shared)

});

hprintln!("shared: {} -> {}", old, new).unwrap();

}

}

$ cargo run --example generics

UART1(STATE = 0)

shared: 0 -> 1

UART0(STATE = 0)

shared: 1 -> 2

UART1(STATE = 1)

shared: 2 -> 4

Условная компиляция

Вы можете использовать условную компиляцию (#[cfg]) на ресурсах (полях структуры #[resources] struct Resources) и задачах (элементах fn). Эффект использования атрибутов #[cfg] в том, что ресурс/ задача будут не доступны в соответствующих структурах Context если условие не выполняется.

В примере ниже выводится сообщение каждый раз, когда вызывается задача foo, но только если программы скомпилирова с профилем dev.

#![allow(unused)]

fn main() {

{{#include ../../../../examples/cfg.rs}}

}

$ cargo run --example cfg --release

$ cargo run --example cfg

foo has been called 1 time

foo has been called 2 times

Запуск задач из ОЗУ

Главной целью переноса описания программы на RTIC в атрибуты в RTIC v0.4.x была возможность взаимодействия с другими атрибутами. Напримерe, атрибут link_section можно применять к задачам, чтобы разместить их в ОЗУ; это может улучшить производительность в некоторых случаях.

В примере ниже показано как разместить высокоприоритетную задачу bar в ОЗУ.

#![allow(unused)]

fn main() {

//! examples/ramfunc.rs

#![deny(unsafe_code)]

#![deny(warnings)]

#![no_main]

#![no_std]

use panic_semihosting as _;

#[rtic::app(

device = lm3s6965,

dispatchers = [

UART0,

#[link_section = ".data.UART1"]

UART1

])

]

mod app {

use cortex_m_semihosting::{debug, hprintln};

#[shared]

struct Shared {}

#[local]

struct Local {}

#[init]

fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {

foo::spawn().unwrap();

(Shared {}, Local {}, init::Monotonics())

}

#[inline(never)]

#[task]

fn foo(_: foo::Context) {

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

debug::exit(debug::EXIT_SUCCESS);

}

// run this task from RAM

#[inline(never)]

#[link_section = ".data.bar"]

#[task(priority = 2)]

fn bar(_: bar::Context) {

foo::spawn().unwrap();

}

}

}

Запуск этой программы создаст ожидаемый вывод.

$ cargo run --example ramfunc

foo

Можно посмотреть на вывод cargo-nm, чтобы убедиться, что bar расположен в ОЗУ (0x2000_0000), тогда как foo расположен во Flash (0x0000_0000).

$ cargo nm --example ramfunc --release | grep ' foo::'

00000162 t ramfunc::foo::h30e7789b08c08e19

$ cargo nm --example ramfunc --release | grep ' bar::'

20000000 t ramfunc::bar::h9d6714fe5a3b0c89

Обходной путь для быстрой передачи сообщений

Передача сообщений всегда вызывает копирование от отправителя в статическую переменную, а затем из статической переменной получателю. Таким образом, при передаче большого буфера, например [u8; 128], передача сообщения вызывает два дорогих вызова memcpy. Чтобы минимизировать накладные расходы на передачу сообщения, можно использовать обходной путь: вместо передачи буфера по значению, можно передавать владеющий указатель на буфер.

Можно использовать глобальный аллокатор, чтобы реализовать данный трюк (alloc::Box, alloc::Rc, и т.п.), либо использовать статически аллоцируемый пул памяти, например heapless::Pool.

Здесь приведен пример использования heapless::Pool для "упаковки" буфера из 128 байт.

#![allow(unused)]

fn main() {

//! examples/pool.rs

#![deny(unsafe_code)]

#![deny(warnings)]

#![no_main]

#![no_std]

use heapless::{

pool,

pool::singleton::{Box, Pool},

};

use panic_semihosting as _;

use rtic::app;

// Declare a pool of 128-byte memory blocks

pool!(P: [u8; 128]);

#[app(device = lm3s6965, dispatchers = [SSI0, QEI0])]

mod app {

use crate::{Box, Pool};

use cortex_m_semihosting::{debug, hprintln};

use lm3s6965::Interrupt;

// Import the memory pool into scope

use super::P;

#[shared]

struct Shared {}

#[local]

struct Local {}

#[init(local = [memory: [u8; 512] = [0; 512]])]

fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) {

// Increase the capacity of the memory pool by ~4

P::grow(cx.local.memory);

rtic::pend(Interrupt::I2C0);

(Shared {}, Local {}, init::Monotonics())

}

#[task(binds = I2C0, priority = 2)]

fn i2c0(_: i2c0::Context) {

// claim a memory block, initialize it and ..

let x = P::alloc().unwrap().init([0u8; 128]);

// .. send it to the `foo` task

foo::spawn(x).ok().unwrap();

// send another block to the task `bar`

bar::spawn(P::alloc().unwrap().init([0u8; 128]))

.ok()

.unwrap();

}

#[task]

fn foo(_: foo::Context, x: Box
) {

hprintln!("foo({:?})", x.as_ptr()).unwrap();

// explicitly return the block to the pool

drop(x);

debug::exit(debug::EXIT_SUCCESS);

}

#[task(priority = 2)]

fn bar(_: bar::Context, x: Box
) {

hprintln!("bar({:?})", x.as_ptr()).unwrap();

// this is done automatically so we can omit the call to `drop`

// drop(x);

}

}

}

$ cargo run --example pool

bar(0x2000008c)

foo(0x20000110)

Инспектирование раскрываемого кода

#[rtic::app] - это процедурный макрос, который создает код. Если по какой-то причине вам нужно увидеть код, сгенерированный этим макросом, у вас есть два пути:

Вы можете изучить файл rtic-expansion.rs внутри папки target. Этот файл содержит элемент #[rtic::app] в раскрытом виде (не всю вашу программу!) из последней сборки (с помощью cargo build или cargo check) RTIC программы. Раскрытый код не отформатирован по-умолчанию, но вы можете запустить rustfmt на нем перед тем, как читать.

$ cargo build --example foo

$ rustfmt target/rtic-expansion.rs

$ tail target/rtic-expansion.rs

#[doc = r" Implementation details"]

mod app {

#[doc = r" Always include the device crate which contains the vector table"]

use lm3s6965 as _;

#[no_mangle]

unsafe extern "C" fn main() -> ! {

rtic::export::interrupt::disable();

let mut core: rtic::export::Peripherals = core::mem::transmute(());

core.SCB.scr.modify(|r| r | 1 << 1);

rtic::export::interrupt::enable();

loop {

rtic::export::wfi()

}

}

}

Или, вы можете использовать подкоманду cargo-expand. Она раскроет все макросы, включая атрибут #[rtic::app], и модули в вашем крейте и напечатает вывод в консоль.

$ # создаст такой же вывод, как выше

$ cargo expand --example smallest | tail

Деструктуризация ресурса

Если задача требует нескольких ресурсов, разбиение структуры ресурсов может улучшить читабельность. Вот два примера того, как это можно сделать:

#![allow(unused)]

fn main() {

//! examples/destructure.rs

#![deny(unsafe_code)]

#![deny(warnings)]

#![no_main]

#![no_std]

use panic_semihosting as _;

#[rtic::app(device = lm3s6965)]

mod app {

use cortex_m_semihosting::hprintln;

use lm3s6965::Interrupt;

#[shared]

struct Shared {

// Some resources to work with

a: u32,

b: u32,

c: u32,

}

#[local]

struct Local {}

#[init]

fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {

rtic::pend(Interrupt::UART0);

rtic::pend(Interrupt::UART1);

(Shared { a: 0, b: 0, c: 0 }, Local {}, init::Monotonics())

}

// Direct destructure

#[task(binds = UART0, shared = [&a, &b, &c])]

fn uart0(cx: uart0::Context) {

let a = cx.shared.a;

let b = cx.shared.b;

let c = cx.shared.c;

hprintln!("UART0: a = {}, b = {}, c = {}", a, b, c).unwrap();

}

// De-structure-ing syntax

#[task(binds = UART1, shared = [&a, &b, &c])]

fn uart1(cx: uart1::Context) {

let uart1::SharedResources { a, b, c } = cx.shared;

hprintln!("UART0: a = {}, b = {}, c = {}", a, b, c).unwrap();

}

}

}