Merge pull request #50 from phip1611/safety

Enhance MmioAddress safety and fix AArch64 instruction emission

Author: phip1611

.github/workflows/rust.yml

@@ -16,9 +16,9 @@ jobs:
       fail-fast: false
       matrix:
         runs-on:
-          - macos-latest
-          - ubuntu-latest
-          - windows-latest
+          - macos-latest # aarch64
+          - ubuntu-latest # x86_64
+          - windows-latest # x86_64
         rust:
           - stable
           - nightly

CHANGELOG.md

@@ -7,6 +7,9 @@
 - New public methods:
   - `Uart16550::ready_to_receive()`
   - `Uart16550::ready_to_send()`
+- Documentation improvements
+- Internal safety fixes (there was no UB, just making the internal code more
+  robust)
 
 ## 0.5.0 - 2026-03-20
 

README.md

@@ -14,19 +14,23 @@ support for MMIO-mapped devices.
 Serial ports are especially useful for debugging or operating system
 learning projects. See [`Uart16550`] to get started.
 
+[`Uart16550`]: https://docs.rs/uart_16550/latest/uart_16550/struct.Uart16550.html
+
 ## Features
 
 - ✅ Full configure, transmit, receive, and interrupt support for UART
   16550–compatible devices
 - ✅ High-level, ergonomic abstractions and types paired with support for
   plain integers
-- ✅ Very easy to integrate, highly configurable when needed
+- ✅ Straightforward to integrate, highly configurable when needed
 - ✅ Validated on **real hardware** as well as across different virtual
   machines
 - ✅ Fully type-safe and derived directly from the official
   [specification][uart]
 - ✅ Supports both **x86 port-mapped I/O** and **memory-mapped I/O** (MMIO)
 - ✅ `no_std`-compatible and allocation-free by design
+- ✅ Compatible with all architectures supported by Rust (x86/x86_64, ARM,
+    RISC-V, ...)
 
 ## Focus, Scope & Limitations
 

src/backend.rs

@@ -12,13 +12,20 @@ use crate::spec::NUM_REGISTERS;
 use core::arch::asm;
 use core::fmt::Debug;
 use core::num::NonZeroU8;
-use core::ptr::{self, read_volatile, write_volatile};
+use core::ptr::NonNull;
 
 mod private {
     pub trait Sealed {}
 }
 
 /// Abstraction over register addresses in [`Backend`].
+///
+/// # Safety
+///
+/// All implementations and instances of this trait are created within this
+/// crate and do follow all safety invariants. API users don't get access to the
+/// underlying register addresses, nor can they construct one themselves, as this
+/// type et al. are sealed.
 pub trait RegisterAddress: Copy + Clone + Debug + Sized + private::Sealed {
     /// Adds a byte offset onto the base register address.
     fn add_offset(self, offset: u8) -> Self;
@@ -49,7 +56,7 @@ impl private::Sealed for PortIoAddress {}
 ///
 /// See [`RegisterAddress`].
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Hash)]
-pub struct MmioAddress(pub(crate) *mut u8);
+pub struct MmioAddress(pub(crate) NonNull<u8>);
 
 // SAFETY: `Uart16550` is not `Sync`, so concurrent access from multiple
 // threads is not possible through this type's API alone. Implementing `Send`
@@ -239,6 +246,67 @@ impl Backend for PioBackend {
     }
 }
 
