Re: [PATCH v3 01/19] rust: io: add dynamically-sized `Region` type

["Gary Guo" <gary@garyguo.net>]

On Mon Jun 8, 2026 at 8:58 PM BST, Gary Guo wrote:
> Currently many I/O related structs carry a `SIZE` parameter to denote the
> minimum size of the I/O region, while they also carry a field indicating
> the actual size. Proliferation of the pattern creates a lot of duplicated
> code, and makes it hard to create typed views of I/O.
>
> Introduce a `Region` type that carries the `SIZE` parameter. It is a
> wrapper of `[u8]`, which makes it dynamically sized with a metadata of
> `usize`. This way, pointers to `Region` naturally carry size information.
> This type is required to be naturally aligned.
>
> Expose the minimum size information via `MIN_SIZE` constant of the
> `KnownSize` trait. Similarly, expose the minimum alignment information via
> `KnownSize::MIN_ALIGN`.
>
> With these changes, it is possible to add an associated type to `Io` trait
> to represent the type of I/O region. For untyped regions, this is the newly
> added `Region` type. Remove `IoKnownSize` as it is no longer necessary. Use
> the same mechanism to indicate minimum size of PCI config spaces.
>
> Signed-off-by: Gary Guo <gary@garyguo.net>
> ---
>  rust/kernel/devres.rs |   6 +--
>  rust/kernel/io.rs     | 131 +++++++++++++++++++++++++++++++++-----------------
>  rust/kernel/pci.rs    |   1 -
>  rust/kernel/pci/io.rs |  40 ++++++---------
>  rust/kernel/ptr.rs    |  12 +++++
>  5 files changed, 116 insertions(+), 74 deletions(-)
>
> diff --git a/rust/kernel/devres.rs b/rust/kernel/devres.rs
> index 11ce500e9b76..ed30ccc6e68e 100644
> --- a/rust/kernel/devres.rs
> +++ b/rust/kernel/devres.rs
> @@ -68,7 +68,6 @@ struct Inner<T> {
>  ///     devres::Devres,
>  ///     io::{
>  ///         Io,
> -///         IoKnownSize,
>  ///         Mmio,
>  ///         MmioRaw,
>  ///         PhysAddr, //
> @@ -297,10 +296,7 @@ pub fn device(&self) -> &Device {
>      /// use kernel::{
>      ///     device::Core,
>      ///     devres::Devres,
> -    ///     io::{
> -    ///         Io,
> -    ///         IoKnownSize, //
> -    ///     },
> +    ///     io::Io,
>      ///     pci, //
>      /// };
>      ///
> diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
> index fcc7678fd9e3..dcf3b40ffa48 100644
> --- a/rust/kernel/io.rs
> +++ b/rust/kernel/io.rs
> @@ -6,7 +6,11 @@
>  
>  use crate::{
>      bindings,
> -    prelude::*, //
> +    prelude::*,
> +    ptr::{
> +        Alignment,
> +        KnownSize, //
> +    }, //
>  };
>  
>  pub mod mem;
> @@ -31,6 +35,59 @@
>  /// `CONFIG_PHYS_ADDR_T_64BIT`, and it can be a u64 even on 32-bit architectures.
>  pub type ResourceSize = bindings::resource_size_t;
>  
> +/// Untyped I/O region.
> +///
> +/// This type can be used when an I/O region without known type information has a compile-time known
> +/// minimum size (and a runtime known actual size).
> +///
> +/// This must be naturally aligned to `usize`.
> +///
> +/// # Invariants
> +///
> +/// Size of the region is at least as large as the `SIZE` generic parameter.
> +#[repr(C)]
> +#[cfg_attr(CONFIG_64BIT, repr(align(8)))]
> +#[cfg_attr(not(CONFIG_64BIT), repr(align(4)))]

I've made this aligned to `usize` so the build-time alignment check can work in
patch 2 for all I/O sizes.

However Sashiko points out that MMIO base could be 4-byte aligned and not 8-byte
aligned, which is true as some simple drivers (e.g. GPIO) can often just ioremap
a very tiny 4-byte aligned region but isn't word-aligned.

So I'm going to make this unconditionally `repr(align(4))` in next version. This
does mean that if you're using `register!()` macro (or just old fashioned I/O on
untyped regions), using one of the build-time accessor methods would fail for
`u64`, as there is no way of knowing at compile time the MMIO region is 64-bit
aligned. Thus, `u64` can only be accessed via `try_` methods once that change is
made.

This doesn't seem to break Nova or Tyr, so I think it s good short-term
approach. If there're users that require 64-bit register access, then we might
need to create 64-bit aligned regions.

Best,
Gary

> +pub struct Region<const SIZE: usize = 0> {
> +    inner: [u8],
> +}
> +
> +impl<const SIZE: usize> Region<SIZE> {
> +    /// Create a raw mutable pointer from given base address and size.
> +    ///
> +    /// `size` should be at least as large as the minimum size `SIZE` to uphold the type invariant.
> +    ///
> +    /// Just like other methods on raw pointers, it is not unsafe to create a raw pointer
> +    /// that does not uphold the type invariants. However such pointers are not valid.
> +    #[inline]
> +    pub fn ptr_from_raw_parts_mut(base: *mut u8, size: usize) -> *mut Self {
> +        core::ptr::slice_from_raw_parts_mut(base, size) as *mut Region<SIZE>
> +    }
> +
> +    /// Create a raw mutable pointer from given base address and size.
> +    ///
> +    /// The alignment of `base` is checked, and `size` is checked against the minimum size specified
> +    /// via const generics.
> +    #[inline]
> +    pub fn ptr_try_from_raw_parts_mut(base: *mut u8, size: usize) -> Result<*mut Self> {
> +        if size < SIZE || base.align_offset(size_of::<usize>()) != 0 {
> +            return Err(EINVAL);
> +        }
> +
> +        Ok(Self::ptr_from_raw_parts_mut(base, size))
> +    }
> +}
> +
> +impl<const SIZE: usize> KnownSize for Region<SIZE> {
> +    const MIN_SIZE: usize = SIZE;
> +    const MIN_ALIGN: Alignment = Alignment::new::<{ size_of::<usize>() }>();
> +
> +    #[inline(always)]
> +    fn size(p: *const Self) -> usize {
> +        (p as *const [u8]).len()
> +    }
> +}
> +
>  /// Raw representation of an MMIO region.
>  ///
>  /// By itself, the existence of an instance of this structure does not provide any guarantees that
> @@ -85,7 +142,6 @@ pub fn maxsize(&self) -> usize {
>  ///     ffi::c_void,
>  ///     io::{
>  ///         Io,
> -///         IoKnownSize,
>  ///         Mmio,
>  ///         MmioRaw,
>  ///         PhysAddr,
> @@ -241,12 +297,25 @@ fn offset(self) -> usize {
>  /// For MMIO regions, all widths (u8, u16, u32, and u64 on 64-bit systems) are typically
>  /// supported. For PCI configuration space, u8, u16, and u32 are supported but u64 is not.