doc: tighten cts/hw control flow wording

src/config.rs

@@ -151,12 +151,12 @@ pub struct Config {
     pub extra_stop_bits: bool,
     /// Whether parity bits should be used.
     pub parity: Parity,
-    /// Whether to wait for CTS before sending.
+    /// Whether transmission should honor the remote CTS signal.
     ///
     /// Only activate this if your hardware connects the CTS/RTS flow control
-    /// signals and you wish to make use of them. Keep this setting disabled to
-    /// make sure that the UART works when CTS is left disconnected.
-    pub flow_control: bool,
+    /// signals and you wish to make use of them. Leave it disabled for
+    /// connections that only use TX/RX/GND, where CTS might remain deasserted.
+    pub check_cts_before_sending: bool,
 }
 
 impl Config {
@@ -182,7 +182,7 @@ impl Config {
         data_bits: WordLength::EightBits,
         extra_stop_bits: false,
         parity: Parity::Disabled,
-        flow_control: false,
+        check_cts_before_sending: false,
     };
 }
 

src/lib.rs

@@ -285,6 +285,11 @@ mod tty;
 /// [`Uart16550::new_mmio()`] create an instance of a device with the
 /// corresponding backend.
 ///
+/// # Synchronous, Asynchronous, and Interrupt-driven Operation
+///
+/// This is a **synchronous** driver that exposes interrupt configuration,
+/// making it possible to build an asynchronous, interrupt-driven driver on top.
+///
 /// # Hints for Usage on Real Hardware
 ///
 /// Please note that real hardware often behaves quite differently. Just because
@@ -398,6 +403,8 @@ impl<B: Backend> Uart16550<B> {
     /// is done only in a context where such operations are valid and safe
     /// (e.g., you have exclusive device access).
     ///
+    /// It is recommended to disable interrupts before calling this function.
+    ///
     /// Further, the serial config must match the expectations of the receiver
     /// on the other side. Otherwise, garbage will be received.
     pub fn init(&mut self, config: Config) -> Result<(), InitError> {
@@ -677,9 +684,7 @@ impl<B: Backend> Uart16550<B> {
             return Err(ByteSendError::NoCapacity);
         }
 
-        // Software flow control. TODO, what to do with hardware flow control?
-        // Is this something we can and should support?
-        if self.config.flow_control {
+        if self.config.check_cts_before_sending {
             // The CTS line is meaningless when in loopback mode.
             let mcr = self.mcr();
             if !mcr.contains(MCR::LOOP_BACK) {