+/// Arch-specific quirks to access hardware.
+///
+/// On MMIO-access on aarch64, LLVM may emit instructions that are not properly
+/// virtualizable. We therefore need to be more explicit about the instruction.
+/// More info: <https://github.com/rust-lang/rust/issues/131894>
+mod arch {
+    use crate::backend::MmioAddress;
+    #[cfg(any(doc, not(target_arch = "aarch64")))]
+    use core::ptr;
+
+    /// Wrapper around [`ptr::read_volatile`].
+    #[cfg(target_arch = "aarch64")]
+    #[inline(always)]
+    pub unsafe fn mmio_read_register(address: MmioAddress) -> u8 {
+        let ptr = address.0.as_ptr();
+        let ret: u8;
+        // SAFETY: Caller ensures the address is valid MMIO memory.
+        unsafe {
+            core::arch::asm!(
+                "ldrb {ret:w}, [{ptr}]",
+                ptr = in(reg) ptr,
+                ret = out(reg) ret,
+                options(nostack, preserves_flags)
+            );
+        }
+        ret
+    }
+
+    /// Wrapper around [`ptr::read_volatile`].
+    #[cfg(not(target_arch = "aarch64"))]
+    #[inline(always)]
+    pub unsafe fn mmio_read_register(address: MmioAddress) -> u8 {
+        // SAFETY: Caller ensures the address is valid MMIO memory.
+        unsafe { ptr::read_volatile(address.0.as_ptr()) }
+    }
+
+    /// Wrapper around [`ptr::write_volatile`].
+    #[cfg(target_arch = "aarch64")]
+    #[inline(always)]
+    pub unsafe fn mmio_write_register(address: MmioAddress, value: u8) {
+        let ptr = address.0.as_ptr();
+        // SAFETY: Caller ensures the address is valid MMIO memory.
+        unsafe {
+            core::arch::asm!(
+                "strb {val:w}, [{ptr}]",
+                val = in(reg) value,
+                ptr = in(reg) ptr,
+                options(nostack, preserves_flags)
+            );
+        }
+    }
+
+    /// Wrapper around [`ptr::write_volatile`].
+    #[cfg(not(target_arch = "aarch64"))]
+    #[inline(always)]
+    pub unsafe fn mmio_write_register(address: MmioAddress, value: u8) {
+        // SAFETY: Caller ensures the address is valid MMIO memory.
+        unsafe { ptr::write_volatile(address.0.as_ptr(), value) }
+    }
+}
+
 /// MMIO-mapped UART 16550.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Hash)]
 pub struct MmioBackend {
@@ -264,23 +332,23 @@ impl Backend for MmioBackend {
 
     #[inline(always)]
     unsafe fn _read_register(&mut self, address: MmioAddress) -> u8 {
-        debug_assert_ne!(address.0, ptr::null_mut());
         debug_assert!(address >= self.base());
         let upper_bound_incl = (NUM_REGISTERS - 1) * usize::from(u8::from(self.stride));
-        debug_assert!(address.0 <= self.base().0.wrapping_add(upper_bound_incl));
+        // Address is in the device's address range
+        debug_assert!(address.0.as_ptr() <= self.base().0.as_ptr().wrapping_add(upper_bound_incl));
 
         // SAFETY: The caller ensured that the MMIO address is safe to use.
-        unsafe { read_volatile(address.0) }
+        unsafe { arch::mmio_read_register(address) }
     }
 
     #[inline(always)]
     unsafe fn _write_register(&mut self, address: MmioAddress, value: u8) {
-        debug_assert_ne!(address.0, ptr::null_mut());
         debug_assert!(address >= self.base());
         let upper_bound_incl = (NUM_REGISTERS - 1) * usize::from(u8::from(self.stride));
-        debug_assert!(address.0 <= self.base().0.wrapping_add(upper_bound_incl));
+        // Address is in the device's address range
+        debug_assert!(address.0.as_ptr() <= self.base().0.as_ptr().wrapping_add(upper_bound_incl));
 
         // SAFETY: The caller ensured that the MMIO address is safe to use.
-        unsafe { write_volatile(address.0, value) }
+        unsafe { arch::mmio_write_register(address, value) }
     }
 }

src/error.rs

@@ -16,8 +16,10 @@ use core::fmt::Display;
 /// [NUM_REGISTERS]: crate::spec::NUM_REGISTERS
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub enum InvalidAddressError<A: RegisterAddress> {
-    /// The specified address is invalid because it is either null or doesn't allow
-    /// for <code>[NUM_REGISTERS] - 1</code> subsequent addresses.
+    /// The specified address is null.
+    Null,
+    /// The given base address is invalid, e.g., it cannot accommodate
+    /// <code>[NUM_REGISTERS] - 1</code> consecutive addresses.
     ///
     /// [NUM_REGISTERS]: crate::spec::NUM_REGISTERS
     InvalidBaseAddress(A),
@@ -31,6 +33,9 @@ pub enum InvalidAddressError<A: RegisterAddress> {
 impl<A: RegisterAddress> Display for InvalidAddressError<A> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
+            Self::Null => {
+                write!(f, "address is null")
+            }
             Self::InvalidBaseAddress(addr) => {
                 write!(f, "invalid register address: {addr:x?}")
             }

src/lib.rs

@@ -22,13 +22,15 @@
 //!   16550–compatible devices
 //! - ✅ High-level, ergonomic abstractions and types paired with support for
 //!   plain integers
-//! - ✅ Very easy to integrate, highly configurable when needed
+//! - ✅ Straightforward to integrate, highly configurable when needed
 //! - ✅ Validated on **real hardware** as well as across different virtual
 //!   machines
 //! - ✅ Fully type-safe and derived directly from the official
 //!   [specification][uart]
 //! - ✅ Supports both **x86 port-mapped I/O** and **memory-mapped I/O** (MMIO)
 //! - ✅ `no_std`-compatible and allocation-free by design
+//! - ✅ Compatible with all architectures supported by Rust (x86/x86_64, ARM,
+//!   RISC-V, ...)
 //!
 //! ## Focus, Scope & Limitations
 //!
@@ -147,6 +149,7 @@ use crate::spec::{FIFO_SIZE, NUM_REGISTERS, calc_baud_rate, calc_divisor};
 use core::cmp;
 use core::hint;
 use core::num::NonZeroU8;
+use core::ptr::NonNull;
 
 pub mod backend;
 pub mod spec;
@@ -291,16 +294,14 @@ impl Uart16550<MmioBackend> {
         base_address: *mut u8,
         stride: u8,
     ) -> Result<Self, InvalidAddressError<MmioAddress>> {
+        let base_address = NonNull::new(base_address).ok_or(InvalidAddressError::Null)?;
         let base_address = MmioAddress(base_address);
-        if base_address.0.is_null() {
-            return Err(InvalidAddressError::InvalidBaseAddress(base_address));
-        }
 
         if stride == 0 || !stride.is_power_of_two() {
             return Err(InvalidAddressError::InvalidStride(stride));
         }
 
-        if (base_address.0 as usize)
+        if (base_address.0.as_ptr() as usize)
             .checked_add((NUM_REGISTERS - 1) * stride as usize)
             .is_none()
         {

src/tty.rs

@@ -56,13 +56,11 @@ impl<A: RegisterAddress + 'static> Error for Uart16550TtyError<A> {
     }
 }
 
-/// Thin opinionated abstraction over [`Uart16550`] that helps to send Rust
-/// strings easily to the other side, assuming the remote is a TTY (terminal).
+/// Lightweight, opinionated wrapper around [`Uart16550`] for sending Rust
+/// strings to a connected TTY (terminal).
 ///
-/// It is especially suited as very easy way to see something when you develop
-/// and test things in a VM.
-///
-/// It implements [`fmt::Write`].
+/// Ideal for quickly observing debug output during VM development and testing.
+/// It implements [`fmt::Write`] allowing the use of `write!()`.
 ///
 /// # Example
 /// ```rust,no_run