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 <[email protected]>
> ---
> 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.
