Update and integrate uart_16550 to 0.8 [Rebase & FF]

Cargo.toml

@@ -54,7 +54,7 @@ quote = { version = "1" }
 scroll = { version = "0.13", default-features = false, features = ["derive"]}
 spin = { version = "0.12" }
 syn = { version = "3" }
-uart_16550 = { version = "0.3.2" }
+uart_16550 = { version = "0.8" }
 corosensei = { version = "0.3.4", default-features = false }
 uuid = { version = "1.23", default-features = false }
 zerocopy = { version = "0.8" }
@@ -90,10 +90,6 @@ suspicious = { level = "warn", priority = -1 }
 #     `the "_support" suffix in the feature name "v1_resource_descriptor_support" is redundant`
 #   This is allowed until the v1_resource_descriptor_support feature is dropped.
 redundant_feature_names = "allow"
-# cargo::multiple_crate_versions violation:
-#  `multiple versions for dependency `bitflags`: 1.3.2, 2.13.1 `
-# This is allowed until the uart_16550 crate is updated to v0.6+ which removes the bitflags v1 dependency.
-multiple_crate_versions = "allow"
 # pedantic::cast_possible_truncation - Temporarily allowed until all cases are updated (each fix needs a lot of
 #                                      attention) to determine if the truncation is intentional and safe or not.
 cast_possible_truncation = "allow"

core/patina_debugger/README.md

@@ -44,7 +44,8 @@ The self-hosted debugger is lightweight and tightly integrated with Patina, offe
 
 ## Platform Integration
 
-1. Instantiate a `PatinaDebugger` with the platform UART configuration (for example, `Uart16550::Io { base: 0x3F8 }`).
+1. Instantiate a `PatinaDebugger` with the platform UART configuration (for example,
+   `unsafe { Uart16550::new_io(0x3F8) }`).
 2. Apply any policy overrides such as `.with_force_enable`, `.with_log_policy`, or `.with_transport_init` when
    if the debugger must initialize the transport.
 3. Register the debugger using `patina_debugger::set_debugger(&DEBUGGER)` before the Patina DXE Core starts dispatching

deny.toml

@@ -170,12 +170,7 @@ deny = [
 #exact = true
 
 # Certain crates/versions that will be skipped when doing duplicate detection.
-skip = [
-    #"ansi_term@0.11.0",
-    #{ crate = "ansi_term@0.11.0", reason = "you can specify a reason why it can't be updated/removed" },
-
-    { crate = "bitflags", reason = "Need https://github.com/gz/rust-x86/pull/150 to be merged into rust-x86." }
-]
+skip = []
 # Similarly to `skip` allows you to skip certain crates during duplicate
 # detection. Unlike skip, it also includes the entire tree of transitive
 # dependencies starting at the specified crate, up to a certain depth, which is

docs/src/dev/principles/abstractions.md

@@ -142,40 +142,47 @@ impl SerialIO for Terminal {
     }
 }
 
-use uart_16550::MmioSerialPort;
+use core::num::NonZero;
+use uart_16550::backend::MmioBackend;
+use uart_16550::{Config, Uart16550 as InnerUart16550};
 struct Uart16550(usize);
 
 impl Uart16550 {
     fn new(addr: usize) -> Self {
         Self(addr)
     }
+
+    /// Returns `None` if the address is rejected or the device can't be detected.
+    fn port(&self) -> Option<InnerUart16550<MmioBackend>> {
+        let addr = core::ptr::NonNull::<u8>::with_exposed_provenance(NonZero::new(self.0)?);
+        // SAFETY: `self.0` is assumed to be a valid, exclusively-owned MMIO address for this example.
+        unsafe { InnerUart16550::new_mmio(addr, 1) }.ok()
+    }
 }
 
 impl SerialIO for Uart16550 {
     fn init(&self) {
-        unsafe { MmioSerialPort::new(self.0).init() };
+        if let Some(mut port) = self.port() {
+            let _ = port.init(Config::DEFAULT);
+        }
     }
 
     fn write(&self, buffer: &[u8]) {
-        let mut port = unsafe { MmioSerialPort::new(self.0) };
-
-        for b in buffer {
-            port.send(*b);
+        if let Some(mut port) = self.port() {
+            port.send_bytes_exact(buffer);
         }
     }
 
     fn read(&self) -> u8 {
-        let mut port = unsafe { MmioSerialPort::new(self.0) };
-        port.receive()
+        let mut byte = 0u8;
+        if let Some(mut port) = self.port() {
+            port.receive_bytes_exact(core::slice::from_mut(&mut byte));
+        }
+        byte
     }
 
     fn try_read(&self) -> Option<u8> {
-        let mut port = unsafe { MmioSerialPort::new(self.0) };
-        if let Ok(value) = port.try_receive() {
-            Some(value)
-        } else {
-            None
-        }
+        self.port()?.try_receive_byte().ok()
     }
 }
 

sdk/patina/src/debug/log.rs

@@ -3,29 +3,31 @@
 //! ## Examples
 //!
 //! ```rust ignore
-//! use patina::debug::log::SerialLogger;
-//! use patina::peripheral::serial::SerialIO;
-//! use serial_writer::*;
+//! use patina::debug::log::{Format, SerialLogger};
+//! use patina::peripheral::serial::Terminal;
+//! use patina::peripheral::serial::uart::{Uart16550, UartPl011};
 //!
 //! let terminal_logger = SerialLogger::new(
 //!    Format::Standard,
 //!    &[("crate1::module", log::LevelFilter::Off)],
 //!    log::LevelFilter::Trace,
-//!    Terminal,
+//!    Terminal {},
 //! );
 //!
+//! // SAFETY: 0x3F8 is the standard COM1 I/O port, exclusively owned for the logger's lifetime.
 //! let uart_16550_logger = SerialLogger::new(
 //!    Format::Standard,
 //!    &[("crate1::module", log::LevelFilter::Off)],
 //!    log::LevelFilter::Trace,
-//!    Uart16550::new(Interface::Io(0x3F8)),
+//!    unsafe { Uart16550::new_io(0x3F8) },
 //! );
 //!
+//! // SAFETY: 0x3F8_0000 is a valid, exclusively-owned PL011 MMIO base address on this platform.
 //! let uart_pl011_logger = SerialLogger::new(
 //!    Format::Standard,
 //!    &[("crate1::module", log::LevelFilter::Off)],
 //!    log::LevelFilter::Trace,
-//!    UartPl011::new(0x3F8_0000),
+//!    unsafe { UartPl011::new(0x3F8_0000) },
 //! );
 //! ```
 //!