Merge #297

297: serial: document parity and word length configuration, set word length based on parity r=richardeoin a=mattico

The first commit documents how serial data word length and parity are related.

The second commit removes manual control over serial data word length but configures it automatically based on the parity. This seems reasonable to do since we only support reading/writing 8-bit data.

closes #296 

Co-authored-by: Matt Ickstadt <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -21,6 +21,7 @@
   constants to specify how many transmit / receive buffers to include in
   `ethernet::DesRing`. To replicate the previous behaviour, use `DesRing<4, 4>`
 * spi: Utilise FIFO in `Transfer` and `Write` implementations
+* **Breaking**: manual control over serial data length removed, now set automatically based on parity
 
 ## [v0.10.0] 2021-07-xx
 

src/serial.rs

@@ -76,11 +76,12 @@ pub enum Event {
 pub mod config {
     use crate::time::Hertz;
 
-    #[derive(Copy, Clone, PartialEq)]
-    pub enum WordLength {
-        DataBits8,
-        DataBits9,
-    }
+    /// The parity bits appended to each serial data word
+    ///
+    /// When enabled parity bits will be automatically added by hardware on transmit, and automatically checked by
+    /// hardware on receive. For example, `read()` would return [`Error::Parity`](super::Error::Parity).
+    ///
+    /// Note that parity bits are included in the serial word length, so if parity is used word length will be set to 9.
     #[derive(Copy, Clone, PartialEq)]
     pub enum Parity {
         ParityNone,
@@ -125,7 +126,6 @@ pub mod config {
     #[derive(Copy, Clone)]
     pub struct Config {
         pub baudrate: Hertz,
-        pub wordlength: WordLength,
         pub parity: Parity,
         pub stopbits: StopBits,
         pub bitorder: BitOrder,
@@ -142,7 +142,6 @@ pub mod config {
         pub fn new<T: Into<Hertz>>(frequency: T) -> Self {
             Config {
                 baudrate: frequency.into(),
-                wordlength: WordLength::DataBits8,
                 parity: Parity::ParityNone,
                 stopbits: StopBits::STOP1,
                 bitorder: BitOrder::LsbFirst,
@@ -162,26 +161,24 @@ pub mod config {
             self
         }
 
+        /// Enables Even Parity
+        ///
+        /// Note that parity bits are included in the serial word length, so if parity is used word length will be set
+        /// to 9.
         pub fn parity_even(mut self) -> Self {
             self.parity = Parity::ParityEven;
             self
         }
 
+        /// Enables Odd Parity
+        ///
+        /// Note that parity bits are included in the serial word length, so if parity is used word length will be set
+        /// to 9.
         pub fn parity_odd(mut self) -> Self {
             self.parity = Parity::ParityOdd;
             self
         }
 
-        pub fn wordlength_8(mut self) -> Self {
-            self.wordlength = WordLength::DataBits8;
-            self
-        }
-
-        pub fn wordlength_9(mut self) -> Self {
-            self.wordlength = WordLength::DataBits9;
-            self
-        }
-
         /// Specify the number of stop bits
         pub fn stopbits(mut self, stopbits: StopBits) -> Self {
             self.stopbits = stopbits;
@@ -595,9 +592,9 @@ macro_rules! usart {
                             .m1()
                             .clear_bit()
                             .m0()
-                            .variant(match config.wordlength {
-                                WordLength::DataBits8 => M0::BIT8,
-                                WordLength::DataBits9 => M0::BIT9,
+                            .variant(match config.parity {
+                                Parity::ParityNone => M0::BIT8,
+                                _ => M0::BIT9,
                             }).pce()
                             .variant(match config.parity {
                                 Parity::ParityNone => PCE::DISABLED,