Merge #150

150: Dwt: Delay and stopwatch r=therealprof a=h2obrain

Implements "dwt cycle counter"-based `use embedded_hal::blocking::delay::{DelayMs, DelayUs};`
Additionally you can use it to measure execution times of code fragments.

### UPDATE2
Feel free to comment on which function names should change!
```rust
use crate::hal::{
    dwt::{ClockDiff, DelayS, DwtExt, StopWatch},
    prelude::*,
    stm32,
};
// Constrain DWT and DCB
let dwt = cp.DWT.constrain(cp.DCB, clocks);
// Create a (copy-/cloneable) delay instance
let delay = dwt.delay();
// DelayMs/DelayUs from hal
delay.delay_us(1000);
delay.delay_ms(1);
// DelayS from dwt.rs
delay.delay_s(0.0000005f32);
delay.delay_s(0.0000005f64);
// Measure some closures timing
let t = dwt.measure(|| delay.delay_ms(10));
let _t: f64 = t.as_secs_f64();
let _t: f32 = t.as_secs_f32();
let _t: u64 = t.as_nanos();
let _t: u32 = t.as_ticks();
// General stopwatch
let mut times = [0u32; 5]; // max 4 laps
let mut sw = self.stopwatch(&mut times, clocks);
sw.lap();
delay.delay_ms(10);
sw.lap();
sw.lap();
// Get all the lap times
{
    let mut lap = 1;
    while let Some(lap_time) = sw.lap_time(lap) {
        let _t = lap_time.as_secs_f64();
        lap += 1;
    }
}
```
### Iterators
A draft for iterators, which seems to need more code than I would have guessed, you can find here ([dwt.rs](https://github.com/h2obrain/stm32f4xx-hal/blob/dwt-stopwatch-iter/src/dwt.rs), [dwt-blinky.rs](https://github.com/h2obrain/stm32f4xx-hal/blob/dwt-stopwatch-iter/examples/dwt-blinky.rs))

### ClockDuration with from-functions

A ClockDuration with interchangeable types would be cool to do stuff like `delay.delay(ClockDuration::from_secs_f64(0.1));` along with this `let cd = dwt.measure(do_stuff); .. ; delay.delay(cd);`

A "the are no stupid solutions" implementation of this can found here ([dwt.rs](https://github.com/h2obrain/stm32f4xx-hal/blob/dwt-lazy-duration/src/dwt.rs), [dwt-blinky.rs](https://github.com/h2obrain/stm32f4xx-hal/blob/dwt-lazy-duration/examples/dwt-blinky.rs))


Co-authored-by: Oliver Meier <h2obrain@gmail.com>

Author: bors[bot]

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 - Implement `timer::Cancel` trait for `Timer<TIM>`.
+- Added DWT cycle counter based delay and stopwatch, including an example.
 
 ## [v0.8.0] - 2020-04-30
 

Cargo.toml

@@ -101,6 +101,10 @@ required-features = ["rt", "stm32f401", "usb_fs"]
 name = "delay-blinky"
 required-features = ["rt", "stm32f411"]
 
+[[example]]
+name = "dwt-blinky"
+required-features = ["rt", "stm32f429"]
+
 [[example]]
 name = "ssd1306-image"
 required-features = ["rt", "stm32f411"]

examples/dwt-blinky.rs

@@ -0,0 +1,71 @@
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+// Halt on panic
+use crate::hal::{
+    dwt::{ClockDuration, DwtExt},
+    prelude::*,
+    stm32,
+};
+use cortex_m;
+use cortex_m_rt::entry;
+use panic_halt as _;
+use stm32f4xx_hal as hal;
+
+#[entry]
+fn main() -> ! {
+    if let (Some(dp), Some(cp)) = (
+        stm32::Peripherals::take(),
+        cortex_m::peripheral::Peripherals::take(),
+    ) {
+        // Set up the LEDs. On the STM32F429I-DISC[O1] they are connected to pin PG13/14.
+        let gpiog = dp.GPIOG.split();
+        let mut led1 = gpiog.pg13.into_push_pull_output();
+        let mut led2 = gpiog.pg14.into_push_pull_output();
+
+        // Set up the system clock. We want to run at 48MHz for this one.
+        let rcc = dp.RCC.constrain();
+        let clocks = rcc.cfgr.sysclk(48.mhz()).freeze();
+
+        // Create a delay abstraction based on DWT cycle counter
+        let dwt = cp.DWT.constrain(cp.DCB, clocks);
+        let mut delay = dwt.delay();
+
+        // Create a stopwatch for maximum 9 laps
+        // Note: it starts immediately
+        let mut lap_times = [0u32; 10];
+        let mut sw = dwt.stopwatch(&mut lap_times);
+        loop {
+            // On for 1s, off for 1s.
+            led1.set_high().unwrap();
+            led2.set_low().unwrap();
+            delay.delay_ms(1000_u32);
+            sw.lap();
+            led1.set_low().unwrap();
+            led2.set_high().unwrap();
+            delay.delay_ms(900_u32);
+            // Also you can measure with almost clock precision
+            let cd: ClockDuration = dwt.measure(|| delay.delay_ms(100_u32));
+            let _t: u32 = cd.as_ticks(); // Should return 48MHz * 0.1s as u32
+            let _t: f32 = cd.as_secs_f32(); // Should return ~0.1s as a f32
+            let _t: f64 = cd.as_secs_f64(); // Should return ~0.1s as a f64
+            let _t: u64 = cd.as_nanos(); // Should return 100000000ns as a u64
+            sw.lap();
+
+            // Get all the lap times
+            {
+                let mut lap = 1;
+                while let Some(lap_time) = sw.lap_time(lap) {
+                    let _t = lap_time.as_secs_f64();
+                    lap += 1;
+                }
+            }
+
+            // Reset stopwatch
+            sw.reset();
+        }
+    }
+
+    loop {}
+}

src/dwt.rs

@@ -0,0 +1,200 @@
+//! Debug and trace and stuff
+
+use crate::rcc::Clocks;
+use crate::time::Hertz;
+use cortex_m::peripheral::{DCB, DWT};
+use embedded_hal::blocking::delay::{DelayMs, DelayUs};
+
+pub trait DwtExt {
+    fn constrain(self, dcb: DCB, clocks: Clocks) -> Dwt;
+}
+impl DwtExt for DWT {
+    /// Enable trace unit and cycle counter
+    fn constrain(mut self, mut dcb: DCB, clocks: Clocks) -> Dwt {
+        dcb.enable_trace();
+        self.enable_cycle_counter();
+        Dwt {
+            dwt: self,
+            dcb,
+            clocks,
+        }
+    }
+}
+
+pub struct Dwt {
+    dwt: DWT,
+    dcb: DCB,
+    clocks: Clocks,
+}
+impl Dwt {
+    /// Release the dwt and dcb control
+    /// # Safety
+    /// All instances of Delay and StopWatch become invalid after this
+    pub unsafe fn release(self) -> (DWT, DCB) {
+        (self.dwt, self.dcb)
+    }
+    /// Create a delay instance
+    pub fn delay(&self) -> Delay {
+        Delay {
+            clock: self.clocks.hclk(),
+        }
+    }
+    /// Create a stopwatch instance
+    /// # Arguments
+    /// * `times` - Array which will be holding the timings in ticks (max laps == times.len()-1)
+    pub fn stopwatch<'i>(&self, times: &'i mut [u32]) -> StopWatch<'i> {
+        StopWatch::new(times, self.clocks.hclk())
+    }
+    /// Measure cycles it takes to execute f
+    pub fn measure<F: FnOnce()>(&self, f: F) -> ClockDuration {
+        let mut times: [u32; 2] = [0; 2];
+        let mut sw = self.stopwatch(&mut times);
+        f();
+        sw.lap().lap_time(1).unwrap()
+    }
+}
+
+#[derive(Clone, Copy)]
+pub struct Delay {
+    clock: Hertz,
+}
+impl Delay {
+    /// Delay for ClockDuration::ticks
+    pub fn delay(duration: ClockDuration) {
+        let ticks = duration.ticks as u64;
+        Delay::delay_ticks(DWT::get_cycle_count(), ticks);
+    }
+    /// Delay ticks
+    /// NOTE DCB and DWT need to be set up for this to work, so it is private
+    fn delay_ticks(mut start: u32, ticks: u64) {
+        if ticks < (u32::MAX / 2) as u64 {
+            // Simple delay
+            let ticks = ticks as u32;
+            while (DWT::get_cycle_count().wrapping_sub(start)) < ticks {}
+        } else if ticks <= u32::MAX as u64 {
+            // Try to avoid race conditions by limiting delay to u32::MAX / 2
+            let mut ticks = ticks as u32;
+            ticks -= u32::MAX / 2;
+            while (DWT::get_cycle_count().wrapping_sub(start)) < u32::MAX / 2 {}
+            start -= u32::MAX / 2;
+            while (DWT::get_cycle_count().wrapping_sub(start)) < ticks {}
+        } else {
+            // Delay for ticks, then delay for rest * u32::MAX
+            let mut rest = (ticks >> 32) as u32;
+            let ticks = (ticks & u32::MAX as u64) as u32;
+            loop {
+                while (DWT::get_cycle_count().wrapping_sub(start)) < ticks {}
+                if rest == 0 {
+                    break;
+                }
+                rest -= 1;
+                while (DWT::get_cycle_count().wrapping_sub(start)) > ticks {}
+            }
+        }
+    }
+}
+
+// Implement DelayUs/DelayMs for various integer types
+impl<T: Into<u64>> DelayUs<T> for Delay {
+    fn delay_us(&mut self, us: T) {
+        // Convert us to ticks
+        let start = DWT::get_cycle_count();
+        let ticks = (us.into() * self.clock.0 as u64) / 1_000_000;
+        Delay::delay_ticks(start, ticks);
+    }
+}
+impl<T: Into<u64>> DelayMs<T> for Delay {
+    fn delay_ms(&mut self, ms: T) {
+        // Convert ms to ticks
+        let start = DWT::get_cycle_count();
+        let ticks = (ms.into() * self.clock.0 as u64) / 1_000;
+        Delay::delay_ticks(start, ticks);
+    }
+}
+
+/// Very simple stopwatch
+pub struct StopWatch<'l> {
+    times: &'l mut [u32],
+    timei: usize,
+    clock: Hertz,
+}
+impl<'l> StopWatch<'l> {
+    /// Create a new instance (Private because dwt/dcb should be set up)
+    /// # Arguments
+    /// * `times` - Array which will be holding the timings (max laps == times.len()-1)
+    /// * `clock` - The DWT cycle counters clock
+    fn new(times: &'l mut [u32], clock: Hertz) -> Self {
+        assert!(times.len() >= 2);
+        let mut sw = StopWatch {
+            times,
+            timei: 0,
+            clock,
+        };
+        sw.reset();
+        sw
+    }
+    /// Returns the numbers of laps recorded
+    pub fn lap_count(&self) -> usize {
+        self.timei
+    }
+    /// Resets recorded laps to 0 and sets 0 offset
+    pub fn reset(&mut self) {
+        self.timei = 0;
+        self.times[0] = DWT::get_cycle_count();
+    }
+    /// Record a new lap
+    /// NOTE If lap count exceeds maximum, the last lap is updated
+    pub fn lap(&mut self) -> &mut Self {
+        let c = DWT::get_cycle_count();
+        if self.timei < self.times.len() {
+            self.timei += 1;
+        }
+        self.times[self.timei] = c;
+        self
+    }
+    /// Calculate the time of lap n (n starting with 1)
+    /// NOTE Returns None if 'n' is out of range
+    pub fn lap_time(&self, n: usize) -> Option<ClockDuration> {
+        if (n < 1) || (self.timei < n) {
+            None
+        } else {
+            Some(ClockDuration {
+                ticks: self.times[n].wrapping_sub(self.times[n - 1]),
+                clock: self.clock,
+            })
+        }
+    }
+}
+
+/// Clock difference with capability to calculate SI units (s)
+#[derive(Clone, Copy)]
+pub struct ClockDuration {
+    ticks: u32,
+    clock: Hertz,
+}
+impl ClockDuration {
+    /// Returns ticks
+    pub fn as_ticks(self) -> u32 {
+        self.ticks
+    }
+    /// Returns calculated milliseconds as integer
+    pub fn as_millis(self) -> u64 {
+        self.ticks as u64 * 1_000 / self.clock.0 as u64
+    }
+    /// Returns calculated microseconds as integer
+    pub fn as_micros(self) -> u64 {
+        self.ticks as u64 * 1_000_000 / self.clock.0 as u64
+    }
+    /// Returns calculated nanoseconds as integer
+    pub fn as_nanos(self) -> u64 {
+        self.ticks as u64 * 1_000_000_000 / self.clock.0 as u64
+    }
+    /// Return calculated seconds as 32-bit float
+    pub fn as_secs_f32(self) -> f32 {
+        self.ticks as f32 / self.clock.0 as f32
+    }
+    /// Return calculated seconds as 64-bit float
+    pub fn as_secs_f64(self) -> f64 {
+        self.ticks as f64 / self.clock.0 as f64
+    }
+}

src/lib.rs

@@ -135,6 +135,8 @@ pub mod otg_hs;
 ))]
 pub mod rng;
 
+#[cfg(feature = "device-selected")]
+pub mod dwt;
 #[cfg(feature = "device-selected")]
 pub mod prelude;
 #[cfg(feature = "device-selected")]