Implement spi config struct

Author: Sh3Rm4n

CHANGELOG.md

@@ -142,6 +142,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Rework SPI implementation: ([#273])
   - A generic `Instance` trait now represents all Spi peripherals.
   - `Spi::spi1` and so on are renamed to `Spi::new`.
+  - Add SPI configuration type to be passed into `Spi::new`
 
 ## [v0.7.0] - 2021-06-18
 

examples/spi.rs

@@ -12,7 +12,7 @@ use cortex_m_rt::entry;
 
 use hal::pac;
 use hal::prelude::*;
-use hal::spi::{Mode, Phase, Polarity, Spi};
+use hal::spi::Spi;
 
 #[entry]
 fn main() -> ! {
@@ -40,19 +40,7 @@ fn main() -> ! {
         .pc12
         .into_af6_push_pull(&mut gpioc.moder, &mut gpioc.otyper, &mut gpioc.afrh);
 
-    let spi_mode = Mode {
-        polarity: Polarity::IdleLow,
-        phase: Phase::CaptureOnFirstTransition,
-    };
-
-    let mut spi = Spi::new(
-        dp.SPI3,
-        (sck, miso, mosi),
-        spi_mode,
-        3_000_000.Hz(),
-        clocks,
-        &mut rcc.apb1,
-    );
+    let mut spi = Spi::new(dp.SPI3, (sck, miso, mosi), 3.MHz(), clocks, &mut rcc.apb1);
 
     // Create an `u8` array, which can be transfered via SPI.
     let msg_send: [u8; 8] = [0xD, 0xE, 0xA, 0xD, 0xB, 0xE, 0xE, 0xF];

src/serial.rs

@@ -470,7 +470,7 @@ where
         Rx: RxPin<Usart>,
         Config: Into<config::Config>,
     {
-        use self::config::*;
+        use config::*;
 
         let config = config.into();
 

src/serial/config.rs

@@ -58,7 +58,7 @@ pub enum Parity {
 }
 
 /// Configuration struct for [`Serial`](super::Serial) providing all
-/// communication-related / parameters. `Serial` always uses eight data
+/// communication-related / parameters. [`Serial`](super::Serial) always uses eight data
 /// bits plus the parity bit - if selected.
 ///
 /// Create a configuration by using `default` in combination with the

src/spi.rs

@@ -22,7 +22,7 @@ use crate::pac::{
 use crate::{
     gpio::{self, PushPull, AF5, AF6},
     rcc::{self, Clocks},
-    time::{fixed_point::FixedPoint, rate::Hertz},
+    time::rate::{self, Hertz},
 };
 
 /// SPI error
@@ -177,14 +177,30 @@ pub struct Spi<SPI, Pins, Word = u8> {
     _word: PhantomData<Word>,
 }
 
+pub mod config;
+
 impl<SPI, Sck, Miso, Mosi, WORD> Spi<SPI, (Sck, Miso, Mosi), WORD> {
-    /// Configures the SPI peripheral to operate in full duplex master mode
+    /// Configures the SPI peripheral to operate in full duplex master mode.
+    ///
+    /// The most convinient way to get a device is like that:
+    ///
+    /// ```ignore
+    /// use stm32f3xx_hal::prelude::*;
+    /// use stm32f3xx_hal::spi::Spi;
+    ///
+    /// // ...
+    ///
+    /// let spi = Spi::new(dp.SPI1, (sck_pin, mosi_pin, miso_pin), 1.MHz, clocks, &mut dp.abp1);
+    ///
+    /// ```
+    ///
+    /// To get a better example, look [here](https://github.com/stm32-rs/stm32f3xx-hal/blob/v0.7.0/examples/spi.rs).
+    ///
     // TODO(Sh3Rm4n): See alternative modes provided besides FullDuplex (as listed in Stm32CubeMx).
-    pub fn new(
+    pub fn new<Config>(
         spi: SPI,
         pins: (Sck, Miso, Mosi),
-        mode: Mode,
-        freq: Hertz,
+        config: Config,
         clocks: Clocks,
         apb: &mut <SPI as Instance>::APB,
     ) -> Self
@@ -194,7 +210,9 @@ impl<SPI, Sck, Miso, Mosi, WORD> Spi<SPI, (Sck, Miso, Mosi), WORD> {
         Miso: MisoPin<SPI>,
         Mosi: MosiPin<SPI>,
         WORD: Word,
+        Config: Into<config::Config>,
     {
+        let config = config.into();
         SPI::enable_clock(apb);
 
         let (frxth, ds) = WORD::register_config();
@@ -218,17 +236,18 @@ impl<SPI, Sck, Miso, Mosi, WORD> Spi<SPI, (Sck, Miso, Mosi), WORD> {
         spi.cr1.write(|w| {
             w.mstr().master();
 
-            match mode.phase {
+            match config.mode.phase {
                 Phase::CaptureOnFirstTransition => w.cpha().first_edge(),
                 Phase::CaptureOnSecondTransition => w.cpha().second_edge(),
             };
 
-            match mode.polarity {
+            match config.mode.polarity {
                 Polarity::IdleLow => w.cpol().idle_low(),
                 Polarity::IdleHigh => w.cpol().idle_high(),
             };
 
-            w.br().variant(Self::compute_baud_rate(clocks, freq));
+            w.br()
+                .variant(Self::compute_baud_rate(clocks, config.frequency));
 
             w.spe()
                 .enabled()
@@ -262,18 +281,18 @@ where
     SPI: Instance,
 {
     /// Change the baud rate of the SPI
-    pub fn reclock(&mut self, freq: Hertz, clocks: Clocks) {
+    pub fn reclock(&mut self, freq: impl Into<rate::Generic<u32>>, clocks: Clocks) {
         self.spi.cr1.modify(|_, w| w.spe().disabled());
 
         self.spi.cr1.modify(|_, w| {
-            w.br().variant(Self::compute_baud_rate(clocks, freq));
+            w.br().variant(Self::compute_baud_rate(clocks, freq.into()));
             w.spe().enabled()
         });
     }
 
-    fn compute_baud_rate(clocks: Clocks, freq: Hertz) -> spi1::cr1::BR_A {
+    fn compute_baud_rate(clocks: Clocks, freq: rate::Generic<u32>) -> spi1::cr1::BR_A {
         use spi1::cr1::BR_A;
-        match SPI::clock(&clocks).0 / freq.integer() {
+        match SPI::clock(&clocks).0 / (freq.integer() * *freq.scaling_factor()) {
             0 => crate::unreachable!(),
             1..=2 => BR_A::DIV2,
             3..=5 => BR_A::DIV4,

src/spi/config.rs

@@ -0,0 +1,103 @@
+//! Types for configuring a spi interface.
+
+use crate::time::rate::{self, Extensions};
+use core::fmt;
+
+use crate::hal::spi::{self, Mode};
+
+/// Configuration struct for [`Spi`](super::Spi) providing all
+/// communication-related / parameters.
+///
+/// The default configruation can be obtain by:
+///
+/// ```
+/// # use stm32f3xx_hal::spi::config::Config;
+/// let config = Config::default();
+/// ````
+///
+/// [`Spi`](super::Spi) defaults to [`spi::MODE_0`] and a frequency of 1 MHz.
+///
+/// ```
+/// # use stm32f3xx_hal::spi::config::Config;
+/// let config = Config::default();
+/// ```
+///
+/// Create a configuration by using `default` in combination with the
+/// builder methods. The following snippet shows creating a configuration
+/// for 19,200 Baud, 8N1 by deriving it from the default value:
+/// ```
+/// # use stm32f3xx_hal::serial::config::*;
+/// # use stm32f3xx_hal::time::rate::{Baud, Extensions};
+/// let config = Config::default().baudrate(19_200.Bd());
+///
+/// assert!(config.baudrate == 19_200.Bd());
+/// assert!(config.parity == Parity::None);
+/// assert!(config.stopbits == StopBits::STOP1);
+/// ```
+#[derive(Clone, Copy, PartialEq)]
+#[non_exhaustive]
+pub struct Config {
+    /// Operating frequency of the SPI peripheral.
+    pub frequency: rate::Generic<u32>,
+    /// Operation Mode as defined by the [`embedded-hal`]
+    pub mode: Mode,
+}
+
+impl fmt::Debug for Config {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let mode = if self.mode == spi::MODE_0 {
+            0
+        } else if self.mode == spi::MODE_1 {
+            1
+        } else if self.mode == spi::MODE_2 {
+            2
+        } else {
+            3
+        };
+
+        f.debug_struct("Config")
+            .field("frequency", &format_args!("{:?}", self.frequency))
+            .field("mode", &format_args!("MODE_{}", mode))
+            .finish()
+    }
+}
+
+#[cfg(feature = "defmt")]
+impl defmt::Format for Config {
+    fn format(&self, f: defmt::Formatter) {
+        let mode = if self.mode == spi::MODE_0 {
+            0
+        } else if self.mode == spi::MODE_1 {
+            1
+        } else if self.mode == spi::MODE_2 {
+            2
+        } else {
+            3
+        };
+
+        defmt::write!(
+            f,
+            "Config {{ frequency: {} Hz, mode: MODE_{}}}",
+            self.frequency.integer() * *self.frequency.scaling_factor(),
+            mode,
+        );
+    }
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            frequency: 1.MHz().into(),
+            mode: spi::MODE_0,
+        }
+    }
+}
+
+impl<T: Into<rate::Generic<u32>>> From<T> for Config {
+    fn from(f: T) -> Config {
+        Config {
+            frequency: f.into(),
+            ..Default::default()
+        }
+    }
+}

testsuite/tests/spi.rs

@@ -4,18 +4,16 @@
 use hal::rcc::{Clocks, APB1};
 use testsuite as _;
 
-use core::convert::TryInto;
-
 use stm32f3xx_hal as hal;
 
 use hal::prelude::*;
 
 use hal::gpio::{PushPull, AF6};
 use hal::gpio::{PC10, PC11, PC12};
-use hal::hal::spi::MODE_0;
 use hal::pac;
 use hal::pac::SPI3;
 use hal::spi::Spi;
+use hal::time::rate::{self, Extensions};
 
 const TEST_MSG: [u8; 8] = [0xa, 0xb, 0xc, 0xd, 0xe, 0xf, 0xaa, 0xbb];
 
@@ -65,8 +63,7 @@ mod tests {
         let spi = Spi::new(
             dp.SPI3,
             (spi_pins.0, spi_pins.1, spi_pins.2),
-            MODE_0,
-            10.MHz().try_into().unwrap(),
+            10.MHz(),
             clocks,
             &mut rcc.apb1,
         );
@@ -80,10 +77,16 @@ mod tests {
 
     #[test]
     fn test_transfer(state: &mut super::State) {
-        for freq in [100.Hz(), 100_000.Hz(), 10_000_000.Hz(), 32_000_000.Hz()] {
+        let rates: [rate::Generic<u32>; 4] = [
+            100.Hz().into(),
+            100.kHz().into(),
+            10.MHz().into(),
+            32.MHz().into(),
+        ];
+        for freq in rates {
             let (spi, pins) = unwrap!(state.spi.take()).free();
 
-            let mut spi = Spi::new(spi, pins, MODE_0, freq, state.clocks, &mut state.apb1);
+            let mut spi = Spi::new(spi, pins, freq, state.clocks, &mut state.apb1);
             let mut transfer_buffer = TEST_MSG;
 
             unwrap!(spi.transfer(&mut transfer_buffer));