revise peripheral API

[japaric]

This PR changes the signature of many of the high level methods available on peripherals like
NVIC::get_priority. Additionally some instance methods have been turned into static methods. The
following guidelines have been used to apply the changes:

• If the method body contains a single, atomic read operation with no side effects (e.g. the read
  operation clears one of the bits of the register): the signature changed to make the method
  static, i.e. &self was removed from the signature.

• If the method involves writing to or a RMW operation on a register: the signature changed to take
  the singleton by &mut self reference.

• If the method involves only read operations where at least one of them modifies the value
  of a register: the signature changed to take the singleton by &mut self reference.

The rationale for this last guideline is that using &self, instead of &mut self, lets the user
(unintentionally) break abstractions in the presence of generators. Example below:

let peripherals = Peripherals::take().unwrap();
let syst = &peripherals.SYST;

// tasks
let mut a = || {
    loop {
        // yielding "busy wait"
        while !a.has_wrapped() {
            yield;
        }

        // do stuff
    }
};

let mut b = || {
    // ..

    // *NOTE* the problem is in the line below: this `is_counter_enabled` method reads the CSR
    // register and that read operation clears the COUNTFLAG bit of the register (if set), which is
    // the bit the `has_wrapped` method checks for.
    if syst.is_counter_enabled() {
        // ..
    }

    // ..
};

One more guideline was considered but the required conditions didn't apply to any of the existing
methods:

• If the method involves only non side effectful, non necessarily atomic read operations: the
  signature of the method should remain as &self.

The rationale for this guideline is that a static method (no self argument) wouldn't be
appropriate because that can result in a torn read if the read operation can be preempted by some
context that modifies the register.

In any case, this last guideline doesn't seem to apply well to the peripherals structs exposed by
this crate because they deref to a RegisterBlock that allows mutation through a &self
reference. When these two properties (the guideline and Deref<Target=RegisterBlock>) are mixed
the user can potentially break abstractions using generators (as shown in the syst example).

cc @hannobraun
closes #67

[homunkulus]

☔ The latest upstream changes (presumably #71) made this pull request unmergeable. Please resolve the merge conflicts.

[hannobraun]

I didn't have time for a full review. I only glanced over the code changes and didn't double-check your unsafe notes against the technicals manuals. Other than that and the broken examples, this looks good to me!

[hannobraun]

This example is broken. Fixed version:

//! ``` no_run
//! use cortex_m::peripheral::Peripherals;
//!
//! fn main() {
//!     let mut peripherals = Peripherals::take().unwrap();
//!     peripherals.DWT.enable_cycle_counter();
//! }
//! ```

[hannobraun]

This example is also broken. Fixed version:

//! ``` no_run
//! use cortex_m::peripheral::{
//!     DWT,
//!     Peripherals,
//! };
//!
//! fn main() {
//!     {
//!         let mut peripherals = Peripherals::take().unwrap();
//!         peripherals.DWT.enable_cycle_counter();
//!     } // all the peripheral singletons are destroyed here
//!
//!     // but this method can be called without a DWT instance
//!     let cyccnt = DWT::get_cycle_count();
//! }
//! ```

[hannobraun]

Also broken. Fixed version:

//! ``` no_run
//! use cortex_m::peripheral::{
//!     DWT,
//!     Peripherals,
//! };
//!
//! fn main() {
//!     {
//!         let mut peripherals = Peripherals::take().unwrap();
//!         peripherals.DWT.enable_cycle_counter();
//!     } // all the peripheral singletons are destroyed here
//!
//!     // actually safe because this is an atomic read with no side effects
//!     let cyccnt = unsafe { (*DWT::ptr()).cyccnt.read() };
//! }
//! ```

[hannobraun]

Should be "map to the same priority".

[japaric]

@hannobraun Thanks for the review!

@homunkulus r+

[homunkulus]

📌 Commit 5a19c39 has been approved by japaric

[homunkulus]

⌛ Testing commit 5a19c39 with merge 08c1320...

[homunkulus]

💔 Test failed - status-travis

[japaric]

@homunkulus r+

[homunkulus]

📌 Commit 47623ce has been approved by japaric

[homunkulus]

⌛ Testing commit 47623ce with merge 024527b...

[homunkulus]

☀️ Test successful - status-travis
Approved by: japaric
Pushing 024527b to master...