julidi / assign-resources

Rust macro to split up fields of a Peripherals struct into new structs

assign-resources

This crate contains a macro to help assign and split up resources from a struct, such as the Peripherals struct provided by embedded PACs and HALs, into many smaller structs which can be passed to other tasks or functions.

It's best explained with the example below. Here we define new structs named UsbResources and LedResources, each containing some IO pins and a peripheral, and generate a new split_resources!() macro. When called, the split_resources!() macro takes PA12, PA11, and USB out of p: Peripherals and uses them to create the field usb: UsbResources, and similarly creates the field leds: LedResources in the returned object. We can then move these new structs into our tasks, which access the resources by name.

We can also label some resources with type aliases, so function signatures can refer to that type as well.

use assign_resources::assign_resources;
use embassy_stm32::peripherals;

assign_resources! {
    usb: UsbResources {
        dp: PA12,
        dm: PA11,
        usb: USB,
    }
    leds: LedResources {
        r: PA2,
        g: PA3,
        b: PA4,
        tim2: TIM2 = PWMTimer,
    }
}

#[embassy_executor::task]
async fn usb_task(r: UsbResources) {
    // use r.dp, r.dm, r.usb
}

async fn setup_leds<'a>(r: LedResources) -> SimplePWM<'a, PWMTimer> {
    // setup three channel PWM (one for each color)
}

#[embassy_executor::task]
async fn led_task(rgb_pwm: SimplePWM<'a, PWMTimer>) {
    // use rgb_pwm
}

#[embassy_executor::main]
async fn main(spawner: embassy_executor::Spawner) {
    let p = embassy_stm32::init(Default::default());
    let r = split_resources!(p);

    let rgb_pwm = setup_leds(r.leds);

    spawner.spawn(usb_task(r.usb)).unwrap();
    spawner.spawn(led_task(rgb_pwm)).unwrap();

    // can still use p.PA0, p.PA1, etc
}

This has a few advantages: you only need to write the specific pin names like PA12 in one place and can refer to them by name thereafter, you only have one argument for each task instead of potentially very many, and you don't need to write out lots of code to split the resources up. If you're targetting multiple different hardware, you can use #[cfg] to change pin allocations in just one place.

Definition in a library

The following code would go in the library file, i.e., lib.rs

use assign_resources::assign_resources;
use embassy_stm32::peripherals;

assign_resources! {
    usb: UsbResources {
        dp: PA12,
        dm: PA11,
        usb: USB_OTG_FS,
    }
    leds: LedResources {
        r: PA2,
        g: PA3,
        b: PA4,
        tim2: TIM2,
    }
}

and the resources can be accessed from outside, e.g., in my_bin.rs:

// import `AssignedResources`, the `split_resources` macro and all custom resources structs from the library
use my_library::{AssignedResources, LedResources, UsbResources, split_resources};

#[embassy_executor::task]
async fn usb_task(r: UsbResources) {
    // use r.dp, r.dm, r.usb
}
#[embassy_executor::task]
async fn led_task(r: LedResources) {
    // use r.r, r.g, r.b, r.tim2
}
#[embassy_executor::main]
async fn main(spawner: embassy_executor::Spawner) {
    let p = embassy_stm32::init(Default::default());
    let r = split_resources!(p);
    spawner.spawn(usb_task(r.usb)).unwrap();
    spawner.spawn(led_task(r.leds)).unwrap();
    // can still use p.PA0, p.PA1, etc
}