add draft doc page for peripheral sharing

docs/modules/ROOT/nav.adoc

@@ -6,6 +6,7 @@
 * xref:layer_by_layer.adoc[Bare metal to async]
 * xref:runtime.adoc[Executor]
 * xref:delaying_a_task.adoc[Delaying a Task]
+* xref:sharing_peripherals.adoc[Sharing peripherals between tasks]
 * xref:hal.adoc[HAL]
 ** xref:nrf.adoc[nRF]
 ** xref:stm32.adoc[STM32]

docs/modules/ROOT/pages/sharing_peripherals.adoc

@@ -0,0 +1,78 @@
+= Sharing peripherals between tasks
+
+Often times, more than one task needs access to the same resource (pin, communication interface, etc.). The following example shows how to use the on-board LED on a Raspberry Pi Pico board by two tasks simultaneously. 
+
+[,rust]
+----
+use defmt::*;
+use embassy_executor::Spawner;
+use embassy_rp::gpio;
+use embassy_sync::blocking_mutex::raw::ThreadModeRawMutex;
+use embassy_sync::mutex::Mutex;
+use embassy_time::{Duration, Ticker};
+use gpio::{AnyPin, Level, Output};
+use {defmt_rtt as _, panic_probe as _};
+
+type LedType = Mutex<ThreadModeRawMutex, Option<Output<'static, AnyPin>>>;
+static LED: LedType = Mutex::new(None);
+
+#[embassy_executor::main]
+async fn main(spawner: Spawner) {
+    let p = embassy_rp::init(Default::default());
+    // set the content of the global LED reference to the real LED pin
+    let led = Output::new(AnyPin::from(p.PIN_25), Level::High);
+    // inner scope is so that once the mutex is written to, the MutexGuard is dropped, thus the
+    // Mutex is released
+    {
+        *(LED.lock().await) = Some(led);
+    }
+    let dt = 100 * 1_000_000;
+    let k = 1.003;
+
+    unwrap!(spawner.spawn(toggle(&LED, Duration::from_nanos(dt))));
+    unwrap!(spawner.spawn(toggle_slightly_slower(
+        &LED,
+        Duration::from_nanos((dt as f64 * k) as u64)
+    )));
+}
+
+async fn toggle_led(led: &'static LedType, delay: Duration) {
+    let mut ticker = Ticker::every(delay);
+    loop {
+        {
+            let mut led_unlocked = led.lock().await;
+            if let Some(pin_ref) = led_unlocked.as_mut() {
+                pin_ref.toggle();
+            }
+        }
+        ticker.next().await;
+    }
+}
+#[embassy_executor::task]
+async fn toggle(led: &'static LedType, delay: Duration) {
+    toggle_led(led, delay).await
+}
+
+#[embassy_executor::task]
+async fn toggle_slightly_slower(led: &'static LedType, delay: Duration) {
+    toggle_led(led, delay).await
+}
+----
+
+The structure facilitating access to the resource is the defined `LedType`.
+
+== Why so complicated
+
+Unwrapping the layers gives insight into why each one is needed.
+
+=== `Mutex<RawMutexType, T>`
+
+The mutex is there so if one task gets the resource first and begins modifying it, all other tasks wanting to write will have to wait (the `led.lock().await` will return immediately if no task has locked the mutex, and will block if it is accessed somewhere else). 
+
+=== `Option<T>`
+
+The `LED` variable needs to be defined outside the main task as references accepted by tasks need to be `'static`. However, if it is outside the main task, it cannot be initialised to point to any pin, as the pins themselves are not initialised. Thus, it is set to `None`. 
+
+=== `Output<AnyPin>`
+
+To indicate that the pin will be set to an Output. The `AnyPin` could have been `embassy_rp::peripherals::PIN_25`, however this option lets the `toggle_led` function be more generic.