Merge #337

bors[bot] · burrbull · web-flow · commit f05b81e2746c · 2021-07-10T16:02:47.000Z
337: Timer rework r=therealprof a=burrbull



Co-authored-by: Andrey Zgarbul &lt;zgarbul.andrey@gmail.com&gt;
Co-authored-by: Zgarbul Andrey &lt;zgarbul.andrey@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -42,6 +42,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Changed
 
+- [breaking-change] `Timer::new` now just initializes peripheral.
+  Use `.start_count_down` to start count, `pwm` or `delay` on `Timer` struct.
 - Add `Spi::new`, `I2s::new, `spi::Instance` and deprecate `Spi:spix`,
   deprecate `Serial::usartx`, remove deprecated `I2c::i2cx`
 - Deprecate `free` in favour of `release`
diff --git a/examples/analog-stopwatch-with-spi-ssd1306.rs b/examples/analog-stopwatch-with-spi-ssd1306.rs
@@ -17,7 +17,7 @@ use crate::hal::{
     rcc::{Clocks, Rcc},
     spi::Spi,
     stm32,
-    timer::{Event, Timer},
+    timer::{CountDownTimer, Event, Timer},
 };
 
 use arrayvec::ArrayString;
@@ -47,7 +47,8 @@ use ssd1306::{prelude::*, Builder};
 // Set up global state. It's all mutexed up for concurrency safety.
 static ELAPSED_MS: Mutex<Cell<u32>> = Mutex::new(Cell::new(0u32));
 static ELAPSED_RESET_MS: Mutex<Cell<u32>> = Mutex::new(Cell::new(0u32));
-static TIMER_TIM2: Mutex<RefCell<Option<Timer<stm32::TIM2>>>> = Mutex::new(RefCell::new(None));
+static TIMER_TIM2: Mutex<RefCell<Option<CountDownTimer<stm32::TIM2>>>> =
+    Mutex::new(RefCell::new(None));
 static STATE: Mutex<Cell<StopwatchState>> = Mutex::new(Cell::new(StopwatchState::Ready));
 static BUTTON: Mutex<RefCell<Option<PA0<Input<PullDown>>>>> = Mutex::new(RefCell::new(None));
 
@@ -116,7 +117,7 @@ fn main() -> ! {
 
     let dc = gpioe.pe3.into_push_pull_output();
     let mut ss = gpioe.pe4.into_push_pull_output();
-    let mut delay = hal::delay::Delay::new(cp.SYST, clocks);
+    let mut delay = hal::delay::Delay::new(cp.SYST, &clocks);
 
     ss.set_high();
     delay.delay_ms(100_u32);
@@ -129,7 +130,7 @@ fn main() -> ! {
     disp.flush().unwrap();
 
     // Create a 1ms periodic interrupt from TIM2
-    let mut timer = Timer::tim2(dp.TIM2, 1.khz(), clocks);
+    let mut timer = Timer::new(dp.TIM2, &clocks).start_count_down(1.hz());
     timer.listen(Event::TimeOut);
 
     free(|cs| {
diff --git a/examples/blinky-timer-irq.rs b/examples/blinky-timer-irq.rs
@@ -14,7 +14,7 @@ use crate::hal::{
     gpio::{gpioa, Output, PushPull},
     prelude::*,
     stm32::{interrupt, Interrupt, Peripherals, TIM2},
-    timer::{Event, Timer},
+    timer::{CountDownTimer, Event, Timer},
 };
 
 use core::cell::RefCell;
@@ -36,14 +36,14 @@ type LEDPIN = gpioa::PA5<Output<PushPull>>;
 static G_LED: Mutex<RefCell<Option<LEDPIN>>> = Mutex::new(RefCell::new(None));
 
 // Make timer interrupt registers globally available
-static G_TIM: Mutex<RefCell<Option<Timer<TIM2>>>> = Mutex::new(RefCell::new(None));
+static G_TIM: Mutex<RefCell<Option<CountDownTimer<TIM2>>>> = Mutex::new(RefCell::new(None));
 
 // Define an interupt handler, i.e. function to call when interrupt occurs.
 // This specific interrupt will "trip" when the timer TIM2 times out
 #[interrupt]
 fn TIM2() {
     static mut LED: Option<LEDPIN> = None;
-    static mut TIM: Option<Timer<TIM2>> = None;
+    static mut TIM: Option<CountDownTimer<TIM2>> = None;
 
     let led = LED.get_or_insert_with(|| {
         cortex_m::interrupt::free(|cs| {
@@ -79,7 +79,7 @@ fn main() -> ! {
     cortex_m::interrupt::free(|cs| *G_LED.borrow(cs).borrow_mut() = Some(led));
 
     // Set up a timer expiring after 1s
-    let mut timer = Timer::tim2(dp.TIM2, 1.hz(), clocks);
+    let mut timer = Timer::new(dp.TIM2, &clocks).start_count_down(1.hz());
 
     // Generate an interrupt when the timer expires
     timer.listen(Event::TimeOut);
diff --git a/examples/delay-syst-blinky.rs b/examples/delay-syst-blinky.rs
@@ -28,7 +28,7 @@ fn main() -> ! {
         let clocks = rcc.cfgr.sysclk(48.mhz()).freeze();
 
         // Create a delay abstraction based on SysTick
-        let mut delay = hal::delay::Delay::new(cp.SYST, clocks);
+        let mut delay = hal::delay::Delay::new(cp.SYST, &clocks);
 
         loop {
             // On for 1s, off for 1s.
diff --git a/examples/delay-timer-blinky.rs b/examples/delay-timer-blinky.rs
@@ -28,7 +28,7 @@ fn main() -> ! {
         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);
+        let mut delay = hal::delay::Delay::tim5(dp.TIM5, &clocks);
 
         loop {
             // On for 1s, off for 1s.
diff --git a/examples/f413disco_lcd_ferris.rs b/examples/f413disco_lcd_ferris.rs
@@ -746,7 +746,7 @@ fn main() -> ! {
         gpioe.pe5.into_push_pull_output().set_high();
 
         // Get delay provider
-        let mut delay = Delay::new(cp.SYST, clocks);
+        let mut delay = Delay::new(cp.SYST, &clocks);
 
         // Set up timing
         let write_timing = Timing::default().data(3).address_setup(3).bus_turnaround(0);
diff --git a/examples/i2s-audio-out-dma.rs b/examples/i2s-audio-out-dma.rs
@@ -103,7 +103,7 @@ fn main() -> ! {
     let gpioc = dp.GPIOC.split();
     let gpiod = dp.GPIOD.split();
 
-    let mut delay = Delay::new(cp.SYST, clocks);
+    let mut delay = Delay::new(cp.SYST, &clocks);
 
     let i2c = I2c::new(
         dp.I2C1,
diff --git a/examples/i2s-audio-out.rs b/examples/i2s-audio-out.rs
@@ -100,7 +100,7 @@ fn main() -> ! {
     // The 86 MHz frequency can be divided to get a sample rate very close to 48 kHz.
     let clocks = rcc.cfgr.use_hse(8.mhz()).i2s_clk(86.mhz()).freeze();
 
-    let mut delay = Delay::new(cp.SYST, clocks);
+    let mut delay = Delay::new(cp.SYST, &clocks);
 
     let i2c = I2c::new(
         dp.I2C1,
diff --git a/examples/pwm.rs b/examples/pwm.rs
@@ -6,19 +6,19 @@
 use panic_halt as _;
 
 use cortex_m_rt::entry;
-use stm32f4xx_hal::{prelude::*, pwm, stm32};
+use stm32f4xx_hal::{pac, prelude::*, timer::Timer};
 
 #[entry]
 fn main() -> ! {
-    if let Some(dp) = stm32::Peripherals::take() {
+    if let Some(dp) = pac::Peripherals::take() {
         // Set up the system clock.
         let rcc = dp.RCC.constrain();
         let clocks = rcc.cfgr.freeze();
 
         let gpioa = dp.GPIOA.split();
         let channels = (gpioa.pa8.into_alternate(), gpioa.pa9.into_alternate());
 
-        let pwm = pwm::tim1(dp.TIM1, channels, clocks, 20u32.khz());
+        let pwm = Timer::new(dp.TIM1, &clocks).pwm(channels, 20u32.khz());
         let (mut ch1, _ch2) = pwm;
         let max_duty = ch1.get_max_duty();
         ch1.set_duty(max_duty / 2);
diff --git a/examples/qei.rs b/examples/qei.rs
@@ -32,7 +32,7 @@ fn main() -> ! {
     let clocks = rcc.cfgr.freeze();
 
     // Create a delay abstraction based on SysTick.
-    let mut delay = Delay::new(cp.SYST, clocks);
+    let mut delay = Delay::new(cp.SYST, &clocks);
 
     let gpioa = dp.GPIOA.split();
 
diff --git a/examples/rng-display.rs b/examples/rng-display.rs
@@ -61,7 +61,7 @@ fn main() -> ! {
             .sysclk(128.mhz())
             .freeze();
 
-        let mut delay_source = hal::delay::Delay::new(cp.SYST, clocks);
+        let mut delay_source = hal::delay::Delay::new(cp.SYST, &clocks);
 
         // Set up I2C1: SCL is PB8 and SDA is PB9; they are set to Alternate Function 4
         // as per the STM32F407 datasheet. Pin assignment as per the
diff --git a/examples/sd.rs b/examples/sd.rs
@@ -30,7 +30,7 @@ fn main() -> ! {
 
     assert!(clocks.is_pll48clk_valid());
 
-    let mut delay = delay::Delay::new(core.SYST, clocks);
+    let mut delay = delay::Delay::new(core.SYST, &clocks);
 
     let gpioc = device.GPIOC.split();
     let gpiod = device.GPIOD.split();
diff --git a/examples/serial-9bit.rs b/examples/serial-9bit.rs
@@ -55,7 +55,7 @@ fn main() -> ! {
 
     let clocks = rcc.cfgr.use_hse(8.mhz()).freeze();
 
-    let mut delay = hal::delay::Delay::new(cp.SYST, clocks);
+    let mut delay = hal::delay::Delay::new(cp.SYST, &clocks);
 
     // define RX/TX pins
     let tx_pin = gpioa.pa2.into_alternate();
diff --git a/examples/serial.rs b/examples/serial.rs
@@ -21,7 +21,7 @@ fn main() -> ! {
 
     let clocks = rcc.cfgr.use_hse(8.mhz()).freeze();
 
-    let mut delay = hal::delay::Delay::new(cp.SYST, clocks);
+    let mut delay = hal::delay::Delay::new(cp.SYST, &clocks);
 
     // define RX/TX pins
     let tx_pin = gpioa.pa2.into_alternate();
diff --git a/examples/st7789-lcd.rs b/examples/st7789-lcd.rs
@@ -49,7 +49,7 @@ fn main() -> ! {
     // Make HCLK faster to allow updating the display more quickly
     let clocks = rcc.cfgr.hclk(100.mhz()).freeze();
 
-    let mut delay = Delay::new(cp.SYST, clocks);
+    let mut delay = Delay::new(cp.SYST, &clocks);
 
     let gpiod = dp.GPIOD.split();
     let gpioe = dp.GPIOE.split();
diff --git a/examples/stopwatch-with-ssd1306-and-interrupts.rs b/examples/stopwatch-with-ssd1306-and-interrupts.rs
@@ -28,7 +28,7 @@ use crate::hal::{
     prelude::*,
     rcc::{Clocks, Rcc},
     stm32,
-    timer::{Event, Timer},
+    timer::{CountDownTimer, Event, Timer},
 };
 use arrayvec::ArrayString;
 use core::cell::{Cell, RefCell};
@@ -46,7 +46,8 @@ use ssd1306::{prelude::*, Builder, I2CDIBuilder};
 
 // Set up global state. It's all mutexed up for concurrency safety.
 static ELAPSED_MS: Mutex<Cell<u32>> = Mutex::new(Cell::new(0u32));
-static TIMER_TIM2: Mutex<RefCell<Option<Timer<stm32::TIM2>>>> = Mutex::new(RefCell::new(None));
+static TIMER_TIM2: Mutex<RefCell<Option<CountDownTimer<stm32::TIM2>>>> =
+    Mutex::new(RefCell::new(None));
 static STATE: Mutex<Cell<StopwatchState>> = Mutex::new(Cell::new(StopwatchState::Ready));
 static BUTTON: Mutex<RefCell<Option<PC13<Input<PullUp>>>>> = Mutex::new(RefCell::new(None));
 
@@ -88,7 +89,7 @@ fn main() -> ! {
         disp.flush().unwrap();
 
         // Create a 1ms periodic interrupt from TIM2
-        let mut timer = Timer::tim2(dp.TIM2, 1.khz(), clocks);
+        let mut timer = Timer::new(dp.TIM2, &clocks).start_count_down(1.hz());
         timer.listen(Event::TimeOut);
 
         free(|cs| {
@@ -103,7 +104,7 @@ fn main() -> ! {
             stm32::NVIC::unmask(hal::stm32::Interrupt::EXTI15_10);
         };
 
-        let mut delay = Delay::new(cp.SYST, clocks);
+        let mut delay = Delay::new(cp.SYST, &clocks);
 
         loop {
             let elapsed = free(|cs| ELAPSED_MS.borrow(cs).get());
diff --git a/examples/timer-periph.rs b/examples/timer-periph.rs
@@ -29,7 +29,7 @@ fn main() -> ! {
     let clocks = rcc.cfgr.sysclk(24.mhz()).freeze();
 
     // Create a timer based on SysTick
-    let mut timer = Timer::tim1(dp.TIM1, 1.hz(), clocks);
+    let mut timer = Timer::new(dp.TIM1, &clocks).start_count_down(1.hz());
 
     hprintln!("hello!").unwrap();
     // wait until timer expires
diff --git a/examples/timer-syst.rs b/examples/timer-syst.rs
@@ -30,7 +30,7 @@ fn main() -> ! {
     let clocks = rcc.cfgr.sysclk(24.mhz()).freeze();
 
     // Create a timer based on SysTick
-    let mut timer = Timer::syst(cp.SYST, 24.hz(), clocks);
+    let mut timer = Timer::syst(cp.SYST, &clocks).start_count_down(24.hz());
 
     hprintln!("hello!").unwrap();
     // wait until timer expires
diff --git a/src/delay/mod.rs b/src/delay/mod.rs
@@ -4,12 +4,12 @@ mod syst;
 
 use cortex_m::peripheral::SYST;
 
-use crate::rcc::Clocks;
+use crate::time::Hertz;
 
 /// Timer as a delay provider (SysTick by default)
 pub struct Delay<T = SYST> {
     tim: T,
-    clocks: Clocks,
+    clk: Hertz,
 }
 
 impl<T> Delay<T> {
diff --git a/src/delay/syst.rs b/src/delay/syst.rs
@@ -11,9 +11,12 @@ use super::Delay;
 
 impl Delay<SYST> {
     /// Configures the system timer (SysTick) as a delay provider
-    pub fn new(mut tim: SYST, clocks: Clocks) -> Self {
+    pub fn new(mut tim: SYST, clocks: &Clocks) -> Self {
         tim.set_clock_source(SystClkSource::External);
-        Self { tim, clocks }
+        Self {
+            tim,
+            clk: clocks.hclk(),
+        }
     }
 
     #[deprecated(since = "0.10.0", note = "Please use release instead")]
@@ -45,7 +48,7 @@ impl DelayUs<u32> for Delay<SYST> {
         // The SysTick Reload Value register supports values between 1 and 0x00FFFFFF.
         const MAX_RVR: u32 = 0x00FF_FFFF;
 
-        let mut total_rvr = us * (self.clocks.hclk().0 / 8_000_000);
+        let mut total_rvr = us * (self.clk.0 / 8_000_000);
 
         while total_rvr != 0 {
             let current_rvr = if total_rvr <= MAX_RVR {
diff --git a/src/delay/timer.rs b/src/delay/timer.rs
@@ -8,10 +8,7 @@ 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 crate::{pac, rcc::Clocks, timer::Timer};
 
 use super::Delay;
 
@@ -41,22 +38,22 @@ macro_rules! hal {
                 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);
-                    }
+            impl Timer<$TIM> {
+                pub fn delay(self) -> Delay<$TIM> {
+                    let Self { tim, clk } = self;
 
                     // 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 }
+                    Delay { tim, clk }
+                }
+            }
+
+            impl Delay<$TIM> {
+                /// Configures the timer as a delay provider
+                pub fn $tim(tim: $TIM, clocks: &Clocks) -> Self {
+                    Timer::new(tim, clocks).delay()
                 }
             }
 
@@ -68,7 +65,7 @@ macro_rules! hal {
                     // 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)
+                    let psc = u16(self.clk.0 / 1_000_000)
                         .expect("Prescaler does not fit in u16");
                     let arr = us;
                     $waitfn(&mut self.tim, psc, arr);
@@ -79,7 +76,7 @@ macro_rules! hal {
                 /// 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)
+                    let psc = u16(self.clk.0 / 1_000_000)
                         .expect("Prescaler does not fit in u16");
                     let arr = u32(us);
                     $waitfn(&mut self.tim, psc, arr);
@@ -105,7 +102,7 @@ macro_rules! hal {
                     //
                     // 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)
+                    let psc = u16(self.clk.0 / 1000 / 2)
                         .expect("Prescaler does not fit in u16");
 
                     // Since PSC = 0.5 ms, double the value for the ARR
@@ -120,7 +117,7 @@ macro_rules! hal {
                 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)
+                    let psc = u16(self.clk.0 / 1000 / 2)
                         .expect("Prescaler does not fit in u16");
                     let arr = u32(ms) << 1;
                     $waitfn(&mut self.tim, psc, arr);
diff --git a/src/pwm.rs b/src/pwm.rs
diff --git a/src/timer.rs b/src/timer.rs
