Change rcc API to take frequencies in MHz

Author: wbuck

CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [v0.7.0] - 2021-03-10
+
+### Added
+
+- Replace custom time based units with types defined in the [embedded-time][] crate ([#191])
+
+### Breaking changes
+
+- The `rcc` public API now expects time based units in `Megahertz`.
+  If the supplied frequency cannot be converted to `Hertz` the code
+  will `panic`. This will occur if the supplied `Megahertz` frequency
+  cannot fit into `u32::MAX` when converting to `Hertz`
+
+```rust
+// The supplied frequencies must be in `MHz`.
+let clocks = rcc
+    .cfgr
+    .use_hse(8u32.MHz())
+    .hclk(48u32.MHz())
+    .sysclk(48u32.MHz())
+    .pclk1(12u32.MHz())
+    .pclk2(12u32.MHz())
+```
+
+[embedded-time]: https://github.com/FluenTech/embedded-time/
+
 ## [v0.6.1] - 2020-12-10
 
 ### Changed
@@ -262,6 +288,7 @@ let clocks = rcc
 
 - Support `stm32f303` device
 
+[#192]: https://github.com/stm32-rs/stm32f3xx-hal/pull/192
 [#184]: https://github.com/stm32-rs/stm32f3xx-hal/pull/184
 [#172]: https://github.com/stm32-rs/stm32f3xx-hal/pull/172
 [#170]: https://github.com/stm32-rs/stm32f3xx-hal/pull/170

examples/can.rs

@@ -32,10 +32,10 @@ fn main() -> ! {
 
     let _clocks = rcc
         .cfgr
-        .use_hse(Hertz(32_000_000))
-        .sysclk(Hertz(32_000_000))
-        .pclk1(Hertz(16_000_000))
-        .pclk2(Hertz(16_000_000))
+        .use_hse(32u32.MHz())
+        .sysclk(32u32.MHz())
+        .pclk1(16u32.MHz())
+        .pclk2(16u32.MHz())
         .freeze(&mut flash.acr);
 
     // Configure CAN RX and TX pins (AF9)

examples/i2c_scanner.rs

@@ -6,7 +6,7 @@
 #![no_std]
 #![no_main]
 
-use core::ops::Range;
+use core::{convert::TryInto, ops::Range};
 
 use panic_semihosting as _;
 
@@ -35,7 +35,13 @@ fn main() -> ! {
         gpiob.pb7.into_af4(&mut gpiob.moder, &mut gpiob.afrl), // SDA
     );
 
-    let mut i2c = hal::i2c::I2c::new(dp.I2C1, pins, 100u32.kHz(), clocks, &mut rcc.apb1).unwrap();
+    let mut i2c = hal::i2c::I2c::new(
+        dp.I2C1,
+        pins,
+        100_000u32.kHz().try_into().unwrap(),
+        clocks,
+        &mut rcc.apb1,
+    );
 
     hprintln!("Start i2c scanning...").expect("Error using hprintln.");
     hprintln!().unwrap();

examples/pwm.rs

@@ -28,7 +28,7 @@ fn main() -> ! {
     // Configure our clocks
     let mut flash = dp.FLASH.constrain();
     let mut rcc = dp.RCC.constrain();
-    let clocks = rcc.cfgr.sysclk(Hertz(16_000_000)).freeze(&mut flash.acr);
+    let clocks = rcc.cfgr.sysclk(16u32.MHz()).freeze(&mut flash.acr);
 
     // Prep the pins we need in their correct alternate function
     let mut gpioa = dp.GPIOA.split(&mut rcc.ahb);

examples/spi.rs

@@ -3,6 +3,8 @@
 #![no_std]
 #![no_main]
 
+use core::convert::TryInto;
+
 use panic_semihosting as _;
 
 use stm32f3xx_hal as hal;
@@ -25,9 +27,9 @@ fn main() -> ! {
 
     let clocks = rcc
         .cfgr
-        .use_hse(Hertz(8_000_000))
-        .sysclk(Hertz(48_000_000))
-        .pclk1(Hertz(24_000_000))
+        .use_hse(8u32.MHz())
+        .sysclk(48u32.MHz())
+        .pclk1(24u32.MHz())
         .freeze(&mut flash.acr);
 
     // Configure pins for SPI
@@ -44,11 +46,10 @@ fn main() -> ! {
         dp.SPI1,
         (sck, miso, mosi),
         spi_mode,
-        3u32.MHz(),
+        3u32.MHz().try_into().unwrap(),
         clocks,
         &mut rcc.apb2,
-    )
-    .unwrap();
+    );
 
     // Create an `u8` array, which can be transfered via SPI.
     let msg_send: [u8; 8] = [0xD, 0xE, 0xA, 0xD, 0xB, 0xE, 0xE, 0xF];

examples/usb_serial.rs

@@ -27,10 +27,10 @@ fn main() -> ! {
 
     let clocks = rcc
         .cfgr
-        .use_hse(Hertz(8_000_000))
-        .sysclk(Hertz(48_000_000))
-        .pclk1(Hertz(24_000_000))
-        .pclk2(Hertz(24_000_000))
+        .use_hse(8u32.MHz())
+        .sysclk(48u32.MHz())
+        .pclk1(24u32.MHz())
+        .pclk2(24u32.MHz())
         .freeze(&mut flash.acr);
 
     assert!(clocks.usbclk_valid());

src/i2c.rs

@@ -4,15 +4,15 @@
 //!
 //! [examples/i2c_scanner.rs]: https://github.com/stm32-rs/stm32f3xx-hal/blob/v0.6.0/examples/i2c_scanner.rs
 
-use core::convert::{TryFrom, TryInto};
+use core::convert::TryFrom;
 use core::ops::Deref;
 
 use crate::{
     gpio::{gpioa, gpiob, AF4},
     hal::blocking::i2c::{Read, Write, WriteRead},
     pac::{i2c1::RegisterBlock, rcc::cfgr3::I2C1SW_A, I2C1, RCC},
     rcc::{Clocks, APB1},
-    time::rate::{Hertz, Rate},
+    time::rate::Hertz,
 };
 
 #[cfg(not(feature = "gpio-f333"))]
@@ -111,22 +111,13 @@ macro_rules! busy_wait {
 
 impl<I2C, SCL, SDA> I2c<I2C, (SCL, SDA)> {
     /// Configures the I2C peripheral to work in master mode
-    pub fn new<F>(
-        i2c: I2C,
-        pins: (SCL, SDA),
-        freq: F,
-        clocks: Clocks,
-        apb1: &mut APB1,
-    ) -> Result<Self, <F as TryInto<Hertz<u32>>>::Error>
+    pub fn new(i2c: I2C, pins: (SCL, SDA), freq: Hertz, clocks: Clocks, apb1: &mut APB1) -> Self
     where
         I2C: Instance,
         SCL: SclPin<I2C>,
         SDA: SdaPin<I2C>,
-        F: Rate + TryInto<Hertz<u32>>,
     {
-        let freq = (freq.try_into()? as Hertz).0;
-
-        crate::assert!(freq <= 1_000_000);
+        crate::assert!(freq.0 <= 1_000_000);
 
         I2C::enable_clock(apb1);
 
@@ -139,16 +130,16 @@ impl<I2C, SCL, SDA> I2c<I2C, (SCL, SDA)> {
         // t_SYNC1 + t_SYNC2 > 4 * t_I2CCLK
         // t_SCL ~= t_SYNC1 + t_SYNC2 + t_SCLL + t_SCLH
         let i2cclk = I2C::clock(&clocks).0;
-        let ratio = i2cclk / freq - 4;
-        let (presc, scll, sclh, sdadel, scldel) = if freq >= 100_000 {
+        let ratio = i2cclk / freq.0 - 4;
+        let (presc, scll, sclh, sdadel, scldel) = if freq.0 >= 100_000 {
             // fast-mode or fast-mode plus
             // here we pick SCLL + 1 = 2 * (SCLH + 1)
             let presc = ratio / 387;
 
             let sclh = ((ratio / (presc + 1)) - 3) / 3;
             let scll = 2 * (sclh + 1) - 1;
 
-            let (sdadel, scldel) = if freq > 400_000 {
+            let (sdadel, scldel) = if freq.0 > 400_000 {
                 // fast-mode plus
                 let sdadel = 0;
                 let scldel = i2cclk / 4_000_000 / (presc + 1) - 1;
@@ -201,7 +192,7 @@ impl<I2C, SCL, SDA> I2c<I2C, (SCL, SDA)> {
         // Enable the peripheral
         i2c.cr1.modify(|_, w| w.pe().set_bit());
 
-        Ok(Self { i2c, pins })
+        Self { i2c, pins }
     }
 
     /// Releases the I2C peripheral and associated pins

src/rcc.rs

@@ -9,6 +9,8 @@
 //! ```
 //! # use cortex_m_rt::entry;
 //! # use stm32f3xx_hal::prelude::*;
+//! #use hal::time::rate::*;
+//!
 //! # #[entry]
 //! # fn main() -> ! {
 //! // Get our peripherals
@@ -33,18 +35,18 @@
 //! let clocks = rcc.cfgr
 //!     // Using the external oscillator
 //!     // Set the frequency to that of the external oscillator
-//!     .use_hse(8.mhz())
+//!     .use_hse(8.MHz())
 //!     // Set the frequency for the AHB bus,
 //!     // which the root of every following clock peripheral
-//!     .hclk(48.mhz())
+//!     .hclk(48.MHz())
 //!     // The sysclk is equivalent to the core clock
-//!     .sysclk(48.mhz())
+//!     .sysclk(48.MHz())
 //!     // The following are peripheral clocks, which are both
 //!     // needed to configure specific peripherals.
 //!     // Looking at the peripheral function parameters
 //!     // should give more insight, which peripheral clock is needed.
-//!     .pclk1(12.mhz())
-//!     .pclk2(12.mhz())
+//!     .pclk1(12.MHz())
+//!     .pclk2(12.MHz())
 //!     // Freeze / apply the configuration and setup all clocks
 //!     .freeze(&mut flash.acr);
 //! # }
@@ -59,8 +61,10 @@ use crate::pac::{
     RCC,
 };
 
+use core::convert::TryInto;
+
 use crate::flash::ACR;
-use crate::time::rate::Hertz;
+use crate::time::rate::*;
 
 /// Extension trait that constrains the `RCC` peripheral
 pub trait RccExt {
@@ -333,7 +337,12 @@ impl CFGR {
     ///
     /// Will result in a hang if an external oscillator is not connected or it fails to start,
     /// unless [css](CFGR::enable_css) is enabled.
-    pub fn use_hse(mut self, freq: Hertz) -> Self {
+    ///
+    /// # Panics
+    ///
+    /// Panics if conversion from `Megahertz` to `Hertz` produces a value greater then `u32::MAX`.
+    pub fn use_hse(mut self, freq: Megahertz) -> Self {
+        let freq: Hertz = crate::expect!(freq.try_into(), "ConversionError");
         self.hse = Some(freq.0);
         self
     }
@@ -360,8 +369,13 @@ impl CFGR {
         self
     }
 
-    /// Sets a frequency for the AHB bus
-    pub fn hclk(mut self, freq: Hertz) -> Self {
+    /// Sets a frequency for the AHB bus.
+    ///
+    /// # Panics
+    ///
+    /// Panics if conversion from `Megahertz` to `Hertz` produces a value greater then `u32::MAX`.
+    pub fn hclk(mut self, freq: Megahertz) -> Self {
+        let freq: Hertz = crate::expect!(freq.try_into(), "ConversionError");
         self.hclk = Some(freq.0);
         self
     }
@@ -372,7 +386,12 @@ impl CFGR {
     ///
     /// If not manually set, it will be set to [`CFGR::sysclk`] frequency
     /// or [`CFGR::sysclk`] frequency / 2, if [`CFGR::sysclk`] > 36 Mhz
-    pub fn pclk1(mut self, freq: Hertz) -> Self {
+    ///
+    /// # Panics
+    ///
+    /// Panics if conversion from `Megahertz` to `Hertz` produces a value greater then `u32::MAX`.
+    pub fn pclk1(mut self, freq: Megahertz) -> Self {
+        let freq: Hertz = crate::expect!(freq.try_into(), "ConversionError");
         self.pclk1 = Some(freq.0);
         self
     }
@@ -390,7 +409,11 @@ impl CFGR {
     ///
     ///     [stm32f302xd,stm32f302xe,stm32f303xd,stm32f303xe,stm32f398]
     ///
-    pub fn pclk2(mut self, freq: Hertz) -> Self {
+    /// # Panics
+    ///
+    /// Panics if conversion from `Megahertz` to `Hertz` produces a value greater then `u32::MAX`.
+    pub fn pclk2(mut self, freq: Megahertz) -> Self {
+        let freq: Hertz = crate::expect!(freq.try_into(), "ConversionError");
         self.pclk2 = Some(freq.0);
         self
     }
@@ -410,7 +433,12 @@ impl CFGR {
     /// even when using the internal oscillator:
     ///
     ///     [stm32f302xd,stm32f302xe,stm32f303xd,stm32f303xe,stm32f398]
-    pub fn sysclk(mut self, freq: Hertz) -> Self {
+    ///
+    /// # Panics
+    ///
+    /// Panics if conversion from `Megahertz` to `Hertz` produces a value greater then `u32::MAX`.
+    pub fn sysclk(mut self, freq: Megahertz) -> Self {
+        let freq: Hertz = crate::expect!(freq.try_into(), "ConversionError");
         self.sysclk = Some(freq.0);
         self
     }
@@ -645,7 +673,7 @@ impl CFGR {
 
         // This ensures, that no panic happens, when
         // pclk1 is not manually set.
-        // As hclk highest value is 72.mhz()
+        // As hclk highest value is 72.MHz()
         // dividing by 2 should always be sufficient
         if self.pclk1.is_none() && pclk1 > 36_000_000 {
             ppre1_bits = cfgr::PPRE1_A::DIV2;