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

["Alexandre Courbot" <acourbot@nvidia.com>]

On Fri Jun 12, 2026 at 1:28 AM JST, 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 4-byte 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     | 130 +++++++++++++++++++++++++++++++++-----------------
>  rust/kernel/lib.rs    |   3 ++
>  rust/kernel/pci.rs    |   1 -
>  rust/kernel/pci/io.rs |  40 +++++++---------
>  rust/kernel/ptr.rs    |  12 +++++
>  6 files changed, 118 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..bef571dad6eb 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,58 @@
>  /// `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 4-byte aligned.
> +///
> +/// # Invariants
> +///
> +/// Size of the region is at least as large as the `SIZE` generic parameter.

I noticed that patch 13 adds the "size must be multiple of 4" invariant.
The doccomment for `ptr_from_raw_parts_mut` says that "size should be
4-bytes aligned" though, which sounds like the same to me. So should
that second invariant be introduced in this patch instead of patch 13?

> +#[repr(C, align(4))]
> +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`, and `base` and `size` should
> +    /// be 4-byte aligned to uphold the type invariant.

s/should/must? I guess we are running into all sort of issues if we
create regions which runtime size is smaller than the compile-time one,
and this is an invariant of `Region` itself.

Maybe this method should even be made `unsafe` for this reason? The
caller will need to write a `SAFETY` comment before dereferencing the
pointer, but IIUC this comment is bound to cover the pointer invariants,
not necessarily those of `Region`. Making the method `unsafe` would
force the user to cover them here.

> +    ///
> +    /// 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(4) != 0 || !size.is_multiple_of(4) {
> +            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::<4>();
> +
> +    #[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 +141,6 @@ pub fn maxsize(&self) -> usize {
>  ///     ffi::c_void,
>  ///     io::{
>  ///         Io,
> -///         IoKnownSize,
>  ///         Mmio,
>  ///         MmioRaw,
>  ///         PhysAddr,
> @@ -241,12 +296,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.
>  pub trait Io {
> +    /// Type of this I/O region. For untyped regions, [`Region`] can be used.
> +    type Target: ?Sized + KnownSize;
> +
>      /// Returns the base address of this mapping.
>      fn addr(&self) -> usize;
>  
>      /// Returns the maximum size of this mapping.
>      fn maxsize(&self) -> usize;
>  
> +    /// Returns the absolute I/O address for a given `offset`,
> +    /// performing compile-time bound checks.

nit: this doccomment could be a one liner.