feat: add try_send_raw and try_receive

Signed-off-by: Martin Kröning <martin.kroening@eonerc.rwth-aachen.de>

Author: mkroening

Changelog.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+- Add `try_send_raw` and `try_receive` ([#34](https://github.com/rust-osdev/uart_16550/pull/34))
+
 # 0.3.0 – 2023-08-04
 
 - Internal rewrite of port operations to work on both `x86` and `x86_64` ([#29](https://github.com/rust-osdev/uart_16550/pull/29))

src/lib.rs

@@ -62,12 +62,17 @@
 #![warn(missing_docs)]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 
+use core::fmt;
+
 use bitflags::bitflags;
 
-macro_rules! wait_for {
+macro_rules! retry_until_ok {
     ($cond:expr) => {
-        while !$cond {
-            core::hint::spin_loop()
+        loop {
+            if let Ok(ok) = $cond {
+                break ok;
+            }
+            core::hint::spin_loop();
         }
     };
 }
@@ -102,3 +107,14 @@ bitflags! {
         // 6 and 7 unknown
     }
 }
+
+/// The `WouldBlockError` error indicates that the serial device was not ready immediately.
+#[non_exhaustive]
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct WouldBlockError;
+
+impl fmt::Display for WouldBlockError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("serial device not ready")
+    }
+}

src/mmio.rs

@@ -3,7 +3,7 @@ use core::{
     sync::atomic::{AtomicPtr, Ordering},
 };
 
-use crate::LineStsFlags;
+use crate::{LineStsFlags, WouldBlockError};
 
 /// A memory-mapped UART.
 #[derive(Debug)]
@@ -90,18 +90,36 @@ impl MmioSerialPort {
 
     /// Sends a raw byte on the serial port, intended for binary data.
     pub fn send_raw(&mut self, data: u8) {
-        wait_for!(self.line_sts().contains(LineStsFlags::OUTPUT_EMPTY));
-        let self_data = self.data.load(Ordering::Relaxed);
-        unsafe {
-            self_data.write(data);
+        retry_until_ok!(self.try_send_raw(data))
+    }
+
+    /// Tries to send a raw byte on the serial port, intended for binary data.
+    pub fn try_send_raw(&mut self, data: u8) -> Result<(), WouldBlockError> {
+        if self.line_sts().contains(LineStsFlags::OUTPUT_EMPTY) {
+            let self_data = self.data.load(Ordering::Relaxed);
+            unsafe {
+                self_data.write(data);
+            }
+            Ok(())
+        } else {
+            Err(WouldBlockError)
         }
     }
 
     /// Receives a byte on the serial port.
     pub fn receive(&mut self) -> u8 {
-        wait_for!(self.line_sts().contains(LineStsFlags::INPUT_FULL));
-        let self_data = self.data.load(Ordering::Relaxed);
-        unsafe { self_data.read() }
+        retry_until_ok!(self.try_receive())
+    }
+
+    /// Tries to receive a byte on the serial port.
+    pub fn try_receive(&mut self) -> Result<u8, WouldBlockError> {
+        if self.line_sts().contains(LineStsFlags::INPUT_FULL) {
+            let self_data = self.data.load(Ordering::Relaxed);
+            let data = unsafe { self_data.read() };
+            Ok(data)
+        } else {
+            Err(WouldBlockError)
+        }
     }
 }
 

src/port.rs

@@ -1,6 +1,6 @@
 use core::fmt;
 
-use crate::LineStsFlags;
+use crate::{LineStsFlags, WouldBlockError};
 
 /// A x86 I/O port-mapped UART.
 #[cfg_attr(docsrs, doc(cfg(any(target_arch = "x86", target_arch = "x86_64"))))]
@@ -115,17 +115,33 @@ impl SerialPort {
 
     /// Sends a raw byte on the serial port, intended for binary data.
     pub fn send_raw(&mut self, data: u8) {
-        unsafe {
-            wait_for!(self.line_sts().contains(LineStsFlags::OUTPUT_EMPTY));
-            x86::io::outb(self.port_data(), data);
+        retry_until_ok!(self.try_send_raw(data))
+    }
+
+    /// Tries to send a raw byte on the serial port, intended for binary data.
+    pub fn try_send_raw(&mut self, data: u8) -> Result<(), WouldBlockError> {
+        if self.line_sts().contains(LineStsFlags::OUTPUT_EMPTY) {
+            unsafe {
+                x86::io::outb(self.port_data(), data);
+            }
+            Ok(())
+        } else {
+            Err(WouldBlockError)
         }
     }
 
     /// Receives a byte on the serial port.
     pub fn receive(&mut self) -> u8 {
-        unsafe {
-            wait_for!(self.line_sts().contains(LineStsFlags::INPUT_FULL));
-            x86::io::inb(self.port_data())
+        retry_until_ok!(self.try_receive())
+    }
+
+    /// Tries to receive a byte on the serial port.
+    pub fn try_receive(&mut self) -> Result<u8, WouldBlockError> {
+        if self.line_sts().contains(LineStsFlags::INPUT_FULL) {
+            let data = unsafe { x86::io::inb(self.port_data()) };
+            Ok(data)
+        } else {
+            Err(WouldBlockError)
         }
     }
 }