From 14fedeb3428d836d358a288fa4ed11547d64a35f Mon Sep 17 00:00:00 2001
From: Jorge Aparicio <jorge@japaric.io>
Date: Wed, 16 May 2018 01:15:44 +0200
Subject: [PATCH] WIP

---
 src/_impl/instant.rs |  2 --
 src/_impl/mod.rs     |  2 ++
 src/_impl/tq.rs      |  4 ++--
 src/lib.rs           | 21 +++++++++++----------
 src/resource.rs      | 17 +++++++++--------
 5 files changed, 24 insertions(+), 22 deletions(-)

diff --git a/src/_impl/instant.rs b/src/_impl/instant.rs
index 4df911f425..fb32d541ec 100644
--- a/src/_impl/instant.rs
+++ b/src/_impl/instant.rs
@@ -1,8 +1,6 @@
 use core::cmp::Ordering;
 use core::{ops, ptr};
 
-use cortex_m::peripheral::DWT;
-
 #[derive(Clone, Copy, Debug)]
 pub struct Instant(pub u32);
 
diff --git a/src/_impl/mod.rs b/src/_impl/mod.rs
index 90c28bd487..b77286cb7f 100644
--- a/src/_impl/mod.rs
+++ b/src/_impl/mod.rs
@@ -16,6 +16,7 @@ mod tq;
 pub type FreeQueue<N> = Queue<u8, N, u8>;
 pub type ReadyQueue<T, N> = Queue<(T, u8), N, u8>;
 
+#[allow(non_snake_case)]
 #[cfg(feature = "timer-queue")]
 pub struct Peripherals<'a> {
     pub CBP: CBP,
@@ -30,6 +31,7 @@ pub struct Peripherals<'a> {
     pub TPIU: TPIU,
 }
 
+#[allow(non_snake_case)]
 #[cfg(not(feature = "timer-queue"))]
 pub struct Peripherals {
     pub CBP: CBP,
diff --git a/src/_impl/tq.rs b/src/_impl/tq.rs
index 6cb5392d44..e1c9e0719e 100644
--- a/src/_impl/tq.rs
+++ b/src/_impl/tq.rs
@@ -3,7 +3,7 @@ use core::cmp::{self, Ordering};
 use cortex_m::peripheral::{SCB, SYST};
 use heapless::binary_heap::{BinaryHeap, Min};
 use heapless::ArrayLength;
-use typenum::{Max, Maximum, Unsigned};
+use typenum::{Max, Unsigned};
 
 use _impl::Instant;
 use resource::{Priority, Resource};
@@ -71,7 +71,7 @@ where
             }
 
             // set SysTick pending
-            unsafe { (*SCB::ptr()).icsr.write(1 << 26) }
+            (*SCB::ptr()).icsr.write(1 << 26);
         }
 
         self.queue.push_unchecked(m);
diff --git a/src/lib.rs b/src/lib.rs
index e5716061bd..69e122cb4a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,10 +1,12 @@
-// #![deny(missing_docs)]
-// #![deny(warnings)]
+//! Real Time for The Masses: high performance, predictable, bare metal task scheduler
+
 #![allow(warnings)]
+#![deny(missing_docs)]
+#![deny(warnings)]
 #![feature(const_fn)]
+#![feature(never_type)]
 #![feature(proc_macro)]
 #![feature(untagged_unions)]
-#![feature(never_type)]
 #![no_std]
 
 extern crate cortex_m;
@@ -12,11 +14,8 @@ extern crate cortex_m_rtfm_macros;
 extern crate heapless;
 extern crate typenum;
 
-use core::mem;
-
-use cortex_m::interrupt::{self, Nr};
+use cortex_m::interrupt;
 pub use cortex_m_rtfm_macros::app;
-use heapless::ring_buffer::RingBuffer;
 use typenum::consts::*;
 use typenum::Unsigned;
 
@@ -26,15 +25,17 @@ pub use resource::{Priority, Resource};
 pub mod _impl;
 mod resource;
 
-/// TODO
-pub fn atomic<R, P, F>(t: &mut Priority<P>, f: F) -> R
+/// Executes the given closure atomically
+///
+/// While the closure is being executed no new task can start
+pub fn atomic<R, P, F>(_p: &mut Priority<P>, f: F) -> R
 where
     F: FnOnce(&mut Priority<U255>) -> R,
     P: Unsigned,
 {
     unsafe {
         // Sanity check
-        debug_assert!(P::to_u8() <= 255);
+        debug_assert!(P::to_usize() <= 255);
 
         if P::to_u8() < 255 {
             interrupt::disable();
diff --git a/src/resource.rs b/src/resource.rs
index 05b6f6d0c8..1c23d00866 100644
--- a/src/resource.rs
+++ b/src/resource.rs
@@ -6,7 +6,7 @@ use cortex_m::register::basepri;
 use typenum::type_operators::IsGreaterOrEqual;
 use typenum::{Max, Maximum, True, Unsigned};
 
-/// TODO
+/// Token that represents the current priority level of a task
 pub struct Priority<N> {
     _not_send_or_sync: PhantomData<*const ()>,
     _n: PhantomData<N>,
@@ -22,22 +22,22 @@ impl<N> Priority<N> {
     }
 }
 
-/// TODO
+/// A resource shared between two or more tasks
 pub unsafe trait Resource {
     #[doc(hidden)]
     const NVIC_PRIO_BITS: u8;
 
-    /// TODO
+    /// The priority ceiling of the resource
     type Ceiling;
 
-    /// TODO
+    /// The data protected by the resource
     type Data: 'static + Send;
 
     // The `static mut` variable that the resource protects fs
     #[doc(hidden)]
     unsafe fn _var() -> &'static mut Self::Data;
 
-    /// TODO
+    /// Borrows the resource data for the span of the current priority
     #[inline(always)]
     fn borrow<'cs, P>(&'cs self, _p: &'cs Priority<P>) -> &'cs Self::Data
     where
@@ -46,7 +46,7 @@ pub unsafe trait Resource {
         unsafe { Self::_var() }
     }
 
-    /// TODO
+    /// Mutably borrows the resource data for the span of the current priority
     #[inline(always)]
     fn borrow_mut<'cs, P>(&'cs mut self, _p: &'cs Priority<P>) -> &'cs mut Self::Data
     where
@@ -55,7 +55,7 @@ pub unsafe trait Resource {
         unsafe { Self::_var() }
     }
 
-    /// TODO
+    /// Creates a critical section, by raising the task priority, to access the resource data
     #[inline(always)]
     fn claim<'cs, R, F, P>(&self, _p: &mut Priority<P>, f: F) -> R
     where
@@ -79,7 +79,8 @@ pub unsafe trait Resource {
         }
     }
 
-    /// TODO
+    /// Creates a critical section, by raising the task priority, to mutably access the resource
+    /// data
     #[inline(always)]
     fn claim_mut<'cs, R, F, P>(&mut self, _p: &mut Priority<P>, f: F) -> R
     where