diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md index 3a3e0b7660..855cde93a6 100644 --- a/book/en/src/by-example/resources.md +++ b/book/en/src/by-example/resources.md @@ -7,22 +7,24 @@ Resources are data visible only to functions declared within the `#[app]` module. The framework gives the user complete control over which context can access which resource. -All resources are declared as a single `struct` within the `#[app]` -module. Each field in the structure corresponds to a different resource. -The `struct` must be annotated with the following attribute: `#[resources]`. - -Resources can optionally be given an initial value using the `#[init]` -attribute. Resources that are not given an initial value are referred to as -*late* resources and are covered in more detail in a follow-up section in this -page. +All resources are declared as *two* `struct`s within the `#[app]` module. +Each field in these structures corresponds to a different resource. +One `struct` must be annotated with the attribute `#[local]`. +The other `struct` must be annotated with the attribute `#[shared]`. +The difference between these two sets of resources will be covered later. Each context (task handler, `init` or `idle`) must declare the resources it -intends to access in its corresponding metadata attribute using the `resources` -argument. This argument takes a list of resource names as its value. The listed -resources are made available to the context under the `resources` field of the -`Context` structure. +intends to access in its corresponding metadata attribute using either the +`local` or `shared` argument. This argument takes a list of resource names as +its value. The listed resources are made available to the context under the +`local` and `shared` fields of the `Context` structure. -The example application shown below contains two interrupt handlers that share access to a resource named `shared`. +All resources are initialized at runtime, after the `#[init]` function returns. +The `#[init]` function must return the initial values for all resources; hence its return type includes the types of the `#[shared]` and `#[local]` structs. +Because resources are uninitialized during the execution of the `#[init]` function, they cannot be accessed within the `#[init]` function. + +The example application shown below contains two interrupt handlers. +Each handler has access to its own `#[local]` resource. ``` rust {{#include ../../../../examples/resource.rs}} @@ -33,13 +35,14 @@ $ cargo run --example resource {{#include ../../../../ci/expected/resource.run}} ``` -Note that the `shared` resource cannot be accessed from `idle`. Attempting to do so results in a compile error. +A `#[local]` resource cannot be accessed from outside the task it was associated to in a `#[task]` attribute. +Assigning the same `#[local]` resource to more than one task is a compile-time error. ## `lock` -Critical sections are required to access shared mutable data in a data race-free manner. +Critical sections are required to access `#[shared]` resources in a data race-free manner. -The `resources` field of the passed `Context` implements the [`Mutex`] trait for each shared resource accessible to the task. +The `shared` field of the passed `Context` implements the [`Mutex`] trait for each shared resource accessible to the task. The only method on this trait, [`lock`], runs its closure argument in a critical section. @@ -52,7 +55,7 @@ The critical section created by the `lock` API is based on dynamic priorities: i [icpp]: https://en.wikipedia.org/wiki/Priority_ceiling_protocol [srp]: https://en.wikipedia.org/wiki/Stack_Resource_Policy -In the example below we have three interrupt handlers with priorities ranging from one to three. The two handlers with the lower priorities contend for the `shared` resource and need to lock the resource for accessing the data. The highest priority handler, which do nat access the `shared` resource, is free to preempt the critical section created by the +In the example below we have three interrupt handlers with priorities ranging from one to three. The two handlers with the lower priorities contend for the `shared` resource and need to lock the resource for accessing the data. The highest priority handler, which do not access the `shared` resource, is free to preempt the critical section created by the lowest priority handler. ``` rust @@ -72,26 +75,7 @@ As an extension to `lock`, and to reduce rightward drift, locks can be taken as {{#include ../../../../examples/multilock.rs}} ``` -## Late resources - -Late resources are resources that are not given an initial value at compile time using the `#[init]` attribute but instead are initialized at runtime using the `init::LateResources` values returned by the `init` function. - -Late resources are useful e.g., to *move* (as in transferring the ownership of) peripherals initialized in `init` into tasks. - -The example below uses late resources to establish a lockless, one-way channel between the `UART0` interrupt handler and the `idle` task. A single producer single consumer [`Queue`] is used as the channel. The queue is split into consumer and producer end points in `init` and then each end point is stored in a different resource; `UART0` owns the producer resource and `idle` owns the consumer resource. - -[`Queue`]: ../../../api/heapless/spsc/struct.Queue.html - -``` rust -{{#include ../../../../examples/late.rs}} -``` - -``` console -$ cargo run --example late -{{#include ../../../../ci/expected/late.run}} -``` - -## Only shared access +## Only shared (`&-`) access By default the framework assumes that all tasks require exclusive access (`&mut-`) to resources but it is possible to specify that a task only requires shared access (`&-`) to a resource using the `&resource_name` syntax in the `resources` list. @@ -113,12 +97,15 @@ $ cargo run --example only-shared-access ## Lock-free resource access of mutable resources -There exists two other options dealing with resources +A critical section is *not* required to access a `#[shared]` resource that's only accessed by tasks running at the *same* priority. +In this case, you can opt out of the `lock` API by adding the `#[lock_free]` field-level attribute to the resource declaration (see example below). +Note that this is merely a convenience: if you do use the `lock` API, at runtime the framework will *not* produce a critical section. -* `#[lock_free]`: there might be several tasks with the same priority - accessing the resource without critical section. Since tasks with the - same priority never can preempt another task on the same priority - this is safe. -* `#[task_local]`: there must be only one task using this resource, - similar to a `static mut` task local resource, but (optionally) set-up by init. +``` rust +{{#include ../../../../examples/lock-free.rs}} +``` +``` console +$ cargo run --example lock-free +{{#include ../../../../ci/expected/lock-free.run}} +``` diff --git a/ci/expected/lock-free.run b/ci/expected/lock-free.run new file mode 100644 index 0000000000..56f47a0be4 --- /dev/null +++ b/ci/expected/lock-free.run @@ -0,0 +1,14 @@ +GPIOA/start + GPIOA/counter = 1 +GPIOA/end +GPIOB/start + GPIOB/counter = 2 +GPIOB/end +GPIOA/start + GPIOA/counter = 3 +GPIOA/end +GPIOB/start + GPIOB/counter = 4 +GPIOB/end +GPIOA/start + GPIOA/counter = 5 diff --git a/ci/expected/resource.run b/ci/expected/resource.run index ca12f0ed5e..9b60960f44 100644 --- a/ci/expected/resource.run +++ b/ci/expected/resource.run @@ -1,2 +1,2 @@ -UART1: shared = 1 -UART0: shared = 2 +UART1: local_to_uart1 = 1 +UART0: local_to_uart0 = 1 diff --git a/examples/lock-free.rs b/examples/lock-free.rs new file mode 100644 index 0000000000..db74c7d8b0 --- /dev/null +++ b/examples/lock-free.rs @@ -0,0 +1,60 @@ +//! examples/lock-free.rs + +#![deny(unsafe_code)] +#![deny(warnings)] +#![no_main] +#![no_std] + +use panic_semihosting as _; + +#[rtic::app(device = lm3s6965)] +mod app { + use cortex_m_semihosting::{debug, hprintln}; + use lm3s6965::Interrupt; + + #[shared] + struct Shared { + #[lock_free] // <- lock-free shared resource + counter: u64, + } + + #[local] + struct Local {} + + #[init] + fn init(_: init::Context) -> (Shared, Local, init::Monotonics) { + rtic::pend(Interrupt::GPIOA); + + (Shared { counter: 0 }, Local {}, init::Monotonics()) + } + + #[task(binds = GPIOA, shared = [counter])] // <- same priority + fn gpioa(c: gpioa::Context) { + hprintln!("GPIOA/start").unwrap(); + rtic::pend(Interrupt::GPIOB); + + *c.shared.counter += 1; // <- no lock API required + let counter = *c.shared.counter; + hprintln!(" GPIOA/counter = {}", counter).unwrap(); + + if counter == 5 { + debug::exit(debug::EXIT_SUCCESS); + } + hprintln!("GPIOA/end").unwrap(); + } + + #[task(binds = GPIOB, shared = [counter])] // <- same priority + fn gpiob(c: gpiob::Context) { + hprintln!("GPIOB/start").unwrap(); + rtic::pend(Interrupt::GPIOA); + + *c.shared.counter += 1; // <- no lock API required + let counter = *c.shared.counter; + hprintln!(" GPIOB/counter = {}", counter).unwrap(); + + if counter == 5 { + debug::exit(debug::EXIT_SUCCESS); + } + hprintln!("GPIOB/end").unwrap(); + } +} diff --git a/examples/resource.rs b/examples/resource.rs index 2c7dffe334..dca0b37034 100644 --- a/examples/resource.rs +++ b/examples/resource.rs @@ -13,55 +13,69 @@ mod app { use lm3s6965::Interrupt; #[shared] - struct Shared { - shared: u32, - } + struct Shared {} #[local] - struct Local {} + struct Local { + local_to_uart0: i64, + local_to_uart1: i64, + } #[init] fn init(_: init::Context) -> (Shared, Local, init::Monotonics) { rtic::pend(Interrupt::UART0); rtic::pend(Interrupt::UART1); - (Shared { shared: 0 }, Local {}, init::Monotonics()) + ( + Shared {}, + // initial values for the `#[local]` resources + Local { + local_to_uart0: 0, + local_to_uart1: 0, + }, + init::Monotonics(), + ) } - // `shared` cannot be accessed from this context + // `#[local]` resources cannot be accessed from this context #[idle] fn idle(_cx: idle::Context) -> ! { debug::exit(debug::EXIT_SUCCESS); - // error: no `shared` field in `idle::Context` - // _cx.shared.shared += 1; + // error: no `local` field in `idle::Context` + // _cx.local.local_to_uart0 += 1; + + // error: no `local` field in `idle::Context` + // _cx.local.local_to_uart1 += 1; loop { cortex_m::asm::nop(); } } - // `shared` can be accessed from this context + // `local_to_uart0` can only be accessed from this context // defaults to priority 1 - #[task(binds = UART0, shared = [shared])] - fn uart0(mut cx: uart0::Context) { - let shared = cx.shared.shared.lock(|shared| { - *shared += 1; - *shared - }); + #[task(binds = UART0, local = [local_to_uart0])] + fn uart0(cx: uart0::Context) { + *cx.local.local_to_uart0 += 1; + let local_to_uart0 = cx.local.local_to_uart0; - hprintln!("UART0: shared = {}", shared).unwrap(); + // error: no `local_to_uart1` field in `uart0::LocalResources` + // cx.local.local_to_uart1 += 1; + + hprintln!("UART0: local_to_uart0 = {}", local_to_uart0).unwrap(); } - // `shared` can be accessed from this context + // `shared` can only be accessed from this context // explicitly set to priority 2 - #[task(binds = UART1, shared = [shared], priority = 2)] - fn uart1(mut cx: uart1::Context) { - let shared = cx.shared.shared.lock(|shared| { - *shared += 1; - *shared - }); + #[task(binds = UART1, local = [local_to_uart1], priority = 2)] + fn uart1(cx: uart1::Context) { + *cx.local.local_to_uart1 += 1; + let local_to_uart1 = cx.local.local_to_uart1; - hprintln!("UART1: shared = {}", shared).unwrap(); + // error: no `local_to_uart0` field in `uart1::LocalResources` + // cx.local.local_to_uart0 += 1; + + hprintln!("UART1: local_to_uart1 = {}", local_to_uart1).unwrap(); } }