Merge #88

88: make compilable on stable r=japaric a=japaric

This PR makes this crate compilable on stable when the "inline-asm" and "singleton" Cargo features
are disabled (they are enabled by default to maintain backwards compatibility).

The main change has been replacing almost (\*) all inline `asm!` invocations with FFI calls into
external assembly files.

(\*) Stuff that has not been converted into external assembly file and thus is not available on
stable:

- Reading the (A)PSR register (I'm not sure if this will work with the extra function call overhead)

- Reading and writing the Link Register (LR)

- Reading and writing the Program Counter (PC)

I would appreciate if someone checked that all the stuff that's now using FFI calls has the same
semantics as the inline `asm!` version.


Co-authored-by: Jorge Aparicio <jorge@japaric.io>

1 files changed, 27 insertions, 9 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 6af60d7..df0ccbb 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -5,31 +5,49 @@
 //! - Access to core peripherals like NVIC, SCB and SysTick.
 //! - Access to core registers like CONTROL, MSP and PSR.
 //! - Interrupt manipulation mechanisms
-//! - Safe wrappers around assembly instructions like `bkpt`
+//! - Safe wrappers around Cortex-M specific instructions like `bkpt`
+//!
+//! # Requirements
+//!
+//! To use this crate on the stable or beta channel `arm-none-eabi-gcc` needs to be installed and
+//! available in your `$PATH`.
+//!
+//! # Optional features
+//!
+//! ## `inline-asm`
+//!
+//! When this feature is enabled the implementation of all the functions inside the `asm` and
+//! `register` modules use inline assembly (`asm!`) instead of external assembly (FFI into separate
+//! assembly files compiled using `arm-none-eabi-gcc`). The advantages the enabling `inline-asm`
+//! are:
+//!
+//! - Reduced overhead. FFI eliminates the possibility of inlining so all operations include a
+//! function call overhead when `inline-asm` is not enabled.
+//!
+//! - `arm-none-eabi-gcc` is not required for building this crate.
+//!
+//! - Some of the `register` API only becomes available only when `inline-asm` is enabled. Check the
+//! API docs for details.
+//!
+//! The disadvantage is that `inline-asm` requires a nightly toolchain.
 
+#![cfg_attr(feature = "inline-asm", feature(asm))]
 #![deny(missing_docs)]
 #![deny(warnings)]
-#![feature(asm)]
-#![feature(const_fn)]
 #![no_std]
 
 extern crate aligned;
 extern crate bare_metal;
-extern crate untagged_option;
 extern crate volatile_register;
 
 #[macro_use]
 mod macros;
 
-#[macro_use]
 pub mod asm;
-pub mod exception;
 pub mod interrupt;
-// NOTE(target_arch) is for documentation purposes
-#[cfg(any(armv7m, target_arch = "x86_64"))]
+#[cfg(not(armv6m))]
 pub mod itm;
 pub mod peripheral;
 pub mod register;
 
 pub use peripheral::Peripherals;
-pub use untagged_option::UntaggedOption;