Merge #498

498: book: update the resources chapter r=AfoHT a=japaric

see individual commit messages for details.

what's still left to do is adjust the very last section about `#[task_local]` and `#[lock_free]` but I plan to do that as a follow up. I didn't find an in-tree example for those two attributes (are they field attributes? where do they fit in the syntax?); a quick scan of the rtic-syntax crate seems to indicate that `task_local` has been removed (?) and that `lock_free` still exists.

Co-authored-by: Jorge Aparicio <jorge.aparicio@ferrous-systems.com>

1 files changed, 60 insertions, 0 deletions

diff --git a/examples/lock-free.rs b/examples/lock-free.rs
new file mode 100644
index 0000000..db74c7d
--- /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();
+    }
+}