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