Merge #335

335: Timer delay r=therealprof a=burrbull

Slightly improved and rebased #309 

Co-authored-by: Danilo Bargen <mail@dbrgn.ch>
Co-authored-by: Andrey Zgarbul <zgarbul.andrey@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added support for I2S communication using SPI peripherals, and two examples [#265]
 - Added support for some LCD controllers using the Flexible Static Memory
   Controller / Flexible Memory Controller [#297]
+- Added `DelayMs` / `DelayUs` impls for TIM2/TIM5 [#309]
 - Added an example for using the new FSMC interface with the provided
   `display-interface` driver and the `st7789` driver on a F413Discovery board [#302]
 - Derive `Eq`, `PartialEq`, `Copy` and `Clone` for error types
@@ -34,6 +35,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 [#265]: https://github.com/stm32-rs/stm32f4xx-hal/pull/265
 [#297]: https://github.com/stm32-rs/stm32f4xx-hal/pull/297
 [#302]: https://github.com/stm32-rs/stm32f4xx-hal/pull/302
+[#309]: https://github.com/stm32-rs/stm32f4xx-hal/pull/309
 [#313]: https://github.com/stm32-rs/stm32f4xx-hal/pull/313
 [#318]: https://github.com/stm32-rs/stm32f4xx-hal/pull/318
 

Cargo.toml

@@ -336,7 +336,11 @@ name = "sd"
 required-features = ["rt", "stm32f405", "sdio-host"]
 
 [[example]]
-name = "delay-blinky"
+name = "delay-syst-blinky"
+required-features = ["rt", "stm32f411"]
+
+[[example]]
+name = "delay-timer-blinky"
 required-features = ["rt", "stm32f411"]
 
 [[example]]

README.md

@@ -55,7 +55,7 @@ use the bsp as BSP for your project.
 
 Otherwise, create a new Rust project as you usually do with `cargo init`. The
 "hello world" of embedded development is usually to blink a LED. The code to do
-so is available in [examples/delay-blinky.rs](examples/delay-blinky.rs).
+so is available in [examples/delay-syst-blinky.rs](examples/delay-syst-blinky.rs).
 Copy that file to the `main.rs` of your project.
 
 You also need to add some dependencies to your `Cargo.toml`:

examples/delay-blinky.rs renamed to examples/delay-syst-blinky.rs

@@ -1,3 +1,5 @@
+//! Demonstrate the use of a blocking `Delay` using the SYST (sysclock) timer.
+
 #![deny(unsafe_code)]
 #![no_main]
 #![no_std]

examples/delay-timer-blinky.rs

@@ -0,0 +1,43 @@
+//! Demonstrate the use of a blocking `Delay` using TIM5 general-purpose timer.
+
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+// Halt on panic
+use panic_halt as _; // panic handler
+
+use cortex_m;
+use cortex_m_rt::entry;
+use stm32f4xx_hal as hal;
+
+use crate::hal::{prelude::*, stm32};
+
+#[entry]
+fn main() -> ! {
+    if let (Some(dp), Some(_cp)) = (
+        stm32::Peripherals::take(),
+        cortex_m::peripheral::Peripherals::take(),
+    ) {
+        // Set up the LED. On the Mini-F4 it's connected to pin PC13.
+        let gpioc = dp.GPIOC.split();
+        let mut led = gpioc.pc13.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 general-pupose 32-bit timer TIM5
+        let mut delay = hal::delay::Delay::tim5(dp.TIM5, clocks);
+
+        loop {
+            // On for 1s, off for 1s.
+            led.set_high();
+            delay.delay_ms(1_000_u32);
+            led.set_low();
+            delay.delay_us(1_000_000_u32);
+        }
+    }
+
+    loop {}
+}

src/delay/mod.rs

@@ -0,0 +1,15 @@
+//! Delays
+
+mod syst;
+
+use cortex_m::peripheral::SYST;
+
+use crate::rcc::Clocks;
+
+/// Timer as a delay provider (SysTick by default)
+pub struct Delay<T = SYST> {
+    tim: T,
+    clocks: Clocks,
+}
+
+mod timer;

src/delay.rs renamed to src/delay/syst.rs

@@ -1,4 +1,4 @@
-//! Delays
+//! System timer (SysTick) as a delay provider.
 
 use cast::u32;
 use cortex_m::peripheral::syst::SystClkSource;
@@ -7,18 +7,13 @@ use cortex_m::peripheral::SYST;
 use crate::rcc::Clocks;
 use embedded_hal::blocking::delay::{DelayMs, DelayUs};
 
-/// System timer (SysTick) as a delay provider
-pub struct Delay {
-    clocks: Clocks,
-    syst: SYST,
-}
+use super::Delay;
 
-impl Delay {
+impl Delay<SYST> {
     /// Configures the system timer (SysTick) as a delay provider
-    pub fn new(mut syst: SYST, clocks: Clocks) -> Self {
-        syst.set_clock_source(SystClkSource::External);
-
-        Delay { clocks, syst }
+    pub fn new(mut tim: SYST, clocks: Clocks) -> Self {
+        tim.set_clock_source(SystClkSource::External);
+        Self { tim, clocks }
     }
 
     #[deprecated(since = "0.10.0", note = "Please use release instead")]
@@ -28,29 +23,29 @@ impl Delay {
 
     /// Releases the system timer (SysTick) resource
     pub fn release(self) -> SYST {
-        self.syst
+        self.tim
     }
 }
 
-impl DelayMs<u32> for Delay {
+impl DelayMs<u32> for Delay<SYST> {
     fn delay_ms(&mut self, ms: u32) {
         self.delay_us(ms * 1_000);
     }
 }
 
-impl DelayMs<u16> for Delay {
+impl DelayMs<u16> for Delay<SYST> {
     fn delay_ms(&mut self, ms: u16) {
         self.delay_ms(u32(ms));
     }
 }
 
-impl DelayMs<u8> for Delay {
+impl DelayMs<u8> for Delay<SYST> {
     fn delay_ms(&mut self, ms: u8) {
         self.delay_ms(u32(ms));
     }
 }
 
-impl DelayUs<u32> for Delay {
+impl DelayUs<u32> for Delay<SYST> {
     fn delay_us(&mut self, us: u32) {
         // The SysTick Reload Value register supports values between 1 and 0x00FFFFFF.
         const MAX_RVR: u32 = 0x00FF_FFFF;
@@ -64,27 +59,27 @@ impl DelayUs<u32> for Delay {
                 MAX_RVR
             };
 
-            self.syst.set_reload(current_rvr);
-            self.syst.clear_current();
-            self.syst.enable_counter();
+            self.tim.set_reload(current_rvr);
+            self.tim.clear_current();
+            self.tim.enable_counter();
 
             // Update the tracking variable while we are waiting...
             total_rvr -= current_rvr;
 
-            while !self.syst.has_wrapped() {}
+            while !self.tim.has_wrapped() {}
 
-            self.syst.disable_counter();
+            self.tim.disable_counter();
         }
     }
 }
 
-impl DelayUs<u16> for Delay {
+impl DelayUs<u16> for Delay<SYST> {
     fn delay_us(&mut self, us: u16) {
         self.delay_us(u32(us))
     }
 }
 
-impl DelayUs<u8> for Delay {
+impl DelayUs<u8> for Delay<SYST> {
     fn delay_us(&mut self, us: u8) {
         self.delay_us(u32(us))
     }

src/delay/timer.rs

@@ -0,0 +1,162 @@
+//! Delay implementation based on general-purpose 32 bit timers.
+//!
+//! TIM2 and TIM5 are a general purpose 32-bit auto-reload up/downcounter with
+//! a 16-bit prescaler.
+
+use core::cmp::max;
+
+use cast::{u16, u32};
+use embedded_hal::blocking::delay::{DelayMs, DelayUs};
+
+use crate::{
+    pac::{self, RCC},
+    rcc::{Clocks, Enable, Reset},
+};
+
+use super::Delay;
+
+macro_rules! hal {
+    ($($TIM:ty: ($tim:ident, $waitfn:ident),)+) => {
+        $(
+            fn $waitfn(tim: &mut $TIM, prescaler: u16, auto_reload_register: u32) {
+                // Write Prescaler (PSC)
+                tim.psc.write(|w| w.psc().bits(prescaler));
+
+                // Write Auto-Reload Register (ARR)
+                // Note: Make it impossible to set the ARR value to 0, since this
+                // would cause an infinite loop.
+                tim.arr.write(|w| unsafe { w.bits(max(1, auto_reload_register)) });
+
+                // Trigger update event (UEV) in the event generation register (EGR)
+                // in order to immediately apply the config
+                tim.cr1.modify(|_, w| w.urs().set_bit());
+                tim.egr.write(|w| w.ug().set_bit());
+                tim.cr1.modify(|_, w| w.urs().clear_bit());
+
+                // Configure the counter in one-pulse mode (counter stops counting at
+                // the next updateevent, clearing the CEN bit) and enable the counter.
+                tim.cr1.write(|w| w.opm().set_bit().cen().set_bit());
+
+                // Wait for CEN bit to clear
+                while tim.cr1.read().cen().is_enabled() { /* wait */ }
+            }
+
+            impl Delay<$TIM> {
+                /// Configures the timer as a delay provider
+                pub fn $tim(tim: $TIM, clocks: Clocks) -> Self {
+                    unsafe {
+                        //NOTE(unsafe) this reference will only be used for atomic writes with no side effects
+                        let rcc = &(*RCC::ptr());
+
+                        <$TIM>::enable(rcc);
+                        <$TIM>::reset(rcc);
+                    }
+
+                    // Enable one-pulse mode (counter stops counting at the next update
+                    // event, clearing the CEN bit)
+                    tim.cr1.modify(|_, w| w.opm().enabled());
+
+                    Self { tim, clocks }
+                }
+
+                /// Releases the timer resource
+                pub fn free(self) -> $TIM {
+                    self.tim
+                }
+            }
+
+            impl DelayUs<u32> for Delay<$TIM> {
+                /// Sleep for up to 2^32-1 microseconds (~71 minutes).
+                fn delay_us(&mut self, us: u32) {
+                    // Set up prescaler so that a tick takes exactly 1 µs.
+                    //
+                    // For example, if the clock is set to 48 MHz, with a prescaler of 48
+                    // we'll get ticks that are 1 µs long. This means that we can write the
+                    // delay value directly to the auto-reload register (ARR).
+                    let psc = u16(self.clocks.pclk1().0 / 1_000_000)
+                        .expect("Prescaler does not fit in u16");
+                    let arr = us;
+                    $waitfn(&mut self.tim, psc, arr);
+                }
+            }
+
+            impl DelayUs<u16> for Delay<$TIM> {
+                /// Sleep for up to 2^16-1 microseconds (~65 milliseconds).
+                fn delay_us(&mut self, us: u16) {
+                    // See DelayUs<u32> for explanations.
+                    let psc = u16(self.clocks.pclk1().0 / 1_000_000)
+                        .expect("Prescaler does not fit in u16");
+                    let arr = u32(us);
+                    $waitfn(&mut self.tim, psc, arr);
+                }
+            }
+
+            impl DelayMs<u32> for Delay<$TIM> {
+                /// Sleep for up to (2^32)/2-1 milliseconds (~24 days).
+                /// If the `ms` value is larger than 2147483647, the code will panic.
+                fn delay_ms(&mut self, ms: u32) {
+                    // See next section for explanation why the usable range is reduced.
+                    assert!(ms <= 2_147_483_647); // (2^32)/2-1
+
+                    // Set up prescaler so that a tick takes exactly 0.5 ms.
+                    //
+                    // For example, if the clock is set to 48 MHz, with a prescaler of 24'000
+                    // we'll get ticks that are 0.5 ms long. This means that we can write the
+                    // delay value multipled by two to the auto-reload register (ARR).
+                    //
+                    // Note that we cannot simply use a prescaler value where the tick corresponds
+                    // to 1 ms, because then a clock of 100 MHz would correspond to a prescaler
+                    // value of 100'000, which doesn't fit in the 16-bit PSC register.
+                    //
+                    // Unfortunately this means that only one half of the full 32-bit range
+                    // can be used, but 24 days should be plenty of usable delay time.
+                    let psc = u16(self.clocks.pclk1().0 / 1000 / 2)
+                        .expect("Prescaler does not fit in u16");
+
+                    // Since PSC = 0.5 ms, double the value for the ARR
+                    let arr = ms << 1;
+
+                    $waitfn(&mut self.tim, psc, arr);
+                }
+            }
+
+            impl DelayMs<u16> for Delay<$TIM> {
+                /// Sleep for up to (2^16)-1 milliseconds (~65 seconds).
+                fn delay_ms(&mut self, ms: u16) {
+                    // See DelayMs<u32> for explanations. Since the value range is only 16 bit,
+                    // we don't need an assert here.
+                    let psc = u16(self.clocks.pclk1().0 / 1000 / 2)
+                        .expect("Prescaler does not fit in u16");
+                    let arr = u32(ms) << 1;
+                    $waitfn(&mut self.tim, psc, arr);
+                }
+            }
+        )+
+    }
+}
+
+hal! {
+    pac::TIM5: (tim5, wait_tim5),
+}
+
+#[cfg(any(
+    feature = "stm32f401",
+    feature = "stm32f405",
+    feature = "stm32f407",
+    feature = "stm32f411",
+    feature = "stm32f412",
+    feature = "stm32f413",
+    feature = "stm32f415",
+    feature = "stm32f417",
+    feature = "stm32f423",
+    feature = "stm32f427",
+    feature = "stm32f429",
+    feature = "stm32f437",
+    feature = "stm32f439",
+    feature = "stm32f446",
+    feature = "stm32f469",
+    feature = "stm32f479"
+))]
+hal! {
+    pac::TIM2: (tim2, wait_tim2),
+}