Merge pull request #17 from japaric/ng

v0.2.0

Author: Jorge Aparicio

.travis.yml

@@ -1,6 +1,6 @@
 dist: trusty
 language: rust
-rust: nightly
+rust: nightly-2017-03-04
 services: docker
 sudo: required
 

CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- Semihosting functionality in the `semihosting` module.
+
+- `exception::Handlers` struct that represent the section of the vector table
+  that contains the exception handlers.
+
+- A default exception handler
+
+- A high level API for the NVIC peripheral.
+
+- Context local data.
+
+- `borrow`/`borrow_mut` methods to `Mutex` that replace `lock`.
+
+- API and macros to send bytes / (formatted) strings through ITM
+
+### Changed
+
+- [breaking-change] `StackFrame` has been renamed to `StackedRegisters` and
+  moved into the `exceptions` module.
+
+- [breaking-change] Core peripherals can now be modified via a `&-` reference
+  and are no longer `Sync`.
+
+- [breaking-change] `interrupt::free`'s closure now includes a critical section
+  token, `CriticalSection`.
+
+- [breaking-change] the core register API has been revamped for type safety.
+
+- The safety of assembly wrappers like `wfi` and `interrupt::free` has been
+  reviewed. In many cases, the functions are no longer unsafe.
+
+- [breaking-change] `bkpt!` has been turned into a function. It no longer
+  accepts an immediate value.
+
+### Removed
+
+- `vector_table` and its associated `struct`, `VectorTable`. It's not a good
+  idea to give people a simple way to call the exception handlers.
+
+- `Mutex`'s `lock` method as it's unsound. You could use it to get multiple
+  `&mut -` references to the wrapped data.
+
 ## [v0.1.6] - 2017-01-22
 
 ### Added
@@ -60,10 +104,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Functions to get the vector table
 - Wrappers over miscellaneous instructions like `bkpt`
 
-[Unreleased]: https://github.com/japaric/rustc-cfg/compare/v0.1.6...HEAD
-[v0.1.6]: https://github.com/japaric/rustc-cfg/compare/v0.1.5...v0.1.6
-[v0.1.5]: https://github.com/japaric/rustc-cfg/compare/v0.1.4...v0.1.5
-[v0.1.4]: https://github.com/japaric/rustc-cfg/compare/v0.1.3...v0.1.4
-[v0.1.3]: https://github.com/japaric/rustc-cfg/compare/v0.1.2...v0.1.3
-[v0.1.2]: https://github.com/japaric/rustc-cfg/compare/v0.1.1...v0.1.2
-[v0.1.1]: https://github.com/japaric/rustc-cfg/compare/v0.1.0...v0.1.1
+[Unreleased]: https://github.com/japaric/cortex-m/compare/v0.1.6...HEAD
+[v0.1.6]: https://github.com/japaric/cortex-m/compare/v0.1.5...v0.1.6
+[v0.1.5]: https://github.com/japaric/cortex-m/compare/v0.1.4...v0.1.5
+[v0.1.4]: https://github.com/japaric/cortex-m/compare/v0.1.3...v0.1.4
+[v0.1.3]: https://github.com/japaric/cortex-m/compare/v0.1.2...v0.1.3
+[v0.1.2]: https://github.com/japaric/cortex-m/compare/v0.1.1...v0.1.2
+[v0.1.1]: https://github.com/japaric/cortex-m/compare/v0.1.0...v0.1.1

Cargo.toml

@@ -6,7 +6,10 @@ keywords = ["arm", "cortex-m", "register", "peripheral"]
 license = "MIT OR Apache-2.0"
 name = "cortex-m"
 repository = "https://github.com/japaric/cortex-m"
-version = "0.1.6"
+version = "0.2.0"
 
 [dependencies]
-volatile-register = "0.1.0"
+volatile-register = "0.2.0"
+
+[dependencies.cortex-m-semihosting]
+version = "0.1.3"

build.rs

@@ -0,0 +1,9 @@
+use std::env;
+
+fn main() {
+    let target = env::var("TARGET").unwrap();
+
+    if target.starts_with("thumbv6m-") {
+        println!("cargo:rustc-cfg=armv6m")
+    }
+}

ci/install.sh

