Merge pull request #253 from Sh3Rm4n/serial-events

Rework serial (interrupt) events

Author: Sh3Rm4n

.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
         features: ["rt"]
         include:
           - mcu: stm32f303xc
-            features: rt,can,stm32-usbd
+            features: rt,can,stm32-usbd,enumset
     steps:
       - uses: actions/checkout@v2
       - uses: actions-rs/toolchain@v1

CHANGELOG.md

@@ -19,12 +19,45 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Readd MonoTimer. This was accidentally removed before. ([#247])
 - Basic serial implementation also available for UART4 and UART5 ([#246])
 - Implement serial DMA also for Serial ([#246])
+- Add [`enumset`][] as a optional dependency, which allow more ergonomic functions
+  regarding enums. This is especially useful for status event query functions.
+  ([#253])
+- As serial `Error` and serial `Events` share things in common. `TryFrom<Event>`
+  and `From<Error>` is implemented for conversions. ([#253])
+- Add serial character match function, with which events can be triggered for
+  the set character. ([#253])
+- Add receiver timeout function, which configures the serial peripheral to
+  trigger an event, if nothing happened after a certain time on the serial
+  receiver line. ([#253])
+- Add `raw_read()` function, which does no error handling and also does not
+  clear any `Event` by itself. Useful, if the error_handling has to be done in
+  another context (like an interrupt rountine). ([#253])
+- Introduce `Toggle`, with `On` and `Off` as a convinience wrapper around `bool`
+  for configuration purposes. ([#253])
+- Add an associated const to `serial::Instance` to return the corresponding
+  `pac::Interrupt`-number, which is useful to `unmask()` interrupts.
+  An `nvic()` function to `Serial` was also added for convinience. ([#253])
+- Add a `Serial::is_busy()` function to check, if the serial device is busy.
+  Useful to block on this function, e.g. `while serial.is_busy() {}`. ([#253])
+- Add `BaudTable` a convinience wrapper around `Baud` to configure the `Serial`
+  to the most commen baud rates. ([#253])
+- Add `Serial::detect_overrun()` function, to en- or disable the overrun
+  detection of the `Serial`. If overrun is disabled (enabled by default), than
+  newly arrived bytes are overwriting the current data in the read receive
+  register without throwing any event. ([#253]).
+- Lift generic constraint of most `Serial` method on `TxPin` and `RxPin`.
+  This should make it easier to generically use the `Serial` peripheral. ([#253])
+
+[`enumset`]: https://crates.io/crates/enumset
 
 ### Changed
 
 - `PXx` struct (representing a generic GPIO pin) implements `Send` and `Sync` ([#251])
 - Each pin aliases (`PA0`, `PA1`, ..) are defined under `gpio` module directly.
-  Re-export from gpio port sub-modules are provided for compatibility. [#257]
+  Re-export from gpio port sub-modules are provided for compatibility. ([#257])
+- The `embedded-hal` Read implementation of `Serial` does now return `WoudBlock`
+  if the peripheral is busy. Also if an `Overrun` occured the receive data
+  register (RDR) is flushed to have a more consistent API. ([#253])
 
 ### Fixed
 
@@ -45,6 +78,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   when `Serial::split` was previously called. ([#252])
 - Parameterized `usb::Peripheral` and `usb::UsbType` on the pin configuration
   used ([#255])
+- Add (almost) all missing serial (interrupt and status) events.
+  Also rename all the event names to be more descriptive. ([#253])
+- A new serial interrupt API was introduced: ([#253])
+  - `listen()` and `unlisten()` are renamed to `enable_interrupt()` and
+  `disable_interrupt()`.
+  - `is_tc()` and other non-parametrizable functions are removed.
+  - `configure_interrupt()` was added, which can be parameterized.
+  - `clear_event()` was added to clear specific events.
+  - `clear_events()` was added to clear all events at once.
+  - `is_event_triggered()` can check if an `Event` is triggered.
+  - `triggered_events` returns an `EnumSet` of triggered events.
 
 ## [v0.7.0] - 2021-06-18
 
@@ -374,6 +418,7 @@ let clocks = rcc
 [#259]: https://github.com/stm32-rs/stm32f3xx-hal/pull/259
 [#257]: https://github.com/stm32-rs/stm32f3xx-hal/pull/257
 [#255]: https://github.com/stm32-rs/stm32f3xx-hal/pull/255
+[#253]: https://github.com/stm32-rs/stm32f3xx-hal/pull/253
 [#252]: https://github.com/stm32-rs/stm32f3xx-hal/pull/252
 [#251]: https://github.com/stm32-rs/stm32f3xx-hal/pull/251
 [#247]: https://github.com/stm32-rs/stm32f3xx-hal/pull/247

Cargo.toml

@@ -47,6 +47,7 @@ stm32f3 = "0.13.2"
 bxcan = { version = ">=0.4, <0.6", optional = true }
 stm32-usbd = { version = "0.6.0", optional = true }
 void = { version = "1.0.2", default-features = false }
+enumset = { version = "1.0.6", optional = true}
 
 [dev-dependencies]
 cortex-m = "0.7.2"
@@ -186,7 +187,7 @@ required-features = ["ld", "rt", "stm32f303"]
 
 [[example]]
 name = "serial_echo_rtic"
-required-features = ["ld", "rt", "stm32f303xc"]
+required-features = ["ld", "rt", "stm32f303xc", "enumset"]
 
 [[example]]
 name = "adc"

examples/serial_echo_rtic.rs

@@ -12,6 +12,7 @@ mod app {
         pac,
         prelude::*,
         serial::{Event, Serial},
+        Toggle,
     };
 
     #[monotonic(binds = SysTick, default = true)]
@@ -65,10 +66,13 @@ mod app {
         pins.1.internal_pull_up(&mut gpioa.pupdr, true);
         let mut serial: SerialType =
             Serial::new(cx.device.USART1, pins, 19200.Bd(), clocks, &mut rcc.apb2);
-        serial.listen(Event::Rxne);
+        serial.configure_interrupt(Event::ReceiveDataRegisterNotEmpty, Toggle::On);
 
         rprintln!("post init");
 
+        // A kick of for the infitinte loop in protocol_serial_task()
+        nb::block!(serial.write(b'c')).unwrap();
+
         task1::spawn().unwrap();
 
         (Shared {}, Local { serial, dir }, init::Monotonics(mono))
@@ -79,22 +83,33 @@ mod app {
         let serial = cx.local.serial;
         let dir = cx.local.dir;
 
-        if serial.is_rxne() {
+        if serial.is_event_triggered(Event::ReceiveDataRegisterNotEmpty) {
             dir.set_high().unwrap();
-            serial.unlisten(Event::Rxne);
+            serial.configure_interrupt(Event::ReceiveDataRegisterNotEmpty, Toggle::Off);
             match serial.read() {
                 Ok(byte) => {
                     serial.write(byte).unwrap();
-                    serial.listen(Event::Tc);
+                    rprintln!("{:?}", char::from_u32(byte.into()).unwrap_or('?'));
+                    serial.configure_interrupt(Event::TransmissionComplete, Toggle::On);
                 }
                 Err(_error) => rprintln!("irq error"),
             };
         }
 
-        if serial.is_tc() {
+        // It is perfectly viable to just use `is_event_triggered` here,
+        // but this is a showcase, to also be able to used `triggered_events`
+        // and other functions enabled by the "enumset" feature.
+        let events = serial.triggered_events();
+        if events.contains(Event::TransmissionComplete) {
             dir.set_low().unwrap();
-            serial.unlisten(Event::Tc);
-            serial.listen(Event::Rxne);
+            let interrupts = {
+                let mut interrupts = enumset::EnumSet::new();
+                interrupts.insert(Event::ReceiveDataRegisterNotEmpty);
+                interrupts
+            };
+            serial.clear_event(Event::TransmissionComplete);
+            // Disable all interrupts, except ReceiveDataRegisterNotEmpty.
+            serial.configure_interrupts(interrupts);
         }
     }
 

src/lib.rs

@@ -69,6 +69,12 @@
 
  Enable USB peripherals on supported targets.
 
+ ### `enumset`
+
+ Enable functions, which leverage [`enumset`](https://crates.io/crates/enumset).
+ This is especially usefull to get all set status events at once,
+ see for example [`serial::Serial::triggered_events()`]
+
  ### `defmt`
 
  Currently these are only used for panicking calls, like
@@ -212,3 +218,30 @@ mod private {
     /// which do implement peripheral functionalities.
     pub trait Sealed {}
 }
+
+/// Toggle something on or off.
+///
+/// Convenience enum and wrapper around a bool, which more explicit about the intention to enable
+/// or disable something, in comparison to `true` or `false`.
+// TODO: Maybe move to some mod like "util"?
+pub enum Toggle {
+    /// Toggle something on / enable a thing.
+    On,
+    /// Toggle something off / disable a thing.
+    Off,
+}
+
+impl From<Toggle> for bool {
+    fn from(toggle: Toggle) -> Self {
+        matches!(toggle, Toggle::On)
+    }
+}
+
+impl From<bool> for Toggle {
+    fn from(b: bool) -> Self {
+        match b {
+            true => Toggle::On,
+            false => Toggle::Off,
+        }
+    }
+}