Merge #385

385: Add support for reconfiguring a Serial port r=burrbull a=horazont

Example use case is to implement a [1-Wire Bus "Master"][1]. In that example, the UART is used instead of bit-banging the 1-Wire protocol. However, not all signals can be generated with a single baud rate. In particular, the 1-wire reset strobe is much longer than the 1-wire data strobes, requiring to use a different, slower baud rate to reset devices.

   [1]: https://www.maximintegrated.com/en/design/technical-documents/tutorials/2/214.html

Co-authored-by: Jonas Schäfer <j.wielicki@sotecware.net>

Author: bors[bot]

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- Serial can now be reconfigured, allowing to change e.g. the baud rate after initialisation.
+
 ## [v0.8.0] - 2021-12-29
 
 ### Breaking changes

examples/serial_reconfigure.rs

@@ -0,0 +1,95 @@
+//! Serial interface reconfiguration test
+//!
+//! You have to short the TX and RX pins to make this program work
+
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+use panic_halt as _;
+
+use cortex_m::asm;
+
+use nb::block;
+
+use cortex_m_rt::entry;
+use stm32f1xx_hal::{
+    pac,
+    prelude::*,
+    serial::{Config, Serial},
+};
+
+#[entry]
+fn main() -> ! {
+    // Get access to the device specific peripherals from the peripheral access crate
+    let p = pac::Peripherals::take().unwrap();
+
+    // Take ownership over the raw flash and rcc devices and convert them into the corresponding
+    // HAL structs
+    let mut flash = p.FLASH.constrain();
+    let rcc = p.RCC.constrain();
+
+    // Freeze the configuration of all the clocks in the system and store the frozen frequencies in
+    // `clocks`
+    let clocks = rcc.cfgr.freeze(&mut flash.acr);
+
+    // Prepare the alternate function I/O registers
+    let mut afio = p.AFIO.constrain();
+
+    // Prepare the GPIOB peripheral
+    let mut gpiob = p.GPIOB.split();
+
+    // USART1
+    // let tx = gpioa.pa9.into_alternate_push_pull(&mut gpioa.crh);
+    // let rx = gpioa.pa10;
+
+    // USART1
+    // let tx = gpiob.pb6.into_alternate_push_pull(&mut gpiob.crl);
+    // let rx = gpiob.pb7;
+
+    // USART2
+    // let tx = gpioa.pa2.into_alternate_push_pull(&mut gpioa.crl);
+    // let rx = gpioa.pa3;
+
+    // USART3
+    // Configure pb10 as a push_pull output, this will be the tx pin
+    let tx = gpiob.pb10.into_alternate_push_pull(&mut gpiob.crh);
+    // Take ownership over pb11
+    let rx = gpiob.pb11;
+
+    // Set up the usart device. Taks ownership over the USART register and tx/rx pins. The rest of
+    // the registers are used to enable and configure the device.
+    let mut serial = Serial::usart3(
+        p.USART3,
+        (tx, rx),
+        &mut afio.mapr,
+        Config::default().baudrate(9600.bps()),
+        clocks,
+    );
+
+    // Loopback test. Write `X` and wait until the write is successful.
+    let sent = b'X';
+    block!(serial.write(sent)).ok();
+
+    // Read the byte that was just sent. Blocks until the read is complete
+    let received = block!(serial.read()).unwrap();
+
+    // Since we have connected tx and rx, the byte we sent should be the one we received
+    assert_eq!(received, sent);
+
+    // Trigger a breakpoint to allow us to inspect the values
+    asm::bkpt();
+
+    // You can reconfigure the serial port to use a different baud rate at runtime.
+    // This may block for a while if the transmission is still in progress.
+    block!(serial.reconfigure(Config::default().baudrate(115_200.bps()), clocks)).unwrap();
+
+    // Let's see if it works.'
+    let sent = b'Y';
+    block!(serial.write(sent)).ok();
+    let received = block!(serial.read()).unwrap();
+    assert_eq!(received, sent);
+    asm::bkpt();
+
+    loop {}
+}

src/serial.rs

@@ -235,6 +235,19 @@ where
         USART::reset(rcc);
 
         remap();
+        self.apply_config(config, clocks);
+
+        // UE: enable USART
+        // RE: enable receiver
+        // TE: enable transceiver
+        self.usart
+            .cr1
+            .modify(|_r, w| w.ue().set_bit().re().set_bit().te().set_bit());
+
+        self
+    }
+
+    fn apply_config(&self, config: Config, clocks: Clocks) {
         // Configure baud rate
         let brr = USART::get_frequency(&clocks).0 / config.baudrate.0;
         assert!(brr >= 16, "impossible baud rate");
@@ -267,15 +280,23 @@ where
             StopBits::STOP1P5 => 0b11,
         };
         self.usart.cr2.modify(|_r, w| w.stop().bits(stop_bits));
+    }
 
-        // UE: enable USART
-        // RE: enable receiver
-        // TE: enable transceiver
-        self.usart
-            .cr1
-            .modify(|_r, w| w.ue().set_bit().re().set_bit().te().set_bit());
-
-        self
+    /// Reconfigure the USART instance.
+    ///
+    /// If a transmission is currently in progress, this returns
+    /// [`nb::Error::WouldBlock`].
+    pub fn reconfigure(&mut self, config: impl Into<Config>, clocks: Clocks) -> nb::Result<(), ()> {
+        let sr = self.usart.sr.read();
+        // if we're currently busy transmitting, we have to wait until that is
+        // over -- regarding reception, we assume that the caller -- with
+        // exclusive access to the Serial instance due to &mut self -- knows
+        // what they're doing.
+        if sr.tc().bit_is_clear() {
+            return nb::Result::Err(nb::Error::WouldBlock);
+        }
+        self.apply_config(config.into(), clocks);
+        nb::Result::Ok(())
     }
 
     /// Starts listening to the USART by enabling the _Received data