@@ -4,11 +4,16 @@ main() {
     curl https://sh.rustup.rs -sSf | \
         sh -s -- -y --default-toolchain $TRAVIS_RUST_VERSION
 
+    local tag=$(git ls-remote --tags --refs --exit-code https://github.com/japaric/cross \
+                       | cut -d/ -f3 \
+                       | grep -E '^v[0-9.]+$' \
+                       | sort --version-sort \
+                       | tail -n1)
     curl -LSfs http://japaric.github.io/trust/install.sh | \
         sh -s -- \
            --force \
            --git japaric/cross \
-           --tag v0.1.2 \
+           --tag $tag \
            --target x86_64-unknown-linux-musl \
            --to ~/.cargo/bin
 }

src/asm.rs

@@ -1,58 +1,60 @@
 //! Miscellaneous assembly instructions
 
-/// Puts the processor in Debug state. Debuggers can pick this up as a "breakpoint".
+/// Puts the processor in Debug state. Debuggers can pick this up as a
+/// "breakpoint".
 ///
-/// Optionally, an "immediate" value (in the 0-255 range) can be passed to `bkpt!`. The debugger can
-/// then read this value using the Program Counter (PC).
-#[cfg(target_arch = "arm")]
-#[macro_export]
-macro_rules! bkpt {
-    () => {
-        asm!("bkpt" :::: "volatile");
-    };
-    ($imm:expr) => {
-        asm!(concat!("bkpt #", stringify!($imm)) :::: "volatile");
-    };
+/// NOTE calling `bkpt` when the processor is not connected to a debugger will
+/// cause an exception
+#[inline(always)]
+pub fn bkpt() {
+    #[cfg(target_arch = "arm")]
+    unsafe {
+        asm!("bkpt"
+             :
+             :
+             :
+             : "volatile");
+    }
 }
 
-/// Puts the processor in Debug state. Debuggers can pick this up as a "breakpoint".
-///
-/// Optionally, an "immediate" value (in the 0-255 range) can be passed to `bkpt!`. The debugger can
-/// then read this value using the Program Counter (PC).
-#[cfg(not(target_arch = "arm"))]
-#[macro_export]
-macro_rules! bkpt {
-    () => {
-        asm!("nop" :::: "volatile");
-    };
-    ($e:expr) => {
-        asm!("nop" :::: "volatile");
-    };
+/// A no-operation. Useful to prevent delay loops from being optimized away.
+pub fn nop() {
+    unsafe {
+        asm!("nop"
+             :
+             :
+             :
+             : "volatile");
+    }
 }
-
-/// Wait for event
-pub unsafe fn wfe() {
+/// Wait For Event
+pub fn wfe() {
     match () {
         #[cfg(target_arch = "arm")]
-        () => asm!("wfe" :::: "volatile"),
+        () => unsafe {
+            asm!("wfe"
+                 :
+                 :
+                 :
+                 : "volatile")
+        },
         #[cfg(not(target_arch = "arm"))]
         () => {}
     }
 }
 
-/// Wait for interupt
-pub unsafe fn wfi() {
+/// Wait For Interrupt
+pub fn wfi() {
     match () {
         #[cfg(target_arch = "arm")]
-        () => asm!("wfi" :::: "volatile"),
+        () => unsafe{
+            asm!("wfi"
+                 :
+                 :
+                 :
+                 : "volatile")
+        },
         #[cfg(not(target_arch = "arm"))]
         () => {}
     }
 }
-
-/// A no-operation. Useful to stop delay loops being elided.
-pub fn nop() {
-    unsafe {
-        asm!("nop" :::: "volatile");
-    }
-}

src/ctxt.rs

@@ -0,0 +1,160 @@
+//! Interrupt / Exception context local data
+//!
+//! The main use case is safely adding state to exception / interrupt handlers.
+//!
+//! This is done in two stages, first you define a token that will appear in the
+//! interrupt handler signature; each handler will have its unique token. This
+//! token must be zero sized type because interrupt handlers' real signature is
+//! `fn()` and it must also implement the `Context` trait. You must also make
+//! sure that the token can't be constructed outside of the crate where it's
+//! defined.
+//!
+//! ```
+//! # use cortex_m::ctxt::Context;
+//! // This must be in a library crate
+//! /// Token unique to the TIM7 interrupt handler
+//! pub struct Tim7 { _0: () }
+//!
+//! unsafe impl Context for Tim7 {}
+//! ```
+//!
+//! Then in the application one can pin data to the interrupt handler using
+//! `Local`.
+//!
+//! ```
+//! # #![feature(const_fn)]
+//! # use std::cell::Cell;
+//! # use cortex_m::ctxt::{Context, Local};
+//! # struct Tim7;
+//! # unsafe impl Context for Tim7 {}
+//! // omitted: how to put this handler in the vector table
+//! extern "C" fn tim7(ctxt: Tim7) {
+//!     static STATE: Local<Cell<bool>, Tim7> = Local::new(Cell::new(false));
+//!
+//!     let state = STATE.borrow(&ctxt);
+//!
+//!     // toggle state
+//!     state.set(!state.get());
+//!
+//!     if state.get() {
+//!         // something
+//!     } else {
+//!         // something else
+//!     }
+//! }
+//! ```
+//!
+//! Note that due to the uniqueness of tokens, other handlers won't be able to
+//! access context local data. (Given that you got the signatures right)
+//!
+//! ```
+//! # #![feature(const_fn)]
+//! # use std::cell::Cell;
+//! # use cortex_m::ctxt::{Context, Local};
+//! # struct Tim3;
+//! # struct Tim4;
+//! static TIM3_DATA: Local<Cell<bool>, Tim3> = Local::new(Cell::new(false));
+//!
+//! extern "C" fn tim3(ctxt: Tim3) {
+//!     let data = TIM3_DATA.borrow(&ctxt);
+//! }
+//!
+//! extern "C" fn tim4(ctxt: Tim4) {
+//!     //let data = TIM3_DATA.borrow(&ctxt);
+//!     // ^ wouldn't work
+//! }
+//! # unsafe impl Context for Tim3 {}
+//! # fn main() {}
+//! ```
+//!
+//! To have the application use these tokenized function signatures, you can
+//! define, in a library, a `Handlers` struct that represents the vector table:
+//!
+//! ```
+//! # struct Tim1;
+//! # struct Tim2;
+//! # struct Tim3;
+//! # struct Tim4;
+//! # extern "C" fn default_handler<T>(_: T) {}
+//! #[repr(C)]
+//! pub struct Handlers {
+//!     tim1: extern "C" fn(Tim1),
+//!     tim2: extern "C" fn(Tim2),
+//!     tim3: extern "C" fn(Tim3),
+//!     tim4: extern "C" fn(Tim4),
+//!     /* .. */
+//! }
+//!
+//! pub const DEFAULT_HANDLERS: Handlers = Handlers {
+//!     tim1: default_handler,
+//!     tim2: default_handler,
+//!     tim3: default_handler,
+//!     tim4: default_handler,
+//!     /* .. */
+//! };
+//! ```
+//!
+//! Then have the user use that `struct` to register the interrupt handlers:
+//!
+//! ```
+//! # struct Tim3;
+//! # struct Handlers { tim3: extern "C" fn(Tim3), tim4: extern "C" fn(Tim3) }
+//! # const DEFAULT_HANDLERS: Handlers = Handlers { tim3: tim3, tim4: tim3 };
+//! extern "C" fn tim3(ctxt: Tim3) { /* .. */ }
+//!
+//! // override the TIM3 interrupt handler
+//! #[no_mangle]
+//! static _INTERRUPTS: Handlers = Handlers {
+//!     tim3: tim3, ..DEFAULT_HANDLERS
+//! };
+//! ```
+//!
+//! This pattern is implemented for exceptions in this crate. See
+//! `exception::Handlers` and `exception::DEFAULT_HANDLERS`.
+
+use core::marker::PhantomData;
+use core::cell::UnsafeCell;
+
+/// Data local to a context
+pub struct Local<T, Ctxt>
+where
+    Ctxt: Context,
+{
+    _ctxt: PhantomData<Ctxt>,
+    data: UnsafeCell<T>,
+}
+
+impl<T, Ctxt> Local<T, Ctxt>
+where
+    Ctxt: Context,
+{
+    /// Initializes context local data
+    pub const fn new(value: T) -> Self {
+        Local {
+            _ctxt: PhantomData,
+            data: UnsafeCell::new(value),
+        }
+    }
+
+    /// Acquires a reference to the context local data
+    pub fn borrow<'ctxt>(&'static self, _ctxt: &'ctxt Ctxt) -> &'ctxt T {
+        unsafe { &*self.data.get() }
+    }
+
+    /// Acquires a mutable reference to the context local data
+    pub fn borrow_mut<'ctxt>(
+        &'static self,
+        _ctxt: &'ctxt mut Ctxt,
+    ) -> &'ctxt mut T {
+        unsafe { &mut *self.data.get() }
+    }
+}
+
+unsafe impl<T, Ctxt> Sync for Local<T, Ctxt>
+where
+    Ctxt: Context,
+{
+}
+
+/// A token unique to a context
+pub unsafe trait Context {}