uefi: improve clarity over timeout in SerialIoMode

Author: phip1611

uefi-raw/src/protocol/console/serial.rs

@@ -62,9 +62,9 @@ bitflags! {
 pub struct SerialIoMode {
     /// Bitmask of the control bits that this device supports.
     pub control_mask: ControlBits,
-    /// If applicable, the number of microseconds to wait before assuming an
+    /// The number of microseconds (µs) to wait before assuming an read or write
     /// operation timed out.
-    pub timeout: u32,
+    pub timeout_us: u32,
     /// Device's baud rate, or 0 if unknown.
     pub baud_rate: u64,
     /// Size in character's of the device's buffer.

uefi-test-runner/src/main.rs

@@ -10,6 +10,7 @@ extern crate alloc;
 
 use alloc::string::ToString;
 use alloc::vec::Vec;
+use core::time::Duration;
 use uefi::mem::memory_map::MemoryMap;
 use uefi::prelude::*;
 use uefi::proto::console::serial::Serial;
@@ -111,7 +112,7 @@ fn send_request_helper(serial: &mut Serial, request: HostRequest) -> Result {
 
     // Set a 10 second timeout for the read and write operations.
     let mut io_mode = *serial.io_mode();
-    io_mode.timeout = 10_000_000;
+    io_mode.timeout_us = Duration::from_secs(10).as_micros() as u32;
     serial.set_attributes(&io_mode)?;
 
     // Send a screenshot request to the host.

uefi/src/proto/console/serial.rs

@@ -59,7 +59,7 @@ impl Serial {
                 &mut self.0,
                 mode.baud_rate,
                 mode.receive_fifo_depth,
-                mode.timeout,
+                mode.timeout_us,
                 mode.parity,
                 mode.data_bits as u8,
                 mode.stop_bits,
@@ -90,7 +90,9 @@ impl Serial {
     /// so far.
     ///
     /// To prevent missing data (overrun), it is recommended to call this
-    /// function multiple times.
+    /// function multiple times. To prevent long blocking times, i.e., to only
+    /// read what is available as of calling this function, it is recommended to
+    /// set the timeout in [`IoMode`] to 1 µs.
     pub fn read(&mut self, data: &mut [u8]) -> Result<usize /* read bytes*/> {
         let mut buffer_size = data.len();
         let status = unsafe { (self.0.read)(&mut self.0, &mut buffer_size, data.as_mut_ptr()) };