implement RFCs 147 and 155, etc.

This commit:

- Implements RFC 147: "all functions must be safe"

- Implements RFC 155: "explicit Context parameter"

- Implements the pending breaking change #141: reject assign syntax in `init`
  (which was used to initialize late resources)

- Refactors code generation to make it more readable -- there are no more random
  identifiers in the output -- and align it with the book description of RTFM
  internals.

- Makes the framework hard depend on `core::mem::MaybeUninit` and thus will
  require nightly until that API is stabilized.

- Fixes a ceiling analysis bug where the priority of the system timer was not
  considered in the analysis.

- Shrinks the size of all the internal queues by turning `AtomicUsize` indices
  into `AtomicU8`s.

- Removes the integration with `owned_singleton`.

3 files changed, 73 insertions, 150 deletions

diff --git a/src/export.rs b/src/export.rs
index cf7293b6..93a92fcf 100644
--- a/src/export.rs
+++ b/src/export.rs
@@ -1,7 +1,5 @@
 //! IMPLEMENTATION DETAILS. DO NOT USE ANYTHING IN THIS MODULE
 
-#[cfg(not(feature = "nightly"))]
-use core::ptr;
 use core::{cell::Cell, u8};
 
 #[cfg(armv7m)]
@@ -14,25 +12,31 @@ pub use heapless::consts;
 use heapless::spsc::{Queue, SingleCore};
 
 #[cfg(feature = "timer-queue")]
-pub use crate::tq::{isr as sys_tick, NotReady, TimerQueue};
+pub use crate::tq::{NotReady, TimerQueue};
 
-pub type FreeQueue<N> = Queue<u8, N, usize, SingleCore>;
-pub type ReadyQueue<T, N> = Queue<(T, u8), N, usize, SingleCore>;
+pub type FreeQueue<N> = Queue<u8, N, u8, SingleCore>;
+pub type ReadyQueue<T, N> = Queue<(T, u8), N, u8, SingleCore>;
 
 #[cfg(armv7m)]
 #[inline(always)]
-pub fn run<F>(f: F)
+pub fn run<F>(priority: u8, f: F)
 where
     F: FnOnce(),
 {
-    let initial = basepri::read();
-    f();
-    unsafe { basepri::write(initial) }
+    if priority == 1 {
+        // if the priority of this interrupt is `1` then BASEPRI can only be `0`
+        f();
+        unsafe { basepri::write(0) }
+    } else {
+        let initial = basepri::read();
+        f();
+        unsafe { basepri::write(initial) }
+    }
 }
 
 #[cfg(not(armv7m))]
 #[inline(always)]
-pub fn run<F>(f: F)
+pub fn run<F>(_priority: u8, f: F)
 where
     F: FnOnce(),
 {
@@ -52,7 +56,7 @@ impl Priority {
         }
     }
 
-    // these two methods are used by claim (see below) but can't be used from the RTFM application
+    // these two methods are used by `lock` (see below) but can't be used from the RTFM application
     #[inline(always)]
     fn set(&self, value: u8) {
         self.inner.set(value)
@@ -64,13 +68,12 @@ impl Priority {
     }
 }
 
-#[cfg(feature = "nightly")]
+// We newtype `core::mem::MaybeUninit` so the end-user doesn't need `#![feature(maybe_uninit)]` in
+// their code
 pub struct MaybeUninit<T> {
-    // we newtype so the end-user doesn't need `#![feature(maybe_uninit)]` in their code
     inner: core::mem::MaybeUninit<T>,
 }
 
