doc up

examples/baseline.rs

@@ -13,18 +13,18 @@ use panic_semihosting as _;
 #[rtfm::app(device = lm3s6965, monotonic = rtfm::cyccnt::CYCCNT)]
 const APP: () = {
     #[init(spawn = [foo])]
-    fn init(c: init::Context) {
-        hprintln!("init(baseline = {:?})", c.start).unwrap();
+    fn init(cx: init::Context) {
+        hprintln!("init(baseline = {:?})", cx.start).unwrap();
 
         // `foo` inherits the baseline of `init`: `Instant(0)`
-        c.spawn.foo().unwrap();
+        cx.spawn.foo().unwrap();
     }
 
     #[task(schedule = [foo])]
-    fn foo(c: foo::Context) {
+    fn foo(cx: foo::Context) {
         static mut ONCE: bool = true;
 
-        hprintln!("foo(baseline = {:?})", c.scheduled).unwrap();
+        hprintln!("foo(baseline = {:?})", cx.scheduled).unwrap();
 
         if *ONCE {
             *ONCE = false;
@@ -36,11 +36,11 @@ const APP: () = {
     }
 
     #[task(binds = UART0, spawn = [foo])]
-    fn uart0(c: uart0::Context) {
-        hprintln!("UART0(baseline = {:?})", c.start).unwrap();
+    fn uart0(cx: uart0::Context) {
+        hprintln!("UART0(baseline = {:?})", cx.start).unwrap();
 
         // `foo` inherits the baseline of `UART0`: its `start` time
-        c.spawn.foo().unwrap();
+        cx.spawn.foo().unwrap();
     }
 
     extern "C" {

examples/cfg.rs

@@ -5,6 +5,7 @@
 #![no_main]
 #![no_std]
 
+use cortex_m_semihosting::debug;
 #[cfg(debug_assertions)]
 use cortex_m_semihosting::hprintln;
 use panic_semihosting as _;
@@ -17,28 +18,36 @@ const APP: () = {
         count: u32,
     }
 
-    #[init]
-    fn init(_: init::Context) {
-        // ..
+    #[init(spawn = [foo])]
+    fn init(cx: init::Context) {
+        cx.spawn.foo().unwrap();
+        cx.spawn.foo().unwrap();
     }
 
-    #[task(priority = 3, resources = [count], spawn = [log])]
-    fn foo(_c: foo::Context) {
+    #[idle]
+    fn idle(_: idle::Context) -> ! {
+        debug::exit(debug::EXIT_SUCCESS);
+
+        loop {}
+    }
+
+    #[task(capacity = 2, resources = [count], spawn = [log])]
+    fn foo(_cx: foo::Context) {
         #[cfg(debug_assertions)]
         {
-            *_c.resources.count += 1;
+            *_cx.resources.count += 1;
 
-            _c.spawn.log(*_c.resources.count).ok();
+            _cx.spawn.log(*_cx.resources.count).unwrap();
         }
 
         // this wouldn't compile in `release` mode
-        // *resources.count += 1;
+        // *_cx.resources.count += 1;
 
         // ..
     }
 
     #[cfg(debug_assertions)]
-    #[task]
+    #[task(capacity = 2)]
     fn log(_: log::Context, n: u32) {
         hprintln!(
             "foo has been called {} time{}",

examples/generics.rs

@@ -29,6 +29,7 @@ const APP: () = {
 
         hprintln!("UART0(STATE = {})", *STATE).unwrap();
 
+        // second argument has type `resources::shared`
         advance(STATE, c.resources.shared);
 
         rtfm::pend(Interrupt::UART1);
@@ -45,14 +46,16 @@ const APP: () = {
         // just to show that `shared` can be accessed directly
         *c.resources.shared += 0;
 
+        // second argument has type `Exclusive<u32>`
         advance(STATE, Exclusive(c.resources.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<T = u32>) {
     *state += 1;
 
-    let (old, new) = shared.lock(|shared| {
+    let (old, new) = shared.lock(|shared: &mut u32| {
         let old = *shared;
         *shared += *state;
         (old, *shared)

examples/hardware.rs

@@ -1,4 +1,4 @@
-//! examples/interrupt.rs
+//! examples/hardware.rs
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
@@ -15,7 +15,7 @@ const APP: () = {
     fn init(_: init::Context) {
         // Pends the UART0 interrupt but its handler won't run until *after*
         // `init` returns because interrupts are disabled
-        rtfm::pend(Interrupt::UART0);
+        rtfm::pend(Interrupt::UART0); // equivalent to NVIC::pend
 
         hprintln!("init").unwrap();
     }

examples/init.rs

@@ -11,14 +11,14 @@ use panic_semihosting as _;
 #[rtfm::app(device = lm3s6965, peripherals = true)]
 const APP: () = {
     #[init]
-    fn init(c: init::Context) {
+    fn init(cx: init::Context) {
         static mut X: u32 = 0;
 
         // Cortex-M peripherals
-        let _core: cortex_m::Peripherals = c.core;
+        let _core: cortex_m::Peripherals = cx.core;
 
         // Device specific peripherals
-        let _device: lm3s6965::Peripherals = c.device;
+        let _device: lm3s6965::Peripherals = cx.device;
 
         // Safe access to local `static mut` variable
         let _x: &'static mut u32 = X;

examples/late.rs

@@ -8,6 +8,7 @@
 use cortex_m_semihosting::{debug, hprintln};
 use heapless::{
     consts::*,
+    i,
     spsc::{Consumer, Producer, Queue},
 };
 use lm3s6965::Interrupt;
@@ -23,12 +24,9 @@ const APP: () = {
 
     #[init]
     fn init(_: init::Context) -> init::LateResources {
-        // NOTE: we use `Option` here to work around the lack of
-        // a stable `const` constructor
-        static mut Q: Option<Queue<u32, U4>> = None;
+        static mut Q: Queue<u32, U4> = Queue(i::Queue::new());
 
-        *Q = Some(Queue::new());
-        let (p, c) = Q.as_mut().unwrap().split();
+        let (p, c) = Q.split();
 
         // Initialization of late resources
         init::LateResources { p, c }

examples/not-sync.rs

@@ -26,12 +26,12 @@ const APP: () = {
         debug::exit(debug::EXIT_SUCCESS);
     }
 
-    #[task(resources = [shared])]
+    #[task(resources = [&shared])]
     fn foo(c: foo::Context) {
         let _: &NotSync = c.resources.shared;
     }
 
-    #[task(resources = [shared])]
+    #[task(resources = [&shared])]
     fn bar(c: bar::Context) {
         let _: &NotSync = c.resources.shared;
     }

examples/only-shared-access.rs

@@ -24,14 +24,15 @@ const APP: () = {
     }
 
     #[task(binds = UART0, resources = [&key])]
-    fn uart0(c: uart0::Context) {
-        hprintln!("UART0(key = {:#x})", c.resources.key).unwrap();
+    fn uart0(cx: uart0::Context) {
+        let key: &u32 = cx.resources.key;
+        hprintln!("UART0(key = {:#x})", key).unwrap();
 
         debug::exit(debug::EXIT_SUCCESS);
     }
 
     #[task(binds = UART1, priority = 2, resources = [&key])]
-    fn uart1(c: uart1::Context) {
-        hprintln!("UART1(key = {:#x})", c.resources.key).unwrap();
+    fn uart1(cx: uart1::Context) {
+        hprintln!("UART1(key = {:#x})", cx.resources.key).unwrap();
     }
 };

examples/periodic.rs

@@ -15,16 +15,16 @@ const PERIOD: u32 = 8_000_000;
 #[rtfm::app(device = lm3s6965, monotonic = rtfm::cyccnt::CYCCNT)]
 const APP: () = {
     #[init(schedule = [foo])]
-    fn init(c: init::Context) {
-        c.schedule.foo(Instant::now() + PERIOD.cycles()).unwrap();
+    fn init(cx: init::Context) {
+        cx.schedule.foo(Instant::now() + PERIOD.cycles()).unwrap();
     }
 
     #[task(schedule = [foo])]
-    fn foo(c: foo::Context) {
+    fn foo(cx: foo::Context) {
         let now = Instant::now();
-        hprintln!("foo(scheduled = {:?}, now = {:?})", c.scheduled, now).unwrap();
+        hprintln!("foo(scheduled = {:?}, now = {:?})", cx.scheduled, now).unwrap();
 
-        c.schedule.foo(c.scheduled + PERIOD.cycles()).unwrap();
+        cx.schedule.foo(cx.scheduled + PERIOD.cycles()).unwrap();
     }
 
     extern "C" {

examples/preempt.rs

@@ -0,0 +1,37 @@
+//! examples/preempt.rs
+
+#![no_main]
+#![no_std]
+
+use cortex_m_semihosting::{debug, hprintln};
+use lm3s6965::Interrupt;
+use panic_semihosting as _;
+use rtfm::app;
+
+#[app(device = lm3s6965)]
+const APP: () = {
+    #[init]
+    fn init(_: init::Context) {
+        rtfm::pend(Interrupt::UART0);
+    }
+
+    #[task(binds = UART0, priority = 1)]
+    fn uart0(_: uart0::Context) {
+        hprintln!("UART0 - start").unwrap();
+        rtfm::pend(Interrupt::UART2);
+        hprintln!("UART0 - end").unwrap();
+        debug::exit(debug::EXIT_SUCCESS);
+    }
+
+    #[task(binds = UART1, priority = 2)]
+    fn uart1(_: uart1::Context) {
+        hprintln!(" UART1").unwrap();
+    }
+
+    #[task(binds = UART2, priority = 2)]
+    fn uart2(_: uart2::Context) {
+        hprintln!(" UART2 - start").unwrap();
+        rtfm::pend(Interrupt::UART1);
+        hprintln!(" UART2 - end").unwrap();
+    }
+};

examples/resource.rs

@@ -23,29 +23,31 @@ const APP: () = {
         rtfm::pend(Interrupt::UART1);
     }
 
+    // `shared` cannot be accessed from this context
     #[idle]
-    fn idle(_: idle::Context) -> ! {
+    fn idle(_cx: idle::Context) -> ! {
         debug::exit(debug::EXIT_SUCCESS);
 
-        // error: `shared` can't be accessed from this context
-        // shared += 1;
+        // error: no `resources` field in `idle::Context`
+        // _cx.resources.shared += 1;
 
         loop {}
     }
 
-    // `shared` can be access from this context
+    // `shared` can be accessed from this context
     #[task(binds = UART0, resources = [shared])]
-    fn uart0(c: uart0::Context) {
-        *c.resources.shared += 1;
+    fn uart0(cx: uart0::Context) {
+        let shared: &mut u32 = cx.resources.shared;
+        *shared += 1;
 
-        hprintln!("UART0: shared = {}", c.resources.shared).unwrap();
+        hprintln!("UART0: shared = {}", shared).unwrap();
     }
 
-    // `shared` can be access from this context
+    // `shared` can be accessed from this context
     #[task(binds = UART1, resources = [shared])]
-    fn uart1(c: uart1::Context) {
-        *c.resources.shared += 1;
+    fn uart1(cx: uart1::Context) {
+        *cx.resources.shared += 1;
 
-        hprintln!("UART1: shared = {}", c.resources.shared).unwrap();
+        hprintln!("UART1: shared = {}", cx.resources.shared).unwrap();
     }
 };

examples/schedule.rs

@@ -13,16 +13,16 @@ use rtfm::cyccnt::{Instant, U32Ext as _};
 #[rtfm::app(device = lm3s6965, monotonic = rtfm::cyccnt::CYCCNT)]
 const APP: () = {
     #[init(schedule = [foo, bar])]
-    fn init(c: init::Context) {
+    fn init(cx: init::Context) {
         let now = Instant::now();
 
         hprintln!("init @ {:?}", now).unwrap();
 
         // Schedule `foo` to run 8e6 cycles (clock cycles) in the future
-        c.schedule.foo(now + 8_000_000.cycles()).unwrap();
+        cx.schedule.foo(now + 8_000_000.cycles()).unwrap();
 
         // Schedule `bar` to run 4e6 cycles in the future
-        c.schedule.bar(now + 4_000_000.cycles()).unwrap();
+        cx.schedule.bar(now + 4_000_000.cycles()).unwrap();
     }
 
     #[task]

examples/smallest.rs

@@ -1,7 +1,5 @@
 //! examples/smallest.rs
 
-#![deny(unsafe_code)]
-#![deny(warnings)]
 #![no_main]
 #![no_std]
 

examples/task.rs

@@ -17,16 +17,20 @@ const APP: () = {
 
     #[task(spawn = [bar, baz])]
     fn foo(c: foo::Context) {
-        hprintln!("foo").unwrap();
+        hprintln!("foo - start").unwrap();
 
         // spawns `bar` onto the task scheduler
         // `foo` and `bar` have the same priority so `bar` will not run until
         // after `foo` terminates
         c.spawn.bar().unwrap();
 
+        hprintln!("foo - middle").unwrap();
+
         // spawns `baz` onto the task scheduler
         // `baz` has higher priority than `foo` so it immediately preempts `foo`
         c.spawn.baz().unwrap();
+
+        hprintln!("foo - end").unwrap();
     }
 
     #[task]

examples/types.rs

@@ -7,7 +7,7 @@
 
 use cortex_m_semihosting::debug;
 use panic_semihosting as _;
-use rtfm::cyccnt::Instant;
+use rtfm::cyccnt;
 
 #[rtfm::app(device = lm3s6965, peripherals = true, monotonic = rtfm::cyccnt::CYCCNT)]
 const APP: () = {
@@ -17,38 +17,39 @@ const APP: () = {
     }
 
     #[init(schedule = [foo], spawn = [foo])]
-    fn init(c: init::Context) {
-        let _: Instant = c.start;
-        let _: rtfm::Peripherals = c.core;
-        let _: lm3s6965::Peripherals = c.device;
-        let _: init::Schedule = c.schedule;
-        let _: init::Spawn = c.spawn;
+    fn init(cx: init::Context) {
+        let _: cyccnt::Instant = cx.start;
+        let _: rtfm::Peripherals = cx.core;
+        let _: lm3s6965::Peripherals = cx.device;
+        let _: init::Schedule = cx.schedule;
+        let _: init::Spawn = cx.spawn;
 
         debug::exit(debug::EXIT_SUCCESS);
     }
 
-    #[task(binds = SVCall, schedule = [foo], spawn = [foo])]
-    fn svcall(c: svcall::Context) {
-        let _: Instant = c.start;
-        let _: svcall::Schedule = c.schedule;
-        let _: svcall::Spawn = c.spawn;
+    #[idle(schedule = [foo], spawn = [foo])]
+    fn idle(cx: idle::Context) -> ! {
+        let _: idle::Schedule = cx.schedule;
+        let _: idle::Spawn = cx.spawn;
+
+        loop {}
     }
 
     #[task(binds = UART0, resources = [shared], schedule = [foo], spawn = [foo])]
-    fn uart0(c: uart0::Context) {
-        let _: Instant = c.start;
-        let _: resources::shared = c.resources.shared;
-        let _: uart0::Schedule = c.schedule;
-        let _: uart0::Spawn = c.spawn;
+    fn uart0(cx: uart0::Context) {
+        let _: cyccnt::Instant = cx.start;
+        let _: resources::shared = cx.resources.shared;
+        let _: uart0::Schedule = cx.schedule;
+        let _: uart0::Spawn = cx.spawn;
     }
 
     #[task(priority = 2, resources = [shared], schedule = [foo], spawn = [foo])]
-    fn foo(c: foo::Context) {
-        let _: Instant = c.scheduled;
-        let _: &mut u32 = c.resources.shared;
-        let _: foo::Resources = c.resources;
-        let _: foo::Schedule = c.schedule;
-        let _: foo::Spawn = c.spawn;
+    fn foo(cx: foo::Context) {
+        let _: cyccnt::Instant = cx.scheduled;
+        let _: &mut u32 = cx.resources.shared;
+        let _: foo::Resources = cx.resources;
+        let _: foo::Schedule = cx.schedule;
+        let _: foo::Spawn = cx.spawn;
     }
 
     extern "C" {