godspeed_sdk/

mmio.rs

// SPDX-License-Identifier: Apache-2.0
//! Memory-mapped I/O access for userspace driver services (§12, §18).
//!
//! This is the SDK's audited hardware-access layer - one of the places outside
//! the kernel where `unsafe` is permitted. §18.1 names this file alongside
//! `dma.rs`, the syscall ABI (`raw_syscall`) and `adversarial.rs`; this said
//! "one of the two places", which `dma.rs`'s own header already contradicted. Driver services use the safe [`Mmio`] wrapper and never
//! write `unsafe` themselves; every volatile access below carries a SAFETY
//! argument, and `Mmio` is only constructable inside this crate (from a
//! kernel-granted mapping), so its base pointer is always valid by construction.

/// A mapped MMIO region granted to a driver (e.g. via
/// [`crate::ServiceContext::xhci_mmio`]). Read/write device registers by byte
/// offset. All accesses are volatile - never reordered or elided - and target
/// the uncached device registers directly, with no kernel mediation (§12).
#[derive(Clone, Copy)]
pub struct Mmio {
    base: *mut u8,
    len: usize,
}

impl Mmio {
    /// Wrap a kernel-granted MMIO base virtual address + window length. Crate-internal: only the
    /// SDK constructs an `Mmio`, and only from a VA the kernel mapped for this driver, which is what
    /// makes the volatile accesses below sound.
    pub(crate) fn new(base: *mut u8, len: usize) -> Self {
        Self { base, len }
    }

    /// Length of the mapped register window in bytes.
    #[inline]
    pub fn len(&self) -> usize {
        self.len
    }

    /// Bounds-check an `off..off+size` access against the mapped window (SEC-4). An out-of-window
    /// MMIO access would otherwise fault (the window is exactly what the kernel mapped) - this turns
    /// that into a loud, explicit panic naming the cause instead of a bare page fault (§26.7).
    /// `checked_add` so a wrapping `off` cannot slip past.
    ///
    /// It also refuses an access that is not aligned to its own size. An unaligned volatile access is
    /// undefined behaviour in Rust, and on Device memory an alignment fault on Arm; this "must be
    /// aligned" was a comment until 2026-10-10, so a safe call could reach it (`backlog/fixed/80` S6). The
    /// ADDRESS is checked, not only the offset, so a window that does not start on a boundary is
    /// caught too.
    #[inline]
    fn check(&self, off: usize, size: usize) {
        assert!(
            off.checked_add(size).map_or(false, |end| end <= self.len),
            "Mmio access out of window bounds",
        );
        assert!(
            (self.base as usize).wrapping_add(off) % size == 0,
            "Mmio access not aligned to its size",
        );
    }

    /// Read an 8-bit register at `off` bytes from the base.
    #[inline]
    pub fn read8(&self, off: usize) -> u8 {
        self.check(off, 1);
        // SAFETY: `base` is a valid kernel-granted MMIO mapping (Mmio is only
        // constructed from one); check() bounded `off` within the mapped window.
        unsafe { core::ptr::read_volatile(self.base.add(off)) }
    }

    /// Read a 16-bit register at `off` (must be 2-byte aligned).
    #[inline]
    pub fn read16(&self, off: usize) -> u16 {
        self.check(off, 2);
        // SAFETY: as `read8`; check() bounded the access and proved it 2-byte aligned.
        unsafe { core::ptr::read_volatile(self.base.add(off) as *const u16) }
    }

    /// Read a 32-bit register at `off` (must be 4-byte aligned).
    #[inline]
    pub fn read32(&self, off: usize) -> u32 {
        self.check(off, 4);
        // SAFETY: as `read8`; check() bounded the access and proved it 4-byte aligned.
        unsafe { core::ptr::read_volatile(self.base.add(off) as *const u32) }
    }

    /// Write an 8-bit register at `off`.
    #[inline]
    pub fn write8(&self, off: usize, val: u8) {
        self.check(off, 1);
        // SAFETY: as `read8`; volatile device-register write.
        unsafe { core::ptr::write_volatile(self.base.add(off), val) }
    }

    /// Write a 16-bit register at `off` (must be 2-byte aligned).
    #[inline]
    pub fn write16(&self, off: usize, val: u16) {
        self.check(off, 2);
        // SAFETY: as `read8`; check() bounded the write and proved it 2-byte aligned.
        unsafe { core::ptr::write_volatile(self.base.add(off) as *mut u16, val) }
    }

