From a452700628e352e6ac01da9e16223a47752ca860 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Sun, 21 Apr 2019 20:02:59 +0200 Subject: 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`. --- src/export.rs | 113 ++++++++++++++++------------------------------------------ src/lib.rs | 32 +++++++---------- src/tq.rs | 78 ++++++++++++++++------------------------ 3 files changed, 73 insertions(+), 150 deletions(-) (limited to 'src') diff --git a/src/export.rs b/src/export.rs index cf7293b..93a92fc 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 = Queue; -pub type ReadyQueue = Queue<(T, u8), N, usize, SingleCore>; +pub type FreeQueue = Queue; +pub type ReadyQueue = Queue<(T, u8), N, u8, SingleCore>; #[cfg(armv7m)] #[inline(always)] -pub fn run(f: F) +pub fn run(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) +pub fn run(_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 { - // we newtype so the end-user doesn't need `#![feature(maybe_uninit)]` in their code inner: core::mem::MaybeUninit, } -#[cfg(feature = "nightly")] impl MaybeUninit { pub const fn uninit() -> Self { MaybeUninit { @@ -86,61 +89,12 @@ impl MaybeUninit { 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 { - value: Option, -} - -#[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 MaybeUninit { - 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( +pub unsafe fn lock( 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( +pub unsafe fn lock( 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 b0bf668..acd8d43 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(&mut self, f: F) -> R - where - F: FnOnce(&mut Self::T) -> R; + fn lock(&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(&mut self, f: F) -> R - where - F: FnOnce(&mut Self::T) -> R, - { + fn lock(&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(&mut self, f: F) -> R - where - F: FnOnce(&mut Self::T) -> R, - { + fn lock(&mut self, f: impl FnOnce(&mut T) -> R) -> R { f(self.0) } } diff --git a/src/tq.rs b/src/tq.rs index 8d52051..8ca1bd3 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 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 @@ -87,49 +115,3 @@ where Some(self.cmp(&other)) } } - -#[inline(always)] -pub fn isr(mut tq: TQ, mut f: F) -where - TQ: Mutex>, - T: Copy + Send, - N: ArrayLength>, - 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; - } - } -} -- cgit v1.2.3