-#[cfg(feature = "nightly")]
 impl<T> MaybeUninit<T> {
     pub const fn uninit() -> Self {
         MaybeUninit {
@@ -86,61 +89,12 @@ impl<T> MaybeUninit<T> {
         self.inner.as_mut_ptr()
     }
 
-    pub fn write(&mut self, value: T) -> &mut T {
-        self.inner.write(value)
-    }
-}
-
-#[cfg(not(feature = "nightly"))]
-pub struct MaybeUninit<T> {
-    value: Option<T>,
-}
-
-#[cfg(not(feature = "nightly"))]
-const MSG: &str =
-    "you have hit a bug (UB) in RTFM implementation; try enabling this crate 'nightly' feature";
-
-#[cfg(not(feature = "nightly"))]
-impl<T> MaybeUninit<T> {
-    pub const fn uninit() -> Self {
-        MaybeUninit { value: None }
-    }
-
-    pub fn as_ptr(&self) -> *const T {
-        if let Some(x) = self.value.as_ref() {
-            x
-        } else {
-            unreachable!(MSG)
-        }
+    pub unsafe fn read(&self) -> T {
+        self.inner.read()
     }
 
-    pub fn as_mut_ptr(&mut self) -> *mut T {
-        if let Some(x) = self.value.as_mut() {
-            x
-        } else {
-            unreachable!(MSG)
-        }
-    }
-
-    pub unsafe fn get_ref(&self) -> &T {
-        if let Some(x) = self.value.as_ref() {
-            x
-        } else {
-            unreachable!(MSG)
-        }
-    }
-
-    pub unsafe fn get_mut(&mut self) -> &mut T {
-        if let Some(x) = self.value.as_mut() {
-            x
-        } else {
-            unreachable!(MSG)
-        }
-    }
-
-    pub fn write(&mut self, val: T) {
-        // NOTE(volatile) we have observed UB when this uses a plain `ptr::write`
-        unsafe { ptr::write_volatile(&mut self.value, Some(val)) }
+    pub fn write(&mut self, value: T) -> &mut T {
+        self.inner.write(value)
     }
 }
 
@@ -160,19 +114,16 @@ where
 
 #[cfg(armv7m)]
 #[inline(always)]
-pub unsafe fn claim<T, R, F>(
+pub unsafe fn lock<T, R>(
     ptr: *mut T,
     priority: &Priority,
     ceiling: u8,
     nvic_prio_bits: u8,
-    f: F,
-) -> R
-where
-    F: FnOnce(&mut T) -> R,
-{
+    f: impl FnOnce(&mut T) -> R,
+) -> R {
     let current = priority.get();
 
-    if priority.get() < ceiling {
+    if current < ceiling {
         if ceiling == (1 << nvic_prio_bits) {
             priority.set(u8::MAX);
             let r = interrupt::free(|_| f(&mut *ptr));
@@ -193,19 +144,16 @@ where
 
 #[cfg(not(armv7m))]
 #[inline(always)]
-pub unsafe fn claim<T, R, F>(
+pub unsafe fn lock<T, R>(
     ptr: *mut T,
     priority: &Priority,
     ceiling: u8,
     _nvic_prio_bits: u8,
-    f: F,
-) -> R
-where
-    F: FnOnce(&mut T) -> R,
-{
+    f: impl FnOnce(&mut T) -> R,
+) -> R {
     let current = priority.get();
 
-    if priority.get() < ceiling {
+    if current < ceiling {
         priority.set(u8::MAX);
         let r = interrupt::free(|_| f(&mut *ptr));
         priority.set(current);
@@ -215,8 +163,7 @@ where
     }
 }
 
-#[cfg(armv7m)]
 #[inline]
-fn logical2hw(logical: u8, nvic_prio_bits: u8) -> u8 {
+pub fn logical2hw(logical: u8, nvic_prio_bits: u8) -> u8 {
     ((1 << nvic_prio_bits) - logical) << (8 - nvic_prio_bits)
 }
diff --git a/src/lib.rs b/src/lib.rs
index b0bf6689..acd8d433 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,8 @@
 //! Real Time For the Masses (RTFM) framework for ARM Cortex-M microcontrollers
 //!
+//! **HEADS UP** This is an **alpha** pre-release; there may be breaking changes in the API and
+//! semantics before a proper release is made.
+//!
 //! **IMPORTANT**: This crate is published as [`cortex-m-rtfm`] on crates.io but the name of the
 //! library is `rtfm`.
 //!
@@ -7,7 +10,7 @@
 //!
 //! The user level documentation can be found [here].
 //!
-//! [here]: https://japaric.github.io/cortex-m-rtfm/book/en/
+//! [here]: https://japaric.github.io/rtfm5/book/en/
 //!
 //! Don't forget to check the documentation of the [`#[app]`] attribute, which is the main component
 //! of the framework.
@@ -16,7 +19,7 @@
 //!
 //! # Minimum Supported Rust Version (MSRV)
 //!
-//! This crate is guaranteed to compile on stable Rust 1.31 (2018 edition) and up. It *might*
+//! This crate is guaranteed to compile on stable Rust 1.36 (2018 edition) and up. It *might*
 //! compile on older versions but that may change in any new patch release.
 //!
 //! # Semantic Versioning
@@ -36,12 +39,11 @@
 //! [`Instant`]: struct.Instant.html
 //! [`Duration`]: struct.Duration.html
 //!
-//! - `nightly`. Enabling this opt-in feature makes RTFM internally use the unstable
-//! `core::mem::MaybeUninit` API and unstable `const_fn` language feature to reduce static memory
-//! usage, runtime overhead and initialization overhead. This feature requires a nightly compiler
-//! and may stop working at any time!
+//! - `nightly`. Enabling this opt-in feature makes RTFM internally use the unstable `const_fn`
+//! language feature to reduce static memory usage, runtime overhead and initialization overhead.
+//! This feature requires a nightly compiler and may stop working at any time!
 
-#![cfg_attr(feature = "nightly", feature(maybe_uninit))]
+#![feature(maybe_uninit)]
 #![deny(missing_docs)]
 #![deny(warnings)]
 #![no_std]
@@ -132,7 +134,7 @@ pub struct Instant(i32);
 impl Instant {
     /// IMPLEMENTATION DETAIL. DO NOT USE
     #[doc(hidden)]
-    pub fn artificial(timestamp: i32) -> Self {
+    pub unsafe fn artificial(timestamp: i32) -> Self {
         Instant(timestamp)
     }
 
@@ -290,9 +292,7 @@ pub trait Mutex {
     type T;
 
     /// Creates a critical section and grants temporary access to the protected data
-    fn lock<R, F>(&mut self, f: F) -> R
-    where
-        F: FnOnce(&mut Self::T) -> R;
+    fn lock<R>(&mut self, f: impl FnOnce(&mut Self::T) -> R) -> R;
 }
 
 impl<'a, M> Mutex for &'a mut M
@@ -301,10 +301,7 @@ where
 {
     type T = M::T;
 
-    fn lock<R, F>(&mut self, f: F) -> R
-    where
-        F: FnOnce(&mut Self::T) -> R,
-    {
+    fn lock<R>(&mut self, f: impl FnOnce(&mut M::T) -> R) -> R {
         (**self).lock(f)
     }
 }
@@ -317,10 +314,7 @@ pub struct Exclusive<'a, T>(pub &'a mut T);
 impl<'a, T> Mutex for Exclusive<'a, T> {
     type T = T;
 
-    fn lock<R, F>(&mut self, f: F) -> R
-    where
-        F: FnOnce(&mut Self::T) -> R,
-    {
+    fn lock<R>(&mut self, f: impl FnOnce(&mut T) -> R) -> R {
         f(self.0)
     }
 }
diff --git a/src/tq.rs b/src/tq.rs
index 8d520518..8ca1bd3f 100644
--- a/src/tq.rs
+++ b/src/tq.rs
@@ -3,7 +3,7 @@ use core::cmp::{self, Ordering};
 use cortex_m::peripheral::{SCB, SYST};
 use heapless::{binary_heap::Min, ArrayLength, BinaryHeap};
 
-use crate::{Instant, Mutex};
+use crate::Instant;
 
 pub struct TimerQueue<T, N>
 where
@@ -43,11 +43,39 @@ where
             }
 
             // set SysTick pending
-            (*SCB::ptr()).icsr.write(1 << 26);
+            SCB::set_pendst();
         }
 
         self.queue.push_unchecked(nr);
     }
+
+    #[inline]
+    pub fn dequeue(&mut self) -> Option<(T, u8)> {
+        if let Some(instant) = self.queue.peek().map(|p| p.instant) {
+            let diff = instant.0.wrapping_sub(Instant::now().0);
+
+            if diff < 0 {
+                // task became ready
+                let nr = unsafe { self.queue.pop_unchecked() };
+
+                Some((nr.task, nr.index))
+            } else {
+                // set a new timeout
+                const MAX: u32 = 0x00ffffff;
+
+                self.syst.set_reload(cmp::min(MAX, diff as u32));
+
+                // start counting down from the new reload
+                self.syst.clear_current();
+
+                None
+            }
+        } else {
+            // the queue is empty
+            self.syst.disable_interrupt();
+            None
+        }
+    }
 }
 
 pub struct NotReady<T>
@@ -87,49 +115,3 @@ where
         Some(self.cmp(&other))
     }
 }
-
-#[inline(always)]
-pub fn isr<TQ, T, N, F>(mut tq: TQ, mut f: F)
-where
-    TQ: Mutex<T = TimerQueue<T, N>>,
-    T: Copy + Send,
-    N: ArrayLength<NotReady<T>>,
-    F: FnMut(T, u8),
-{
-    loop {
-        // XXX does `#[inline(always)]` improve performance or not?
-        let next = tq.lock(#[inline(always)]
-        |tq| {
-            if let Some(instant) = tq.queue.peek().map(|p| p.instant) {
-                let diff = instant.0.wrapping_sub(Instant::now().0);
-
-                if diff < 0 {
-                    // task became ready
-                    let m = unsafe { tq.queue.pop_unchecked() };
-
-                    Some((m.task, m.index))
-                } else {
-                    // set a new timeout
-                    const MAX: u32 = 0x00ffffff;
-
-                    tq.syst.set_reload(cmp::min(MAX, diff as u32));
-
-                    // start counting down from the new reload
-                    tq.syst.clear_current();
-
-                    None
-                }
-            } else {
-                // the queue is empty
-                tq.syst.disable_interrupt();
-                None
-            }
-        });
-
-        if let Some((task, index)) = next {
-            f(task, index)
-        } else {
-            return;
-        }
-    }
-}