    /// Write a 32-bit register at `off` (must be 4-byte aligned).
    #[inline]
    pub fn write32(&self, off: usize, val: u32) {
        self.check(off, 4);
        // SAFETY: as `read8`; check() bounded the write and proved it 4-byte aligned.
        unsafe { core::ptr::write_volatile(self.base.add(off) as *mut u32, val) }
    }

    /// Read a 64-bit register at `off` (must be 8-byte aligned). For the
    /// controller's 64-bit registers (DCBAAP, CRCR, ERSTBA, ERDP).
    #[inline]
    pub fn read64(&self, off: usize) -> u64 {
        self.check(off, 8);
        // SAFETY: as `read8`; check() bounded the access and proved it 8-byte aligned.
        unsafe { core::ptr::read_volatile(self.base.add(off) as *const u64) }
    }

    /// Write a 64-bit register at `off` (must be 8-byte aligned).
    #[inline]
    pub fn write64(&self, off: usize, val: u64) {
        self.check(off, 8);
        // SAFETY: as `read8`; check() bounded the write and proved it 8-byte aligned.
        unsafe { core::ptr::write_volatile(self.base.add(off) as *mut u64, val) }
    }
}

/// A mapped framebuffer granted to the `console` service (via
/// [`crate::ServiceContext::framebuffer`]), plus the geometry needed to address a pixel in it.
///
/// Unlike [`Mmio`], which exists to read and write device *registers* one at a time, a framebuffer is
/// addressed in bulk - long contiguous runs, whole-row fills, a full-screen clear - so this hands out a
/// **slice** rather than word accessors. That is what lets the renderer above it be ordinary
/// bounds-checked Rust with no `unsafe` at all (§18.2 forbids `unsafe` in a service outright), and it
/// keeps write-combining and write-buffer gathering available: a pixel run is one `copy_from_slice`,
/// not N volatile stores.
///
/// The handle **owns** the mapping for the service's lifetime and is not `Copy`, so there is exactly one
/// route to those bytes and it is a `&mut self` borrow. That matters beyond tidiness: the alternative
/// spelling, a `&'static mut [u8]` field, is an unowned mutable global in everything but name.
pub struct Framebuffer {
    base: *mut u8,
    len: usize,
    /// Bytes per scanline.
    pub pitch: usize,
    /// Bytes per pixel.
    pub bpp: usize,
    /// Visible width in pixels.
    pub width: usize,
    /// Visible height in pixels.
    pub height: usize,
    /// Bit position of the red channel within a pixel.
    pub r_shift: u32,
    /// Bit position of the green channel within a pixel.
    pub g_shift: u32,
    /// Bit position of the blue channel within a pixel.
    pub b_shift: u32,
}

impl Framebuffer {
    /// Wrap a kernel-granted framebuffer mapping. Crate-internal: only the SDK constructs one, and only
    /// from the VA and geometry the kernel wrote into this service's context page.
    #[allow(clippy::too_many_arguments)]
    pub(crate) fn new(
        base: *mut u8,
        len: usize,
        pitch: usize,
        bpp: usize,
        width: usize,
        height: usize,
        r_shift: u32,
        g_shift: u32,
        b_shift: u32,
    ) -> Self {
        Self { base, len, pitch, bpp, width, height, r_shift, g_shift, b_shift }
    }

    /// The framebuffer's bytes, for rendering.
    ///
    /// The one `unsafe` a display costs. From here up, every pixel write is a bounds-checked slice
    /// write: a wrong offset paints nothing rather than corrupting memory.
    #[inline]
    pub fn bytes_mut(&mut self) -> &mut [u8] {
        // SAFETY: the kernel mapped exactly [base, base + len) into this service's address space as
        // writable USER memory at spawn (the framebuffer grant), and that mapping lives as long as the
        // service does - it is torn down only when the address space is, on death. `&mut self` gives
        // exclusive access, and `Framebuffer` is neither `Copy` nor `Clone`, so no second live slice to
        // these bytes can exist. `len` is the kernel's own `pitch * height`.
        unsafe { core::slice::from_raw_parts_mut(self.base, self.len) }
    }

    /// Length of the mapping in bytes (`pitch * height`).
    #[inline]
    pub fn len(&self) -> usize {
        self.len
    }

    /// Whether the mapping is empty. Present because clippy asks for it beside `len`; a granted
    /// framebuffer is never zero-length.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }
}