* [PATCH v4 7/7] rust: io: mem: return DevresLt from IoMem/ExclusiveIoMem::into_devres()
From: Danilo Krummrich @ 2026-06-26 18:36 UTC (permalink / raw)
To: gregkh, rafael, dakr, ojeda, boqun, gary, bjorn3_gh, lossin,
a.hindborg, aliceryhl, tmgross, acourbot, ecourtney, m.wilczynski,
david.m.ertman, ira.weiny, leon, daniel.almeida, bhelgaas,
kwilczynski
Cc: driver-core, linux-kernel, nova-gpu, dri-devel, linux-pwm,
rust-for-linux
In-Reply-To: <20260626183630.2585057-1-dakr@kernel.org>
Implement ForLt and CovariantForLt for IoMem<'static, SIZE> and
ExclusiveIoMem<'static, SIZE> so that DevresLt can shorten the stored
'static lifetime back to the caller's borrow lifetime.
CovariantForLt is sound because both types only hold &'a Device<Bound>,
which is covariant over 'a.
Since DevresLt::new() handles the lifetime transmutation internally,
into_devres() no longer needs an explicit transmute to 'static.
Add DevresIoMem<SIZE> and DevresExclusiveIoMem<SIZE> type aliases.
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
drivers/pwm/pwm_th1520.rs | 5 ++-
rust/kernel/io/mem.rs | 65 +++++++++++++++++++++++++++------------
2 files changed, 47 insertions(+), 23 deletions(-)
diff --git a/drivers/pwm/pwm_th1520.rs b/drivers/pwm/pwm_th1520.rs
index 3e3fa51ccef9..7102c60fd14b 100644
--- a/drivers/pwm/pwm_th1520.rs
+++ b/drivers/pwm/pwm_th1520.rs
@@ -24,9 +24,8 @@
use kernel::{
clk::Clk,
device::{Bound, Core, Device},
- devres,
io::{
- mem::IoMem,
+ mem::DevresIoMem,
Io, //
},
of, platform,
@@ -86,7 +85,7 @@ struct Th1520WfHw {
#[pin_data(PinnedDrop)]
struct Th1520PwmDriverData {
#[pin]
- iomem: devres::Devres<IoMem<'static, TH1520_PWM_REG_SIZE>>,
+ iomem: DevresIoMem<TH1520_PWM_REG_SIZE>,
clk: Clk,
}
diff --git a/rust/kernel/io/mem.rs b/rust/kernel/io/mem.rs
index fc2a3e24f8d5..4691a01a3cf7 100644
--- a/rust/kernel/io/mem.rs
+++ b/rust/kernel/io/mem.rs
@@ -9,7 +9,7 @@
Bound,
Device, //
},
- devres::Devres,
+ devres::DevresLt,
io::{
self,
resource::{
@@ -20,6 +20,10 @@
MmioRaw, //
},
prelude::*,
+ types::{
+ CovariantForLt,
+ ForLt, //
+ },
};
/// An IO request for a specific device and resource.
@@ -172,6 +176,19 @@ pub struct ExclusiveIoMem<'a, const SIZE: usize> {
_region: Region,
}
+impl<const SIZE: usize> ForLt for ExclusiveIoMem<'static, SIZE> {
+ type Of<'a> = ExclusiveIoMem<'a, SIZE>;
+}
+
+// SAFETY: `ExclusiveIoMem<'a, SIZE>` is covariant over `'a`; it holds an `IoMem<'a, SIZE>`,
+// which holds `&'a Device<Bound>`, which is covariant.
+unsafe impl<const SIZE: usize> CovariantForLt for ExclusiveIoMem<'static, SIZE> {}
+
+/// A device-managed exclusive I/O memory region.
+///
+/// See [`ExclusiveIoMem::into_devres`].
+pub type DevresExclusiveIoMem<const SIZE: usize> = DevresLt<ExclusiveIoMem<'static, SIZE>>;
+
impl<'a, const SIZE: usize> ExclusiveIoMem<'a, SIZE> {
/// Creates a new `ExclusiveIoMem` instance.
fn ioremap(dev: &'a Device<Bound>, resource: &Resource) -> Result<Self> {
@@ -198,15 +215,13 @@ fn ioremap(dev: &'a Device<Bound>, resource: &Resource) -> Result<Self> {
/// Consume the `ExclusiveIoMem` and register it as a device-managed resource.
///
- /// The returned `Devres<ExclusiveIoMem<'static, SIZE>>` can outlive the original lifetime
- /// `'a`. Access to the I/O memory is revoked when the device is unbound.
- pub fn into_devres(self) -> Result<Devres<ExclusiveIoMem<'static, SIZE>>> {
- // SAFETY: Casting to `'static` is sound because `Devres` guarantees the
- // `ExclusiveIoMem` does not actually outlive the device -- access is revoked and the
- // resource is released when the device is unbound.
- let iomem: ExclusiveIoMem<'static, SIZE> = unsafe { core::mem::transmute(self) };
- let dev = iomem.iomem.dev;
- Devres::new(dev, iomem)
+ /// The returned [`DevresExclusiveIoMem`] can outlive the original borrow and be stored in
+ /// driver data. Access to the I/O memory is revoked automatically when the device is unbound.
+ pub fn into_devres(self) -> Result<DevresExclusiveIoMem<SIZE>> {
+ let dev = self.iomem.dev;
+ // SAFETY: `ExclusiveIoMem` only holds a device reference and an I/O mapping, both of
+ // which remain valid for the device's full bound scope, not just for `'a`.
+ unsafe { DevresLt::new(dev, self) }
}
}
@@ -232,6 +247,19 @@ pub struct IoMem<'a, const SIZE: usize = 0> {
io: MmioRaw<SIZE>,
}
+impl<const SIZE: usize> ForLt for IoMem<'static, SIZE> {
+ type Of<'a> = IoMem<'a, SIZE>;
+}
+
+// SAFETY: `IoMem<'a, SIZE>` is covariant over `'a`; it holds `&'a Device<Bound>`,
+// which is covariant.
+unsafe impl<const SIZE: usize> CovariantForLt for IoMem<'static, SIZE> {}
+
+/// A device-managed I/O memory region.
+///
+/// See [`IoMem::into_devres`].
+pub type DevresIoMem<const SIZE: usize> = DevresLt<IoMem<'static, SIZE>>;
+
impl<'a, const SIZE: usize> IoMem<'a, SIZE> {
fn ioremap(dev: &'a Device<Bound>, resource: &Resource) -> Result<Self> {
// Note: Some ioremap() implementations use types that depend on the CPU
@@ -271,16 +299,13 @@ fn ioremap(dev: &'a Device<Bound>, resource: &Resource) -> Result<Self> {
/// Consume the `IoMem` and register it as a device-managed resource.
///
- /// The returned `Devres<IoMem<'static, SIZE>>` can outlive the original
- /// lifetime `'a`. Access to the I/O memory is revoked when the device
- /// is unbound.
- pub fn into_devres(self) -> Result<Devres<IoMem<'static, SIZE>>> {
- // SAFETY: Casting to `'static` is sound because `Devres` guarantees the `IoMem` does not
- // actually outlive the device -- access is revoked and the resource is released when the
- // device is unbound.
- let iomem: IoMem<'static, SIZE> = unsafe { core::mem::transmute(self) };
- let dev = iomem.dev;
- Devres::new(dev, iomem)
+ /// The returned [`DevresIoMem`] can outlive the original borrow and be stored in driver data.
+ /// Access to the I/O memory is revoked automatically when the device is unbound.
+ pub fn into_devres(self) -> Result<DevresIoMem<SIZE>> {
+ let dev = self.dev;
+ // SAFETY: `IoMem` only holds a device reference and an I/O mapping, both of which
+ // remain valid for the device's full bound scope, not just for `'a`.
+ unsafe { DevresLt::new(dev, self) }
}
}
--
2.54.0
^ permalink raw reply related
* [PATCH v4 6/7] rust: pci: return DevresLt from Bar::into_devres()
From: Danilo Krummrich @ 2026-06-26 18:36 UTC (permalink / raw)
To: gregkh, rafael, dakr, ojeda, boqun, gary, bjorn3_gh, lossin,
a.hindborg, aliceryhl, tmgross, acourbot, ecourtney, m.wilczynski,
david.m.ertman, ira.weiny, leon, daniel.almeida, bhelgaas,
kwilczynski
Cc: driver-core, linux-kernel, nova-gpu, dri-devel, linux-pwm,
rust-for-linux
In-Reply-To: <20260626183630.2585057-1-dakr@kernel.org>
Implement ForLt and CovariantForLt for Bar<'static, SIZE> so that
DevresLt can shorten the stored 'static lifetime back to the caller's
borrow lifetime.
CovariantForLt is sound because Bar<'a, SIZE> only holds &'a
Device<Bound>, which is covariant over 'a.
Since DevresLt::new() handles the lifetime transmutation internally,
into_devres() no longer needs an explicit transmute to Bar<'static>.
Add a DevresBar<SIZE> type alias for convenience.
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
rust/kernel/pci.rs | 1 +
rust/kernel/pci/io.rs | 37 ++++++++++++++++++++++++++-----------
2 files changed, 27 insertions(+), 11 deletions(-)
diff --git a/rust/kernel/pci.rs b/rust/kernel/pci.rs
index 5071cae6543f..f783b9d9fa26 100644
--- a/rust/kernel/pci.rs
+++ b/rust/kernel/pci.rs
@@ -45,6 +45,7 @@
ConfigSpace,
ConfigSpaceKind,
ConfigSpaceSize,
+ DevresBar,
Extended,
Normal, //
};
diff --git a/rust/kernel/pci/io.rs b/rust/kernel/pci/io.rs
index 0461e01aaa20..7a0d2d74129d 100644
--- a/rust/kernel/pci/io.rs
+++ b/rust/kernel/pci/io.rs
@@ -6,7 +6,7 @@
use crate::{
bindings,
device,
- devres::Devres,
+ devres::DevresLt,
io::{
Io,
IoCapable,
@@ -14,7 +14,11 @@
Mmio,
MmioRaw, //
},
- prelude::*, //
+ prelude::*,
+ types::{
+ CovariantForLt,
+ ForLt, //
+ }, //
};
use core::{
marker::PhantomData,
@@ -151,6 +155,19 @@ pub struct Bar<'a, const SIZE: usize = 0> {
num: i32,
}
+impl<const SIZE: usize> ForLt for Bar<'static, SIZE> {
+ type Of<'a> = Bar<'a, SIZE>;
+}
+
+// SAFETY: `Bar<'a, SIZE>` is covariant over `'a`; it holds `&'a Device<Bound>`,
+// which is covariant.
+unsafe impl<const SIZE: usize> CovariantForLt for Bar<'static, SIZE> {}
+
+/// A device-managed PCI BAR mapping.
+///
+/// See [`Bar::into_devres`].
+pub type DevresBar<const SIZE: usize> = DevresLt<Bar<'static, SIZE>>;
+
impl<'a, const SIZE: usize> Bar<'a, SIZE> {
pub(super) fn new(
pdev: &'a Device<device::Bound>,
@@ -223,15 +240,13 @@ fn release(&self) {
/// Consume the `Bar` and register it as a device-managed resource.
///
- /// The returned `Devres<Bar<'static, SIZE>>` can outlive the original lifetime `'a`. Access
- /// to the BAR is revoked when the device is unbound.
- pub fn into_devres(self) -> Result<Devres<Bar<'static, SIZE>>> {
- // SAFETY: Casting to `'static` is sound because `Devres` guarantees the `Bar` does not
- // actually outlive the device -- access is revoked and the resource is released when the
- // device is unbound.
- let bar: Bar<'static, SIZE> = unsafe { core::mem::transmute(self) };
- let pdev = bar.pdev;
- Devres::new(pdev.as_ref(), bar)
+ /// The returned [`DevresBar`] can outlive the original borrow and be stored in driver data.
+ /// Access to the BAR is revoked automatically when the device is unbound.
+ pub fn into_devres(self) -> Result<DevresBar<SIZE>> {
+ let pdev = self.pdev;
+ // SAFETY: `Bar` only holds a reference to the device and an I/O mapping, both of which
+ // remain valid for the device's full bound scope, not just for `'a`.
+ unsafe { DevresLt::new(pdev.as_ref(), self) }
}
}
--
2.54.0
^ permalink raw reply related
* [PATCH v4 5/7] rust: devres: add DevresLt for ForLt-aware device resource access
From: Danilo Krummrich @ 2026-06-26 18:36 UTC (permalink / raw)
To: gregkh, rafael, dakr, ojeda, boqun, gary, bjorn3_gh, lossin,
a.hindborg, aliceryhl, tmgross, acourbot, ecourtney, m.wilczynski,
david.m.ertman, ira.weiny, leon, daniel.almeida, bhelgaas,
kwilczynski
Cc: driver-core, linux-kernel, nova-gpu, dri-devel, linux-pwm,
rust-for-linux
In-Reply-To: <20260626183630.2585057-1-dakr@kernel.org>
Devres<T> stores resources as T and returns &'a T from access(). For
lifetime-parameterized types like Bar<'a, SIZE> that are transmuted to
'static for storage, this exposes the synthetic 'static lifetime to
callers -- any method on the stored type that returns a reference with
its lifetime parameter would yield a &'static reference, which is
unsound.
Add DevresLt<F: ForLt>, a thin wrapper around Devres<F::Of<'static>>
that shortens the stored 'static lifetime to the caller's borrow
lifetime in all access methods.
DevresLt::new() is unsafe because the caller must guarantee that the
data remains valid for the device's full bound scope; the internal
transmute from F::Of<'a> to F::Of<'static> would otherwise allow
use-after-free.
Two access patterns are provided:
- CovariantForLt types get direct-reference accessors (access,
try_access) that return shortened references via
CovariantForLt::cast_ref.
- Plain ForLt types use closure-based accessors (access_with,
try_access_with) whose universally quantified lifetime prevents
callers from smuggling in concrete short-lived references.
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
rust/kernel/devres.rs | 106 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 106 insertions(+)
diff --git a/rust/kernel/devres.rs b/rust/kernel/devres.rs
index 11ce500e9b76..b7c075a39ba4 100644
--- a/rust/kernel/devres.rs
+++ b/rust/kernel/devres.rs
@@ -24,6 +24,8 @@
Arc, //
},
types::{
+ CovariantForLt,
+ ForLt,
ForeignOwnable,
Opaque, //
},
@@ -365,6 +367,110 @@ fn drop(&mut self) {
}
}
+/// Guard returned by [`DevresLt::try_access`].
+///
+/// Dereferences to `F::Of<'a>`, shortening the lifetime of the stored data to the guard's borrow
+/// lifetime.
+pub struct DevresGuard<'a, F: CovariantForLt>(RevocableGuard<'a, F::Of<'static>>);
+
+impl<'a, F: CovariantForLt> core::ops::Deref for DevresGuard<'a, F> {
+ type Target = F::Of<'a>;
+
+ #[inline]
+ fn deref(&self) -> &Self::Target {
+ F::cast_ref(&*self.0)
+ }
+}
+
+/// Device-managed resource with [`ForLt`](trait@ForLt)-aware access.
+///
+/// `DevresLt` wraps [`Devres`] and shortens the stored `'static` lifetime to the caller's borrow
+/// lifetime in all access methods.
+///
+/// Types that implement [`trait@CovariantForLt`] get direct-reference accessors ([`Self::access`],
+/// [`Self::try_access`]). Plain [`ForLt`](trait@ForLt) types use closure-based accessors
+/// ([`Self::access_with`], [`Self::try_access_with`]).
+pub struct DevresLt<F: ForLt>(Devres<F::Of<'static>>)
+where
+ for<'a> F::Of<'a>: Send;
+
+impl<F: ForLt> DevresLt<F>
+where
+ for<'a> F::Of<'a>: Send,
+{
+ /// Creates a new [`DevresLt`] instance of the given `data`.
+ ///
+ /// # Safety
+ ///
+ /// The data must remain valid for the device's full bound scope. [`DevresLt`] allows
+ /// access until the device is unbound, which may outlast `'a`.
+ pub unsafe fn new<'a, E>(
+ dev: &'a Device<Bound>,
+ data: impl PinInit<F::Of<'a>, E>,
+ ) -> Result<Self>
+ where
+ Error: From<E>,
+ {
+ // SAFETY: The caller guarantees the data is valid for the device's full bound scope.
+ // Lifetimes do not affect layout, so F::Of<'a> and F::Of<'static> have identical
+ // representation; casting the slot pointer is sound.
+ let data = unsafe {
+ pin_init::pin_init_from_closure::<F::Of<'static>, E>(move |slot| {
+ data.__pinned_init(slot.cast())
+ })
+ };
+
+ Ok(Self(Devres::new(dev, data)?))
+ }
+
+ /// Return a reference of the [`Device`] this [`DevresLt`] instance has been created with.
+ #[inline]
+ pub fn device(&self) -> &Device {
+ self.0.device()
+ }
+
+ /// Obtain `&F::Of<'_>`, bypassing the [`Revocable`], through a closure.
+ ///
+ /// This method works like [`DevresLt::access`](DevresLt::access) but accepts any
+ /// [`trait@ForLt`] type, not just [`trait@CovariantForLt`].
+ #[inline]
+ pub fn access_with<R, G>(&self, dev: &Device<Bound>, f: G) -> Result<R>
+ where
+ G: for<'a> FnOnce(&F::Of<'a>) -> R,
+ {
+ self.0.access(dev).map(f)
+ }
+
+ /// [`DevresLt`] accessor for [`Revocable::try_access_with`].
+ #[inline]
+ pub fn try_access_with<R, G>(&self, f: G) -> Option<R>
+ where
+ G: for<'a> FnOnce(&F::Of<'a>) -> R,
+ {
+ self.0.data().try_access_with(f)
+ }
+}
+
+impl<F: CovariantForLt> DevresLt<F>
+where
+ for<'a> F::Of<'a>: Send,
+{
+ /// Obtain `&'a F::Of<'a>`, bypassing the [`Revocable`].
+ ///
+ /// This method works like [`Devres::access`], but shortens the returned reference's lifetime
+ /// from `'static` to `'a` via [`CovariantForLt::cast_ref`].
+ #[inline]
+ pub fn access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a F::Of<'a>> {
+ self.0.access(dev).map(F::cast_ref)
+ }
+
+ /// [`DevresLt`] accessor for [`Revocable::try_access`].
+ #[inline]
+ pub fn try_access(&self) -> Option<DevresGuard<'_, F>> {
+ self.0.data().try_access().map(DevresGuard)
+ }
+}
+
/// Consume `data` and [`Drop::drop`] `data` once `dev` is unbound.
fn register_foreign<P>(dev: &Device<Bound>, data: P) -> Result
where
--
2.54.0
^ permalink raw reply related
* [PATCH v4 4/7] rust: auxiliary: sample: demonstrate ForLt with invariant Mutex type
From: Danilo Krummrich @ 2026-06-26 18:36 UTC (permalink / raw)
To: gregkh, rafael, dakr, ojeda, boqun, gary, bjorn3_gh, lossin,
a.hindborg, aliceryhl, tmgross, acourbot, ecourtney, m.wilczynski,
david.m.ertman, ira.weiny, leon, daniel.almeida, bhelgaas,
kwilczynski
Cc: driver-core, linux-kernel, nova-gpu, dri-devel, linux-pwm,
rust-for-linux
In-Reply-To: <20260626183630.2585057-1-dakr@kernel.org>
Extend the auxiliary driver sample to demonstrate both access patterns:
- registration_data() with CovariantForLt!(Data<'_>) for the covariant
data type that holds a plain &'bound reference.
- registration_data_with() with ForLt!(MutexData<'_>) for an invariant
data type that wraps a Mutex<&'bound Device>. Since Mutex<T> is
invariant over T, MutexData cannot implement CovariantForLt and must
use the closure-based accessor.
Reviewed-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
samples/rust/rust_driver_auxiliary.rs | 94 +++++++++++++++++++--------
1 file changed, 68 insertions(+), 26 deletions(-)
diff --git a/samples/rust/rust_driver_auxiliary.rs b/samples/rust/rust_driver_auxiliary.rs
index 92ee6a6d348e..e441ae81fa2c 100644
--- a/samples/rust/rust_driver_auxiliary.rs
+++ b/samples/rust/rust_driver_auxiliary.rs
@@ -11,14 +11,21 @@
Core, //
},
driver,
+ new_mutex,
pci,
prelude::*,
- types::CovariantForLt,
+ sync::Mutex,
+ types::{
+ CovariantForLt,
+ ForLt, //
+ },
InPlaceModule, //
};
const MODULE_NAME: &CStr = <LocalModule as kernel::ModuleMetadata>::NAME;
const AUXILIARY_NAME: &CStr = c"auxiliary";
+const COVARIANT_DEV_ID: u32 = 0;
+const INVARIANT_DEV_ID: u32 = 1;
struct AuxiliaryDriver;
@@ -56,12 +63,26 @@ struct Data<'bound> {
parent: &'bound pci::Device<Bound>,
}
+/// Registration data with interior mutability.
+///
+/// `Mutex<&'bound T>` is invariant over `'bound`, so this type cannot implement
+/// [`CovariantForLt`](trait@CovariantForLt). Access must go through the closure-based
+/// [`auxiliary::Device::registration_data_with()`].
+#[pin_data]
+struct MutexData<'bound> {
+ #[pin]
+ parent: Mutex<&'bound pci::Device<Bound>>,
+ index: u32,
+}
+
struct ParentDriver;
#[allow(clippy::type_complexity)]
+#[pin_data]
struct ParentData<'bound> {
_reg0: auxiliary::Registration<'bound, CovariantForLt!(Data<'_>)>,
- _reg1: auxiliary::Registration<'bound, CovariantForLt!(Data<'_>)>,
+ #[pin]
+ _reg1: auxiliary::Registration<'bound, ForLt!(MutexData<'_>)>,
}
kernel::pci_device_table!(
@@ -81,17 +102,17 @@ fn probe<'bound>(
pdev: &'bound pci::Device<Core<'_>>,
_info: &'bound Self::IdInfo,
) -> impl PinInit<Self::Data<'bound>, Error> + 'bound {
- Ok(ParentData {
+ try_pin_init!(ParentData {
// SAFETY: `ParentData` is the driver's private data, which is dropped when the
// device is unbound; i.e. `mem::forget()` is never called on it.
_reg0: unsafe {
auxiliary::Registration::new_with_lt(
pdev.as_ref(),
AUXILIARY_NAME,
- 0,
+ COVARIANT_DEV_ID,
MODULE_NAME,
Data {
- index: 0,
+ index: COVARIANT_DEV_ID,
parent: pdev,
},
)?
@@ -101,12 +122,16 @@ fn probe<'bound>(
auxiliary::Registration::new_with_lt(
pdev.as_ref(),
AUXILIARY_NAME,
- 1,
+ INVARIANT_DEV_ID,
MODULE_NAME,
- Data {
- index: 1,
- parent: pdev,
- },
+ pin_init!(MutexData {
+ parent <- {
+ let pdev: &pci::Device<Bound> = pdev;
+
+ new_mutex!(pdev)
+ },
+ index: INVARIANT_DEV_ID,
+ }),
)?
},
})
@@ -115,22 +140,39 @@ fn probe<'bound>(
impl ParentDriver {
fn connect(adev: &auxiliary::Device<Bound>) -> Result {
- let data = adev.registration_data::<CovariantForLt!(Data<'_>)>()?;
- let pdev = data.parent;
-
- dev_info!(
- pdev,
- "Connect auxiliary {} with parent: VendorID={}, DeviceID={:#x}\n",
- adev.id(),
- pdev.vendor_id(),
- pdev.device_id()
- );
-
- dev_info!(
- pdev,
- "Connected to auxiliary device with index {}.\n",
- data.index
- );
+ match adev.id() {
+ // CovariantForLt types can use the direct-reference accessor.
+ COVARIANT_DEV_ID => {
+ let data = adev.registration_data::<CovariantForLt!(Data<'_>)>()?;
+ let pdev = data.parent;
+
+ dev_info!(
+ pdev,
+ "Connect auxiliary {} with parent: VendorID={}, DeviceID={:#x}\n",
+ adev.id(),
+ pdev.vendor_id(),
+ pdev.device_id()
+ );
+
+ dev_info!(
+ pdev,
+ "Connected to auxiliary device with index {}.\n",
+ data.index
+ );
+ }
+ // Invariant ForLt types (e.g. containing a Mutex) require the closure-based accessor.
+ INVARIANT_DEV_ID => {
+ adev.registration_data_with::<ForLt!(MutexData<'_>), _>(|data| {
+ let pdev = *data.parent.lock();
+ dev_info!(
+ pdev,
+ "Connected to auxiliary device with index {} (via Mutex).\n",
+ data.index
+ );
+ })?;
+ }
+ _ => return Err(EINVAL),
+ }
Ok(())
}
--
2.54.0
^ permalink raw reply related
* [PATCH v4 3/7] rust: auxiliary: add registration_data_with() for ForLt types
From: Danilo Krummrich @ 2026-06-26 18:36 UTC (permalink / raw)
To: gregkh, rafael, dakr, ojeda, boqun, gary, bjorn3_gh, lossin,
a.hindborg, aliceryhl, tmgross, acourbot, ecourtney, m.wilczynski,
david.m.ertman, ira.weiny, leon, daniel.almeida, bhelgaas,
kwilczynski
Cc: driver-core, linux-kernel, nova-gpu, dri-devel, linux-pwm,
rust-for-linux
In-Reply-To: <20260626183630.2585057-1-dakr@kernel.org>
Add registration_data_with() taking a for<'a> closure that receives
Pin<&'a F::Of<'a>>, which works with any ForLt type. Taking a for<'a>
closure rather than returning a direct reference prevents callers from
choosing a concrete lifetime for the data, which is required for
soundness with non-covariant ForLt types.
Extract the common null-check, TypeId-check and KBox-borrow logic into a
private registration_data_pinned() helper shared by both
registration_data_with() and the existing registration_data().
Relax Registration's bound from CovariantForLt to ForLt so that
non-covariant types can be registered.
Reviewed-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
rust/kernel/auxiliary.rs | 93 +++++++++++++++++++++++++++++-----------
1 file changed, 67 insertions(+), 26 deletions(-)
diff --git a/rust/kernel/auxiliary.rs b/rust/kernel/auxiliary.rs
index 40a0af74a8e5..19a488700bb9 100644
--- a/rust/kernel/auxiliary.rs
+++ b/rust/kernel/auxiliary.rs
@@ -21,6 +21,7 @@
prelude::*,
types::{
CovariantForLt,
+ ForLt,
ForeignOwnable,
Opaque, //
},
@@ -270,18 +271,15 @@ pub fn parent(&self) -> &device::Device<device::Bound> {
unsafe { parent.as_bound() }
}
- /// Returns a pinned reference to the registration data set by the registering (parent) driver.
+ /// Returns the stored registration data as a pinned reference.
///
- /// `F` is the [`CovariantForLt`](trait@CovariantForLt) encoding of the data type. The returned
- /// reference has its lifetime shortened from `'static` to `&self`'s borrow lifetime via
- /// [`CovariantForLt::cast_ref`].
+ /// Performs null and [`TypeId`] checks, then borrows the stored [`KBox`].
///
- /// Returns [`EINVAL`] if `F` does not match the type used by the parent driver when calling
- /// [`Registration::new()`].
+ /// # Safety
///
- /// Returns [`ENOENT`] if no registration data has been set, e.g. when the device was
- /// registered by a C driver.
- pub fn registration_data<F: CovariantForLt + 'static>(&self) -> Result<Pin<&F::Of<'_>>> {
+ /// Callers must ensure that the lifetime shortening from the original `'static` storage to
+ /// `'_` is sound, e.g. via an HRTB closure or [`CovariantForLt`] guarantee.
+ unsafe fn registration_data_pinned<F: ForLt + 'static>(&self) -> Result<Pin<&F::Of<'_>>> {
// SAFETY: By the type invariant, `self.as_raw()` is a valid `struct auxiliary_device`.
let ptr = unsafe { (*self.as_raw()).registration_data_rust };
if ptr.is_null() {
@@ -300,17 +298,59 @@ pub fn registration_data<F: CovariantForLt + 'static>(&self) -> Result<Pin<&F::O
return Err(EINVAL);
}
- // SAFETY: The `TypeId` check above confirms that the stored type matches
- // `F::Of<'static>`; `ptr` remains valid until `Registration::drop()` calls
- // `from_foreign()`.
- let wrapper = unsafe { Pin::<KBox<RegistrationData<F::Of<'static>>>>::borrow(ptr) };
+ // SAFETY: The `TypeId` check above confirms that the stored type matches `F`'s
+ // encoding; lifetimes are erased at runtime, so borrowing as `F::Of<'_>` is
+ // layout-compatible with the stored `F::Of<'static>`. `ptr` remains valid until
+ // `Registration::drop()` calls `from_foreign()`.
+ let wrapper = unsafe { Pin::<KBox<RegistrationData<F::Of<'_>>>>::borrow(ptr) };
// SAFETY: `data` is a structurally pinned field of `RegistrationData`.
- let pinned: Pin<&F::Of<'_>> = unsafe { wrapper.map_unchecked(|w| &w.data) };
+ Ok(unsafe { wrapper.map_unchecked(|w| &w.data) })
+ }
- // SAFETY: The data was pinned when stored; `cast_ref` only shortens
- // the lifetime, so the pinning guarantee is preserved.
- Ok(unsafe { Pin::new_unchecked(F::cast_ref(pinned.get_ref())) })
+ /// Access the registration data set by the registering (parent) driver through a closure.
+ ///
+ /// `F` is the [`ForLt`](trait@ForLt) encoding of the data type. The closure receives a pinned
+ /// reference to the registration data.
+ ///
+ /// For covariant types that implement [`trait@CovariantForLt`], prefer
+ /// [`registration_data`](Self::registration_data) which returns a direct reference.
+ ///
+ /// Returns [`EINVAL`] if `F` does not match the type used by the parent driver when calling
+ /// [`Registration::new()`].
+ ///
+ /// Returns [`ENOENT`] if no registration data has been set, e.g. when the device was
+ /// registered by a C driver.
+ #[inline]
+ pub fn registration_data_with<F: ForLt + 'static, R>(
+ &self,
+ f: impl for<'a> FnOnce(Pin<&'a F::Of<'a>>) -> R,
+ ) -> Result<R> {
+ // SAFETY: The HRTB closure prevents the caller from smuggling in references with a
+ // concrete short lifetime, making the round-trip from `'static` sound regardless of
+ // variance.
+ let pinned = unsafe { self.registration_data_pinned::<F>()? };
+
+ Ok(f(pinned))
+ }
+
+ /// Returns a pinned reference to the registration data set by the registering (parent) driver.
+ ///
+ /// This method is only available when `F` implements [`trait@CovariantForLt`], which guarantees
+ /// that the lifetime shortening is sound.
+ ///
+ /// For non-covariant types, use the closure-based [`Self::registration_data_with`].
+ ///
+ /// Returns [`EINVAL`] if `F` does not match the type used by the parent driver when calling
+ /// [`Registration::new()`].
+ ///
+ /// Returns [`ENOENT`] if no registration data has been set, e.g. when the device was
+ /// registered by a C driver.
+ #[inline]
+ pub fn registration_data<F: CovariantForLt + 'static>(&self) -> Result<Pin<&F::Of<'_>>> {
+ // SAFETY: `CovariantForLt` guarantees covariance, which makes the lifetime shortening
+ // from `'static` to `'_` performed by `registration_data_pinned` sound.
+ unsafe { self.registration_data_pinned::<F>() }
}
}
@@ -399,22 +439,23 @@ struct RegistrationData<T> {
/// This type represents the registration of a [`struct auxiliary_device`]. When its parent device
/// is unbound, the corresponding auxiliary device will be unregistered from the system.
///
-/// The type parameter `F` is a [`CovariantForLt`](trait@CovariantForLt) encoding of the
-/// registration data type. For non-lifetime-parameterized types, use
-/// [`CovariantForLt!(T)`](macro@CovariantForLt).
-/// The data can be accessed by the auxiliary driver through [`Device::registration_data()`].
+/// The type parameter `F` is a [`ForLt`](trait@ForLt) encoding of the registration
+/// data type. For non-lifetime-parameterized types, use [`ForLt!(T)`](macro@ForLt).
+///
+/// The data can be accessed by the auxiliary driver through [`Device::registration_data()`] and
+/// [`Device::registration_data_with()`].
///
/// # Invariants
///
/// `self.adev` always holds a valid pointer to an initialized and registered
/// [`struct auxiliary_device`] whose `registration_data_rust` field points to a
/// valid `Pin<KBox<RegistrationData<F::Of<'static>>>>`.
-pub struct Registration<'a, F: CovariantForLt + 'static> {
+pub struct Registration<'a, F: ForLt + 'static> {
adev: NonNull<bindings::auxiliary_device>,
_phantom: PhantomData<F::Of<'a>>,
}
-impl<'a, F: CovariantForLt> Registration<'a, F>
+impl<'a, F: ForLt> Registration<'a, F>
where
for<'b> F::Of<'b>: Send + Sync,
{
@@ -526,7 +567,7 @@ pub fn new<E>(
}
}
-impl<F: CovariantForLt> Drop for Registration<'_, F> {
+impl<F: ForLt> Drop for Registration<'_, F> {
fn drop(&mut self) {
// SAFETY: By the type invariant of `Self`, `self.adev.as_ptr()` is a valid registered
// `struct auxiliary_device`.
@@ -548,7 +589,7 @@ fn drop(&mut self) {
}
// SAFETY: A `Registration` of a `struct auxiliary_device` can be released from any thread.
-unsafe impl<F: CovariantForLt> Send for Registration<'_, F> where for<'a> F::Of<'a>: Send {}
+unsafe impl<F: ForLt> Send for Registration<'_, F> where for<'a> F::Of<'a>: Send {}
// SAFETY: `Registration` does not expose any methods or fields that need synchronization.
-unsafe impl<F: CovariantForLt> Sync for Registration<'_, F> where for<'a> F::Of<'a>: Send {}
+unsafe impl<F: ForLt> Sync for Registration<'_, F> where for<'a> F::Of<'a>: Send {}
--
2.54.0
^ permalink raw reply related
* [PATCH v4 2/7] rust: types: introduce ForLt base trait for CovariantForLt
From: Danilo Krummrich @ 2026-06-26 18:36 UTC (permalink / raw)
To: gregkh, rafael, dakr, ojeda, boqun, gary, bjorn3_gh, lossin,
a.hindborg, aliceryhl, tmgross, acourbot, ecourtney, m.wilczynski,
david.m.ertman, ira.weiny, leon, daniel.almeida, bhelgaas,
kwilczynski
Cc: driver-core, linux-kernel, nova-gpu, dri-devel, linux-pwm,
rust-for-linux
In-Reply-To: <20260626183630.2585057-1-dakr@kernel.org>
Add a new ForLt trait as a base for CovariantForLt:
- ForLt (non-unsafe): represents a type generic over a lifetime, with
no covariance guarantee.
- CovariantForLt (unsafe): becomes a subtrait of ForLt that
additionally proves the type is covariant over its lifetime
parameter, providing a safe cast_ref() method.
This split allows non-covariant types (e.g. types behind a Mutex) to
implement ForLt and participate in DevresLt / registration data patterns
that use HRTB closures for sound access, without requiring a covariance
proof that would fail to compile.
Both macros share the UnsafeForLtImpl helper type, distinguished by
a const generic N: ForLt! emits N = 0 (no covariance proof),
CovariantForLt! emits N = 1 (with compile-time covariance proof).
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
rust/kernel/types.rs | 1 +
rust/kernel/types/for_lt.rs | 72 +++++++++++++++++++++++++++++--------
rust/macros/for_lt.rs | 68 ++++++++++++++++++++++++-----------
rust/macros/lib.rs | 19 +++++++++-
4 files changed, 123 insertions(+), 37 deletions(-)
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index cbe6907042d3..c1ed05d1046c 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -14,6 +14,7 @@
#[doc(hidden)]
pub mod for_lt;
pub use for_lt::CovariantForLt;
+pub use for_lt::ForLt;
/// Used to transfer ownership to and from foreign (non-Rust) languages.
///
diff --git a/rust/kernel/types/for_lt.rs b/rust/kernel/types/for_lt.rs
index a11f7509633c..0b53494080b7 100644
--- a/rust/kernel/types/for_lt.rs
+++ b/rust/kernel/types/for_lt.rs
@@ -1,17 +1,59 @@
// SPDX-License-Identifier: Apache-2.0 OR MIT
-//! Provide implementation and test of the `CovariantForLt` trait and macro.
+//! Provide implementation and test of the `ForLt` and `CovariantForLt` traits and macros.
//!
-//! This module is hidden and user should just use `CovariantForLt!` directly.
+//! This module is hidden and users should just use `ForLt!` / `CovariantForLt!` directly.
use core::marker::PhantomData;
/// Representation of types generic over a lifetime.
///
-/// The type must be covariant over the generic lifetime, i.e. the lifetime parameter
-/// can be soundly shortened.
+/// # Macro
+///
+/// It is not recommended to implement this trait directly. `ForLt!` macro is provided to obtain a
+/// type that implements this trait.
///
-/// The lifetime involved must be covariant.
+/// The full syntax is
+///
+/// ```
+/// # use kernel::types::ForLt;
+/// # fn expect_lt<F: ForLt>() {}
+/// # struct TypeThatUse<'a>(&'a ());
+/// # expect_lt::<
+/// ForLt!(for<'a> TypeThatUse<'a>)
+/// # >();
+/// ```
+///
+/// which gives a type so that `<ForLt!(for<'a> TypeThatUse<'a>) as ForLt>::Of<'b>`
+/// is `TypeThatUse<'b>`.
+///
+/// You may also use a short-hand syntax which works similar to lifetime elision.
+/// The macro also accepts types that do not involve a lifetime at all.
+///
+/// ```
+/// # use kernel::types::ForLt;
+/// # fn expect_lt<F: ForLt>() {}
+/// # struct TypeThatUse<'a>(&'a ());
+/// # expect_lt::<
+/// ForLt!(TypeThatUse<'_>) // Equivalent to `ForLt!(for<'a> TypeThatUse<'a>)`.
+/// # >();
+/// # expect_lt::<
+/// ForLt!(&u32) // Equivalent to `ForLt!(for<'a> &'a u32)`.
+/// # >();
+/// # expect_lt::<
+/// ForLt!(u32) // Equivalent to `ForLt!(for<'a> u32)`.
+/// # >();
+/// ```
+pub trait ForLt {
+ /// The type parameterized by the lifetime.
+ type Of<'a>: 'a;
+}
+pub use macros::ForLt;
+
+/// [`trait@ForLt`] subtrait for types that are covariant over their lifetime parameter.
+///
+/// Provides a safe [`cast_ref`](CovariantForLt::cast_ref) method for types that are proven to be
+/// covariant. The `CovariantForLt!` macro syntax is the same as `ForLt!`.
///
/// # Macro
///
@@ -84,10 +126,7 @@
/// # Safety
///
/// `Self::Of<'a>` must be covariant over the lifetime `'a`.
-pub unsafe trait CovariantForLt {
- /// The type parameterized by the lifetime.
- type Of<'a>: 'a;
-
+pub unsafe trait CovariantForLt: ForLt {
/// Cast a reference to a shorter lifetime.
#[inline(always)]
fn cast_ref<'r, 'short: 'r, 'long: 'short>(long: &'r Self::Of<'long>) -> &'r Self::Of<'short> {
@@ -99,25 +138,28 @@ fn cast_ref<'r, 'short: 'r, 'long: 'short>(long: &'r Self::Of<'long>) -> &'r Sel
/// This is intended to be an "unsafe-to-refer-to" type.
///
-/// Must only be used by the `CovariantForLt!` macro.
+/// Must only be used by the `ForLt!` / `CovariantForLt!` macros.
///
/// `T` is the magic `dyn for<'a> WithLt<'a, TypeThatUse<'a>>` generated by macro.
///
/// `WF` is a type that the macro can use to assert some specific type is well-formed.
///
/// `N` is to provide the macro a place to emit arbitrary items, in case it needs to prove
-/// additional properties.
+/// additional properties. `ForLt!` emits `N = 0`; `CovariantForLt!` emits `N = 1` after a
+/// covariance proof.
#[doc(hidden)]
pub struct UnsafeForLtImpl<T: ?Sized, WF, const N: usize>(PhantomData<(WF, T)>);
-// This is a helper trait for implementation `CovariantForLt` to be able to use HRTB.
+// This is a helper trait for implementation of `ForLt` / `CovariantForLt` to be able to use HRTB.
#[doc(hidden)]
pub trait WithLt<'a> {
type Of: 'a;
}
-// SAFETY: In `CovariantForLt!` macro, a covariance proof is generated when naming
-// `UnsafeForLtImpl` and it will fail to evaluate if the type is not covariant.
-unsafe impl<T: ?Sized + for<'a> WithLt<'a>, WF> CovariantForLt for UnsafeForLtImpl<T, WF, 0> {
+impl<T: ?Sized + for<'a> WithLt<'a>, WF, const N: usize> ForLt for UnsafeForLtImpl<T, WF, N> {
type Of<'a> = <T as WithLt<'a>>::Of;
}
+
+// SAFETY: In `CovariantForLt!` macro, a covariance proof is generated in the `N` const generic
+// and it will fail to evaluate if the type is not covariant. Only `N = 1` gets this impl.
+unsafe impl<T: ?Sized + for<'a> WithLt<'a>, WF> CovariantForLt for UnsafeForLtImpl<T, WF, 1> {}
diff --git a/rust/macros/for_lt.rs b/rust/macros/for_lt.rs
index 9487a9352f1c..9270a069cd3a 100644
--- a/rust/macros/for_lt.rs
+++ b/rust/macros/for_lt.rs
@@ -176,8 +176,10 @@ fn prove(&mut self, ty: &'a Type) {
}
}
-pub(crate) fn covariant_for_lt(input: HigherRankedType) -> TokenStream {
- let (ty, lifetime) = match input {
+/// Resolve the higher-ranked type into a concrete `(ty, lifetime)` pair, expanding elided
+/// lifetimes as needed. Shared by both `for_lt` and `covariant_for_lt`.
+fn resolve_hrt(input: HigherRankedType) -> (Type, Lifetime) {
+ match input {
HigherRankedType::Explicit { lifetime, ty, .. } => (ty, lifetime),
HigherRankedType::Implicit { ty } => {
// If there's no explicit `for<'a>` binder, inject a synthetic `'__elided` lifetime
@@ -188,14 +190,33 @@ pub(crate) fn covariant_for_lt(input: HigherRankedType) -> TokenStream {
};
(ty.expand_elided_lifetime(&lifetime), lifetime)
}
- };
+ }
+}
+
+/// Produce the `'static`-substituted type for the WF check. Shared by both macros.
+fn ty_static(ty: &Type, lifetime: &Lifetime) -> Type {
+ ty.replace_lifetime(
+ lifetime,
+ &Lifetime {
+ apostrophe: Span::mixed_site(),
+ ident: format_ident!("static"),
+ },
+ )
+}
+
+/// Shared implementation for both `ForLt!` and `CovariantForLt!`.
+///
+/// Both macros run the prover and emit `ProveWf` structs to check well-formedness for all lifetime
+/// instances (workaround for <https://github.com/rust-lang/rust/issues/152489>). `CovariantForLt!`
+/// additionally emits covariance proof functions and sets `N = 1`.
+fn for_lt_inner(input: HigherRankedType, prove_covariance: bool) -> TokenStream {
+ let (ty, lifetime) = resolve_hrt(input);
let mut prover = Prover(&lifetime, Vec::new());
prover.prove(&ty);
let mut proof = Vec::new();
- // Emit proofs for every type that requires additional compiler help in proving covariance.
for (idx, required_proof) in prover.1.into_iter().enumerate() {
// Insert a proof that the type is well-formed.
//
@@ -210,15 +231,16 @@ struct #wf_proof_name<#lifetime>(
);
));
- // Insert a proof that the type is covariant.
- let cov_proof_name = format_ident!("prove_covariant_{idx}");
- proof.push(quote!(
- fn #cov_proof_name<'__short, '__long: '__short>(
- long: #wf_proof_name<'__long>
- ) -> #wf_proof_name<'__short> {
- long
- }
- ));
+ if prove_covariance {
+ let cov_proof_name = format_ident!("prove_covariant_{idx}");
+ proof.push(quote!(
+ fn #cov_proof_name<'__short, '__long: '__short>(
+ long: #wf_proof_name<'__long>
+ ) -> #wf_proof_name<'__short> {
+ long
+ }
+ ));
+ }
}
// Make sure that the type is wellformed when substituting lifetime with `'static`.
@@ -226,13 +248,9 @@ fn #cov_proof_name<'__short, '__long: '__short>(
// Currently the Rust compiler doesn't check this, see the above `ProveWf` documentation.
//
// We prefer to use this way of proving WF-ness as it can work when generics are involved.
- let ty_static = ty.replace_lifetime(
- &lifetime,
- &Lifetime {
- apostrophe: Span::mixed_site(),
- ident: format_ident!("static"),
- },
- );
+ let ty_static = ty_static(&ty, &lifetime);
+
+ let n: usize = prove_covariance.into();
quote!(
::kernel::types::for_lt::UnsafeForLtImpl::<
@@ -241,8 +259,16 @@ fn #cov_proof_name<'__short, '__long: '__short>(
{
#(#proof)*
- 0
+ #n
}
>
)
}
+
+pub(crate) fn for_lt(input: HigherRankedType) -> TokenStream {
+ for_lt_inner(input, false)
+}
+
+pub(crate) fn covariant_for_lt(input: HigherRankedType) -> TokenStream {
+ for_lt_inner(input, true)
+}
diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
index 2167cb270928..e970769609f3 100644
--- a/rust/macros/lib.rs
+++ b/rust/macros/lib.rs
@@ -491,11 +491,28 @@ pub fn kunit_tests(attr: TokenStream, input: TokenStream) -> TokenStream {
.into()
}
-/// Obtain a type that implements [`CovariantForLt`] for the given higher-ranked type.
+/// Obtain a type that implements [`ForLt`] for the given higher-ranked type.
+///
+/// Please refer to the documentation of the [`ForLt`] trait.
+///
+/// [`ForLt`]: trait.ForLt.html
+#[proc_macro]
+#[allow(non_snake_case)]
+pub fn ForLt(input: TokenStream) -> TokenStream {
+ for_lt::for_lt(parse_macro_input!(input)).into()
+}
+
+/// Obtain a type that implements [`CovariantForLt`] (and [`ForLt`]) for the given higher-ranked
+/// type.
+///
+/// Unlike [`ForLt!`], this macro additionally proves that the type is covariant over the lifetime,
+/// providing a safe [`CovariantForLt::cast_ref`] method.
///
/// Please refer to the documentation of the [`CovariantForLt`] trait.
///
/// [`CovariantForLt`]: trait.CovariantForLt.html
+/// [`CovariantForLt::cast_ref`]: trait.CovariantForLt.html#method.cast_ref
+/// [`ForLt`]: trait.ForLt.html
#[proc_macro]
#[allow(non_snake_case)]
pub fn CovariantForLt(input: TokenStream) -> TokenStream {
--
2.54.0
^ permalink raw reply related
* [PATCH v4 1/7] rust: types: rename ForLt to CovariantForLt
From: Danilo Krummrich @ 2026-06-26 18:36 UTC (permalink / raw)
To: gregkh, rafael, dakr, ojeda, boqun, gary, bjorn3_gh, lossin,
a.hindborg, aliceryhl, tmgross, acourbot, ecourtney, m.wilczynski,
david.m.ertman, ira.weiny, leon, daniel.almeida, bhelgaas,
kwilczynski
Cc: driver-core, linux-kernel, nova-gpu, dri-devel, linux-pwm,
rust-for-linux
In-Reply-To: <20260626183630.2585057-1-dakr@kernel.org>
Rename ForLt to CovariantForLt to prepare for the introduction of a new
ForLt base trait that does not require covariance.
The existing ForLt trait requires covariance, which enables the safe
cast_ref() method. This rename preserves the same semantics under a more
precise name, making room for a weaker ForLt trait in a subsequent
commit.
No functional change.
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Reviewed-by: Gary Guo <gary@garyguo.net>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
drivers/gpu/nova-core/driver.rs | 4 +-
rust/kernel/auxiliary.rs | 23 +++++------
rust/kernel/types.rs | 2 +-
rust/kernel/types/for_lt.rs | 57 ++++++++++++++-------------
rust/macros/for_lt.rs | 6 +--
rust/macros/lib.rs | 11 +++---
samples/rust/rust_driver_auxiliary.rs | 8 ++--
7 files changed, 56 insertions(+), 55 deletions(-)
diff --git a/drivers/gpu/nova-core/driver.rs b/drivers/gpu/nova-core/driver.rs
index 5738d4ac521b..48380ac15f68 100644
--- a/drivers/gpu/nova-core/driver.rs
+++ b/drivers/gpu/nova-core/driver.rs
@@ -15,7 +15,7 @@
Atomic,
Relaxed, //
},
- types::ForLt,
+ types::CovariantForLt,
};
use crate::gpu::Gpu;
@@ -29,7 +29,7 @@ pub(crate) struct NovaCore<'bound> {
pub(crate) gpu: Gpu<'bound>,
bar: pci::Bar<'bound, BAR0_SIZE>,
#[allow(clippy::type_complexity)]
- _reg: auxiliary::Registration<'bound, ForLt!(())>,
+ _reg: auxiliary::Registration<'bound, CovariantForLt!(())>,
}
pub(crate) struct NovaCoreDriver;
diff --git a/rust/kernel/auxiliary.rs b/rust/kernel/auxiliary.rs
index c42928d5a239..40a0af74a8e5 100644
--- a/rust/kernel/auxiliary.rs
+++ b/rust/kernel/auxiliary.rs
@@ -20,7 +20,7 @@
},
prelude::*,
types::{
- ForLt,
+ CovariantForLt,
ForeignOwnable,
Opaque, //
},
@@ -272,16 +272,16 @@ pub fn parent(&self) -> &device::Device<device::Bound> {
/// Returns a pinned reference to the registration data set by the registering (parent) driver.
///
- /// `F` is the [`ForLt`](trait@ForLt) encoding of the data type. The returned
+ /// `F` is the [`CovariantForLt`](trait@CovariantForLt) encoding of the data type. The returned
/// reference has its lifetime shortened from `'static` to `&self`'s borrow lifetime via
- /// [`ForLt::cast_ref`].
+ /// [`CovariantForLt::cast_ref`].
///
/// Returns [`EINVAL`] if `F` does not match the type used by the parent driver when calling
/// [`Registration::new()`].
///
/// Returns [`ENOENT`] if no registration data has been set, e.g. when the device was
/// registered by a C driver.
- pub fn registration_data<F: ForLt + 'static>(&self) -> Result<Pin<&F::Of<'_>>> {
+ pub fn registration_data<F: CovariantForLt + 'static>(&self) -> Result<Pin<&F::Of<'_>>> {
// SAFETY: By the type invariant, `self.as_raw()` is a valid `struct auxiliary_device`.
let ptr = unsafe { (*self.as_raw()).registration_data_rust };
if ptr.is_null() {
@@ -399,8 +399,9 @@ struct RegistrationData<T> {
/// This type represents the registration of a [`struct auxiliary_device`]. When its parent device
/// is unbound, the corresponding auxiliary device will be unregistered from the system.
///
-/// The type parameter `F` is a [`ForLt`](trait@ForLt) encoding of the registration
-/// data type. For non-lifetime-parameterized types, use [`ForLt!(T)`](macro@ForLt).
+/// The type parameter `F` is a [`CovariantForLt`](trait@CovariantForLt) encoding of the
+/// registration data type. For non-lifetime-parameterized types, use
+/// [`CovariantForLt!(T)`](macro@CovariantForLt).
/// The data can be accessed by the auxiliary driver through [`Device::registration_data()`].
///
/// # Invariants
@@ -408,12 +409,12 @@ struct RegistrationData<T> {
/// `self.adev` always holds a valid pointer to an initialized and registered
/// [`struct auxiliary_device`] whose `registration_data_rust` field points to a
/// valid `Pin<KBox<RegistrationData<F::Of<'static>>>>`.
-pub struct Registration<'a, F: ForLt + 'static> {
+pub struct Registration<'a, F: CovariantForLt + 'static> {
adev: NonNull<bindings::auxiliary_device>,
_phantom: PhantomData<F::Of<'a>>,
}
-impl<'a, F: ForLt> Registration<'a, F>
+impl<'a, F: CovariantForLt> Registration<'a, F>
where
for<'b> F::Of<'b>: Send + Sync,
{
@@ -525,7 +526,7 @@ pub fn new<E>(
}
}
-impl<F: ForLt> Drop for Registration<'_, F> {
+impl<F: CovariantForLt> Drop for Registration<'_, F> {
fn drop(&mut self) {
// SAFETY: By the type invariant of `Self`, `self.adev.as_ptr()` is a valid registered
// `struct auxiliary_device`.
@@ -547,7 +548,7 @@ fn drop(&mut self) {
}
// SAFETY: A `Registration` of a `struct auxiliary_device` can be released from any thread.
-unsafe impl<F: ForLt> Send for Registration<'_, F> where for<'a> F::Of<'a>: Send {}
+unsafe impl<F: CovariantForLt> Send for Registration<'_, F> where for<'a> F::Of<'a>: Send {}
// SAFETY: `Registration` does not expose any methods or fields that need synchronization.
-unsafe impl<F: ForLt> Sync for Registration<'_, F> where for<'a> F::Of<'a>: Send {}
+unsafe impl<F: CovariantForLt> Sync for Registration<'_, F> where for<'a> F::Of<'a>: Send {}
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index ac316fd7b538..cbe6907042d3 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -13,7 +13,7 @@
#[doc(hidden)]
pub mod for_lt;
-pub use for_lt::ForLt;
+pub use for_lt::CovariantForLt;
/// Used to transfer ownership to and from foreign (non-Rust) languages.
///
diff --git a/rust/kernel/types/for_lt.rs b/rust/kernel/types/for_lt.rs
index d44323c28e8d..a11f7509633c 100644
--- a/rust/kernel/types/for_lt.rs
+++ b/rust/kernel/types/for_lt.rs
@@ -1,8 +1,8 @@
// SPDX-License-Identifier: Apache-2.0 OR MIT
-//! Provide implementation and test of the `ForLt` trait and macro.
+//! Provide implementation and test of the `CovariantForLt` trait and macro.
//!
-//! This module is hidden and user should just use `ForLt!` directly.
+//! This module is hidden and user should just use `CovariantForLt!` directly.
use core::marker::PhantomData;
@@ -15,38 +15,39 @@
///
/// # Macro
///
-/// It is not recommended to implement this trait directly. `ForLt!` macro is provided to obtain a
-/// type that implements this trait.
+/// It is not recommended to implement this trait directly. `CovariantForLt!` macro is provided to
+/// obtain a type that implements this trait.
///
/// The full syntax is
///
/// ```
-/// # use kernel::types::ForLt;
-/// # fn expect_lt<F: ForLt>() {}
+/// # use kernel::types::CovariantForLt;
+/// # fn expect_lt<F: CovariantForLt>() {}
/// # struct TypeThatUse<'a>(&'a ());
/// # expect_lt::<
-/// ForLt!(for<'a> TypeThatUse<'a>)
+/// CovariantForLt!(for<'a> TypeThatUse<'a>)
/// # >();
/// ```
///
-/// which gives a type so that `<ForLt!(for<'a> TypeThatUse<'a>) as ForLt>::Of<'b>`
+/// which gives a type so that
+/// `<CovariantForLt!(for<'a> TypeThatUse<'a>) as CovariantForLt>::Of<'b>`
/// is `TypeThatUse<'b>`.
///
/// You may also use a short-hand syntax which works similar to lifetime elision.
/// The macro also accepts types that do not involve a lifetime at all.
///
/// ```
-/// # use kernel::types::ForLt;
-/// # fn expect_lt<F: ForLt>() {}
+/// # use kernel::types::CovariantForLt;
+/// # fn expect_lt<F: CovariantForLt>() {}
/// # struct TypeThatUse<'a>(&'a ());
/// # expect_lt::<
-/// ForLt!(TypeThatUse<'_>) // Equivalent to `ForLt!(for<'a> TypeThatUse<'a>)`.
+/// CovariantForLt!(TypeThatUse<'_>) // Equivalent to `CovariantForLt!(for<'a> TypeThatUse<'a>)`.
/// # >();
/// # expect_lt::<
-/// ForLt!(&u32) // Equivalent to `ForLt!(for<'a> &'a u32)`.
+/// CovariantForLt!(&u32) // Equivalent to `CovariantForLt!(for<'a> &'a u32)`.
/// # >();
/// # expect_lt::<
-/// ForLt!(u32) // Equivalent to `ForLt!(for<'a> u32)`.
+/// CovariantForLt!(u32) // Equivalent to `CovariantForLt!(for<'a> u32)`.
/// # >();
/// ```
///
@@ -55,10 +56,10 @@
/// it.
///
/// ```ignore,compile_fail
-/// # use kernel::types::ForLt;
-/// # fn expect_lt<F: ForLt>() {}
+/// # use kernel::types::CovariantForLt;
+/// # fn expect_lt<F: CovariantForLt>() {}
/// # expect_lt::<
-/// ForLt!(fn(&u32)) // Contravariant, will fail compilation.
+/// CovariantForLt!(fn(&u32)) // Contravariant, will fail compilation.
/// # >();
/// ```
///
@@ -67,23 +68,23 @@
/// the generic parameter but is in a separate item.
///
/// ```
-/// # use kernel::types::ForLt;
-/// fn expect_lt<F: ForLt>() {}
+/// # use kernel::types::CovariantForLt;
+/// fn expect_lt<F: CovariantForLt>() {}
/// # #[allow(clippy::unnecessary_safety_comment, reason = "false positive")]
/// fn generic_fn<T: 'static>() {
/// // Syntactically proven by the macro
-/// expect_lt::<ForLt!(&T)>();
+/// expect_lt::<CovariantForLt!(&T)>();
/// // Syntactically proven by the macro
-/// expect_lt::<ForLt!(&KBox<T>)>();
+/// expect_lt::<CovariantForLt!(&KBox<T>)>();
/// // Cannot be syntactically proven, need to check covariance of `KBox`
-/// // expect_lt::<ForLt!(&KBox<&T>)>();
+/// // expect_lt::<CovariantForLt!(&KBox<&T>)>();
/// }
/// ```
///
/// # Safety
///
/// `Self::Of<'a>` must be covariant over the lifetime `'a`.
-pub unsafe trait ForLt {
+pub unsafe trait CovariantForLt {
/// The type parameterized by the lifetime.
type Of<'a>: 'a;
@@ -94,11 +95,11 @@ fn cast_ref<'r, 'short: 'r, 'long: 'short>(long: &'r Self::Of<'long>) -> &'r Sel
unsafe { core::mem::transmute(long) }
}
}
-pub use macros::ForLt;
+pub use macros::CovariantForLt;
/// This is intended to be an "unsafe-to-refer-to" type.
///
-/// Must only be used by the `ForLt!` macro.
+/// Must only be used by the `CovariantForLt!` macro.
///
/// `T` is the magic `dyn for<'a> WithLt<'a, TypeThatUse<'a>>` generated by macro.
///
@@ -109,14 +110,14 @@ fn cast_ref<'r, 'short: 'r, 'long: 'short>(long: &'r Self::Of<'long>) -> &'r Sel
#[doc(hidden)]
pub struct UnsafeForLtImpl<T: ?Sized, WF, const N: usize>(PhantomData<(WF, T)>);
-// This is a helper trait for implementation `ForLt` to be able to use HRTB.
+// This is a helper trait for implementation `CovariantForLt` to be able to use HRTB.
#[doc(hidden)]
pub trait WithLt<'a> {
type Of: 'a;
}
-// SAFETY: In `ForLt!` macro, a covariance proof is generated when naming `UnsafeForLtImpl`
-// and it will fail to evaluate if the type is not covariant.
-unsafe impl<T: ?Sized + for<'a> WithLt<'a>, WF> ForLt for UnsafeForLtImpl<T, WF, 0> {
+// SAFETY: In `CovariantForLt!` macro, a covariance proof is generated when naming
+// `UnsafeForLtImpl` and it will fail to evaluate if the type is not covariant.
+unsafe impl<T: ?Sized + for<'a> WithLt<'a>, WF> CovariantForLt for UnsafeForLtImpl<T, WF, 0> {
type Of<'a> = <T as WithLt<'a>>::Of;
}
diff --git a/rust/macros/for_lt.rs b/rust/macros/for_lt.rs
index 364d4113cd10..9487a9352f1c 100644
--- a/rust/macros/for_lt.rs
+++ b/rust/macros/for_lt.rs
@@ -154,8 +154,8 @@ fn prove(&mut self, ty: &'a Type) {
// Note that if we encounter `&'other_lt T`, then we still need to make sure the type
// is wellformed if `T` involves `&'lt`, so we defer to the compiler.
//
- // This is to block cases like `ForLt!(for<'a> &'static &'a u32)`, as the presence of
- // the type implies `'a: 'static` but this is unsound.
+ // This is to block cases like `CovariantForLt!(for<'a> &'static &'a u32)`, as the
+ // presence of the type implies `'a: 'static` but this is unsound.
Type::Reference(ty)
if ty.mutability.is_none() && ty.lifetime.as_ref() == Some(self.0) =>
{
@@ -176,7 +176,7 @@ fn prove(&mut self, ty: &'a Type) {
}
}
-pub(crate) fn for_lt(input: HigherRankedType) -> TokenStream {
+pub(crate) fn covariant_for_lt(input: HigherRankedType) -> TokenStream {
let (ty, lifetime) = match input {
HigherRankedType::Explicit { lifetime, ty, .. } => (ty, lifetime),
HigherRankedType::Implicit { ty } => {
diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
index 4a48fabbc268..2167cb270928 100644
--- a/rust/macros/lib.rs
+++ b/rust/macros/lib.rs
@@ -491,14 +491,13 @@ pub fn kunit_tests(attr: TokenStream, input: TokenStream) -> TokenStream {
.into()
}
-/// Obtain a type that implements [`ForLt`] for the given higher-ranked type.
+/// Obtain a type that implements [`CovariantForLt`] for the given higher-ranked type.
///
-/// Please refer to the documentation of the [`ForLt`] trait.
+/// Please refer to the documentation of the [`CovariantForLt`] trait.
///
-/// [`ForLt`]: trait.ForLt.html
+/// [`CovariantForLt`]: trait.CovariantForLt.html
#[proc_macro]
-// The macro shares the name with the trait.
#[allow(non_snake_case)]
-pub fn ForLt(input: TokenStream) -> TokenStream {
- for_lt::for_lt(parse_macro_input!(input)).into()
+pub fn CovariantForLt(input: TokenStream) -> TokenStream {
+ for_lt::covariant_for_lt(parse_macro_input!(input)).into()
}
diff --git a/samples/rust/rust_driver_auxiliary.rs b/samples/rust/rust_driver_auxiliary.rs
index 2c1351040e45..92ee6a6d348e 100644
--- a/samples/rust/rust_driver_auxiliary.rs
+++ b/samples/rust/rust_driver_auxiliary.rs
@@ -13,7 +13,7 @@
driver,
pci,
prelude::*,
- types::ForLt,
+ types::CovariantForLt,
InPlaceModule, //
};
@@ -60,8 +60,8 @@ struct Data<'bound> {
#[allow(clippy::type_complexity)]
struct ParentData<'bound> {
- _reg0: auxiliary::Registration<'bound, ForLt!(Data<'_>)>,
- _reg1: auxiliary::Registration<'bound, ForLt!(Data<'_>)>,
+ _reg0: auxiliary::Registration<'bound, CovariantForLt!(Data<'_>)>,
+ _reg1: auxiliary::Registration<'bound, CovariantForLt!(Data<'_>)>,
}
kernel::pci_device_table!(
@@ -115,7 +115,7 @@ fn probe<'bound>(
impl ParentDriver {
fn connect(adev: &auxiliary::Device<Bound>) -> Result {
- let data = adev.registration_data::<ForLt!(Data<'_>)>()?;
+ let data = adev.registration_data::<CovariantForLt!(Data<'_>)>()?;
let pdev = data.parent;
dev_info!(
--
2.54.0
^ permalink raw reply related
* [PATCH v4 0/7] ForLt/CovariantForLt split, auxiliary closure API and DevresLt
From: Danilo Krummrich @ 2026-06-26 18:36 UTC (permalink / raw)
To: gregkh, rafael, dakr, ojeda, boqun, gary, bjorn3_gh, lossin,
a.hindborg, aliceryhl, tmgross, acourbot, ecourtney, m.wilczynski,
david.m.ertman, ira.weiny, leon, daniel.almeida, bhelgaas,
kwilczynski
Cc: driver-core, linux-kernel, nova-gpu, dri-devel, linux-pwm,
rust-for-linux
The ForLt trait currently guarantees covariance, which allows safe
lifetime shortening via cast_ref(). However, some types (e.g. those
containing Mutex<&'bound T>) are invariant over their lifetime parameter
and cannot safely use cast_ref().
This series splits ForLt into two traits:
- ForLt: base trait for all lifetime-parameterized types, providing
only the Of<'a> GAT.
- CovariantForLt: unsafe subtrait that guarantees covariance,
providing a safe cast_ref() method.
For invariant types, a closure-based API (registration_data_with()) is
added to the auxiliary subsystem. The closure's HRTB prevents the caller
from choosing a concrete lifetime, which would be unsound for invariant
types.
On top of that, this series adds DevresLt<F: ForLt>, a thin wrapper
around Devres<F::Of<'static>> that shortens the stored 'static lifetime
back to the caller's borrow scope. DevresLt provides both closure-based
access (access_with/try_access_with for ForLt types) and direct
reference access (access/try_access for CovariantForLt types).
Also implement ForLt and CovariantForLt for Bar, IoMem and
ExclusiveIoMem, and update their into_devres() methods to return
DevresLt. Provide convenience type aliases DevresBar, DevresIoMem and
DevresExclusiveIoMem.
Changes in v4:
- ForLt! macro: run the Prover and emit ProveWf structs for
well-formedness checks
- DevresLt: change Send bound from F::Of<'static>: Send to the
correct for<'a> F::Of<'a>: Send
- Add #[inline] to forwarding functions in registration_data_with,
registration_data, and all DevresLt accessors
Changes in v3:
- Keep UnsafeForLtImpl as the shared helper for both ForLt! and
CovariantForLt!, distinguished by const generic N
- Remove cast_ref_unchecked() from ForLt; lifetime shortening is
handled by borrowing with the target lifetime directly or by
decoupling the HRTB from the outer reference lifetime
Changes in v2:
- Fold the ForLt -> CovariantForLt rename and the new ForLt base trait
into this series
- Add closure-based registration_data_with() for auxiliary ForLt types
- Add auxiliary sample demonstrating ForLt with an invariant Mutex type
- DevresLt: add closure-based access_with()/try_access_with() for ForLt
types alongside direct access()/try_access() for CovariantForLt types
- Make DevresLt::new() unsafe; callers must guarantee the data outlives
the device binding
- Implement both ForLt and CovariantForLt (previously just ForLt) for
Bar, IoMem, ExclusiveIoMem
- Various safety comment and documentation improvements
Danilo Krummrich (7):
rust: types: rename ForLt to CovariantForLt
rust: types: introduce ForLt base trait for CovariantForLt
rust: auxiliary: add registration_data_with() for ForLt types
rust: auxiliary: sample: demonstrate ForLt with invariant Mutex type
rust: devres: add DevresLt for ForLt-aware device resource access
rust: pci: return DevresLt from Bar::into_devres()
rust: io: mem: return DevresLt from
IoMem/ExclusiveIoMem::into_devres()
drivers/gpu/nova-core/driver.rs | 4 +-
drivers/pwm/pwm_th1520.rs | 5 +-
rust/kernel/auxiliary.rs | 78 ++++++++++++++-----
rust/kernel/devres.rs | 106 ++++++++++++++++++++++++++
rust/kernel/io/mem.rs | 65 +++++++++++-----
rust/kernel/pci.rs | 1 +
rust/kernel/pci/io.rs | 37 ++++++---
rust/kernel/types.rs | 1 +
rust/kernel/types/for_lt.rs | 95 ++++++++++++++++-------
rust/macros/for_lt.rs | 72 +++++++++++------
rust/macros/lib.rs | 18 ++++-
samples/rust/rust_driver_auxiliary.rs | 96 ++++++++++++++++-------
12 files changed, 447 insertions(+), 131 deletions(-)
base-commit: 51cb1aa1250c36269474b8b6ca6b6319e170f5a5
--
2.54.0
^ permalink raw reply
* [PATCH v5 20/20] rust: io: implement `IoSysMap`
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Add an enum as sum type for `Mmio` and `SysMem`. This serves similar
purpose of `iosys_map`. Thanks to Rust's type system, all of projection and
struct read/write can be handled by the generic I/O projection mechanism
(i.e. `io_project!`, `io_read!, `io_write!`) for free, and there is no need
to provide things like `iosys_map_rd_field` or `iosys_map_wr_field`. An
enum type also makes it very easy to construct or destruct.
This could be made more generic by implementing on a general purpose sum
type like `Either`; however this is kept specific unless a need arises that
warrants this to be generic over other I/O backends.
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/io.rs | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 137 insertions(+)
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index b5ac3ac86bbd..0c5f53dd0939 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -1446,6 +1446,143 @@ fn as_view(self) -> <Self::Backend as IoBackend>::View<'a, Self::Target> {
}
}
+/// I/O Backend for [`IoSysMap`].
+pub struct IoSysMapBackend;
+
+/// Either [`Mmio`] or [`SysMem`].
+///
+/// This can be used when a piece of logic may wish to handle both MMIO or system memory but does
+/// not want or cannot be generic over I/O backends. This serves a similar purpose to
+/// [`include/linux/iosys-map.h`] in C.
+///
+/// This type can be used like any other types that implements [`Io`]; this also include
+/// [`io_project!`], [`io_read!`], [`io_write!`].
+///
+/// [`include/linux/iosys-map.h`](srctree/include/linux/iosys-map.h)
+pub enum IoSysMap<'a, T: ?Sized> {
+ /// The view is I/O memory.
+ Io(Mmio<'a, T>),
+ /// The view is system memory.
+ Sys(SysMem<'a, T>),
+}
+
+impl<T: ?Sized> Copy for IoSysMap<'_, T> {}
+impl<T: ?Sized> Clone for IoSysMap<'_, T> {
+ #[inline]
+ fn clone(&self) -> Self {
+ *self
+ }
+}
+
+impl<'a, T: ?Sized> From<Mmio<'a, T>> for IoSysMap<'a, T> {
+ #[inline]
+ fn from(value: Mmio<'a, T>) -> Self {
+ IoSysMap::Io(value)
+ }
+}
+
+impl<'a, T: ?Sized> From<SysMem<'a, T>> for IoSysMap<'a, T> {
+ #[inline]
+ fn from(value: SysMem<'a, T>) -> Self {
+ IoSysMap::Sys(value)
+ }
+}
+
+impl IoBackend for IoSysMapBackend {
+ type View<'a, T: ?Sized + KnownSize> = IoSysMap<'a, T>;
+
+ #[inline]
+ fn as_ptr<'a, T: ?Sized + KnownSize>(view: Self::View<'a, T>) -> *mut T {
+ match view {
+ IoSysMap::Io(l) => MmioBackend::as_ptr(l),
+ IoSysMap::Sys(r) => SysMemBackend::as_ptr(r),
+ }
+ }
+
+ #[inline]
+ unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>(
+ view: Self::View<'a, T>,
+ ptr: *mut U,
+ ) -> Self::View<'a, U> {
+ match view {
+ // SAFETY: Per safety requirement.
+ IoSysMap::Io(l) => IoSysMap::Io(unsafe { MmioBackend::project_view(l, ptr) }),
+ // SAFETY: Per safety requirement.
+ IoSysMap::Sys(r) => IoSysMap::Sys(unsafe { SysMemBackend::project_view(r, ptr) }),
+ }
+ }
+}
+
+impl<T> IoCapable<T> for IoSysMapBackend
+where
+ MmioBackend: IoCapable<T>,
+ SysMemBackend: IoCapable<T>,
+{
+ #[inline]
+ fn io_read(view: Self::View<'_, T>) -> T {
+ match view {
+ IoSysMap::Io(l) => MmioBackend::io_read(l),
+ IoSysMap::Sys(r) => SysMemBackend::io_read(r),
+ }
+ }
+
+ #[inline]
+ fn io_write<'a>(view: Self::View<'a, T>, value: T) {
+ match view {
+ IoSysMap::Io(l) => MmioBackend::io_write(l, value),
+ IoSysMap::Sys(r) => SysMemBackend::io_write(r, value),
+ }
+ }
+}
+
+impl IoCopyable for IoSysMapBackend {
+ #[inline]
+ unsafe fn copy_from_io(view: Self::View<'_, [u8]>, buffer: *mut u8) {
+ match view {
+ // SAFETY: Per safety requirement.
+ IoSysMap::Io(l) => unsafe { MmioBackend::copy_from_io(l, buffer) },
+ // SAFETY: Per safety requirement.
+ IoSysMap::Sys(r) => unsafe { SysMemBackend::copy_from_io(r, buffer) },
+ }
+ }
+
+ #[inline]
+ unsafe fn copy_to_io(view: Self::View<'_, [u8]>, buffer: *const u8) {
+ match view {
+ // SAFETY: Per safety requirement.
+ IoSysMap::Io(l) => unsafe { MmioBackend::copy_to_io(l, buffer) },
+ // SAFETY: Per safety requirement.
+ IoSysMap::Sys(r) => unsafe { SysMemBackend::copy_to_io(r, buffer) },
+ }
+ }
+
+ #[inline]
+ fn copy_read<T: FromBytes>(view: Self::View<'_, T>) -> T {
+ match view {
+ IoSysMap::Io(l) => MmioBackend::copy_read(l),
+ IoSysMap::Sys(r) => SysMemBackend::copy_read(r),
+ }
+ }
+
+ #[inline]
+ fn copy_write<T: IntoBytes>(view: Self::View<'_, T>, value: T) {
+ match view {
+ IoSysMap::Io(l) => MmioBackend::copy_write(l, value),
+ IoSysMap::Sys(r) => SysMemBackend::copy_write(r, value),
+ }
+ }
+}
+
+impl<'a, T: ?Sized + KnownSize> IoBase<'a> for IoSysMap<'a, T> {
+ type Backend = IoSysMapBackend;
+ type Target = T;
+
+ #[inline]
+ fn as_view(self) -> IoSysMap<'a, T> {
+ self
+ }
+}
+
// This helper turns associated functions to methods so it can be invoked in macro.
// Used by `io_project!()` only.
#[doc(hidden)]
--
2.54.0
^ permalink raw reply related
* [PATCH v5 19/20] rust: io: add copying methods
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
One feature that was lost from the old `dma_read!` and `dma_write!` when
moving to `io_read!` and `io_write!` was the ability to read/write a large
structs. However, the semantics was unclear to begin with, as there was no
guarantee about their atomicity even for structs that were small enough to
fit in u32. Re-introduce the capability in the form of copying methods.
dma_read!(foo, bar) -> io_project!(foo, bar).copy_read()
dma_write!(foo, bar, baz) -> io_project!(foo, bar).copy_write(baz)
Model these semantics after memcpy so user has clear expectation of lack of
atomicity. As an additional benefit of this change, this now works for MMIO
as well by mapping them to `memcpy_{from,to}io`.
For slices which is DST so the `copy_read` and `copy_write` API above can't
work, add `copy_from_slice` and `copy_to_slice` to copy from/to normal
memory.
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/helpers/io.c | 13 +++
rust/kernel/dma.rs | 25 +++++
rust/kernel/io.rs | 248 ++++++++++++++++++++++++++++++++++++++++++++++-
samples/rust/rust_dma.rs | 15 ++-
4 files changed, 295 insertions(+), 6 deletions(-)
diff --git a/rust/helpers/io.c b/rust/helpers/io.c
index 397810864a24..7ed9a4f77f1b 100644
--- a/rust/helpers/io.c
+++ b/rust/helpers/io.c
@@ -19,6 +19,19 @@ __rust_helper void rust_helper_iounmap(void __iomem *addr)
iounmap(addr);
}
+__rust_helper void rust_helper_memcpy_fromio(void *dst,
+ const volatile void __iomem *src,
+ size_t count)
+{
+ memcpy_fromio(dst, src, count);
+}
+
+__rust_helper void rust_helper_memcpy_toio(volatile void __iomem *dst,
+ const void *src, size_t count)
+{
+ memcpy_toio(dst, src, count);
+}
+
__rust_helper u8 rust_helper_readb(const void __iomem *addr)
{
return readb(addr);
diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
index 0ff4cce8e809..37bc20895803 100644
--- a/rust/kernel/dma.rs
+++ b/rust/kernel/dma.rs
@@ -18,6 +18,7 @@
IoBackend,
IoBase,
IoCapable,
+ IoCopyable,
SysMem,
SysMemBackend, //
},
@@ -1196,6 +1197,30 @@ fn io_write<'a>(view: Self::View<'a, T>, value: T) {
}
}
+impl IoCopyable for CoherentBackend {
+ #[inline]
+ unsafe fn copy_from_io(view: Self::View<'_, [u8]>, buffer: *mut u8) {
+ // SAFETY: Per safety requirement.
+ unsafe { SysMemBackend::copy_from_io(view.cpu_addr, buffer) }
+ }
+
+ #[inline]
+ unsafe fn copy_to_io(view: Self::View<'_, [u8]>, buffer: *const u8) {
+ // SAFETY: Per safety requirement.
+ unsafe { SysMemBackend::copy_to_io(view.cpu_addr, buffer) }
+ }
+
+ #[inline]
+ fn copy_read<T: zerocopy::FromBytes>(view: Self::View<'_, T>) -> T {
+ SysMemBackend::copy_read(view.cpu_addr)
+ }
+
+ #[inline]
+ fn copy_write<T: zerocopy::IntoBytes>(view: Self::View<'_, T>, value: T) {
+ SysMemBackend::copy_write(view.cpu_addr, value)
+ }
+}
+
impl<'a, T: ?Sized + KnownSize> IoBase<'a> for CoherentView<'a, T> {
type Backend = CoherentBackend;
type Target = T;
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index aa82736253ac..b5ac3ac86bbd 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -5,7 +5,8 @@
//! C header: [`include/asm-generic/io.h`](srctree/include/asm-generic/io.h)
use core::{
- marker::PhantomData, //
+ marker::PhantomData,
+ mem::MaybeUninit, //
};
use crate::{
@@ -271,6 +272,61 @@ pub trait IoCapable<T>: IoBackend {
fn io_write<'a>(view: Self::View<'a, T>, value: T);
}
+/// Trait indicating that an I/O backend supports memory copy operations.
+pub trait IoCopyable: IoBackend {
+ /// Copy contents of `view` to `buffer`.
+ ///
+ /// # Safety
+ ///
+ /// - `buffer` is valid for volatile write for `view.size()` bytes.
+ unsafe fn copy_from_io(view: Self::View<'_, [u8]>, buffer: *mut u8);
+
+ /// Copy `size` bytes from `buffer` to `address`.
+ ///
+ /// # Safety
+ ///
+ /// - `buffer` is valid for volatile read for `view.size()` bytes.
+ unsafe fn copy_to_io(view: Self::View<'_, [u8]>, buffer: *const u8);
+
+ /// Copy from `view` and return the value.
+ #[inline]
+ fn copy_read<T: FromBytes>(view: Self::View<'_, T>) -> T {
+ // Project `self` to `[u8]`.
+ let ptr = Self::as_ptr(view);
+ // SAFETY: This is a identity projection.
+ let slice_view = unsafe {
+ Self::project_view(
+ view,
+ core::ptr::slice_from_raw_parts_mut::<u8>(ptr.cast(), size_of::<T>()),
+ )
+ };
+
+ let mut buf = MaybeUninit::<T>::uninit();
+ // SAFETY: `buf.as_mut_ptr()` is valid for write for `size_of::<T>()` bytes.
+ unsafe { Self::copy_from_io(slice_view, buf.as_mut_ptr().cast()) };
+ // SAFETY: T: FromBytes` guarantee that all bit patterns are valid.
+ unsafe { buf.assume_init() }
+ }
+
+ /// Copy `value` to `view`.
+ #[inline]
+ fn copy_write<T: IntoBytes>(view: Self::View<'_, T>, value: T) {
+ // Project `self` to `[u8]`.
+ let ptr = Self::as_ptr(view);
+ // SAFETY: This is a identity projection.
+ let slice_view = unsafe {
+ Self::project_view(
+ view,
+ core::ptr::slice_from_raw_parts_mut::<u8>(ptr.cast(), size_of::<T>()),
+ )
+ };
+
+ // SAFETY: `&raw const value` is valid for read for `size_of::<T>()` bytes.
+ unsafe { Self::copy_to_io(slice_view, (&raw const value).cast()) };
+ core::mem::forget(value);
+ }
+}
+
/// Describes a given I/O location: its offset, width, and type to convert the raw value from and
/// into.
///
@@ -350,6 +406,24 @@ fn size(self) -> usize {
KnownSize::size(Self::Backend::as_ptr(self.as_view()))
}
+ /// Returns the length of the slice in number of elements.
+ #[inline]
+ fn len<T>(self) -> usize
+ where
+ Self: Io<'a, Target = [T]>,
+ {
+ Self::Backend::as_ptr(self.as_view()).len()
+ }
+
+ /// Returns `true` if the slice has a length of 0.
+ #[inline]
+ fn is_empty<T>(self) -> bool
+ where
+ Self: Io<'a, Target = [T]>,
+ {
+ self.len() == 0
+ }
+
/// Try to convert into a different typed I/O view.
///
/// The target type must be of same or smaller size to current type, and the current view must
@@ -437,6 +511,115 @@ fn write_val(self, value: Self::Target)
Self::Backend::io_write(self.as_view(), value)
}
+ /// Copy-read from I/O memory.
+ ///
+ /// This is equivalent to reading from the I/O memory with byte-wise copy, although the actual
+ /// implementation might be more efficient. There is no atomicity guarantee. Note that for some
+ /// backends (e.g. `Mmio`), this can read different value compared to [`read_val`] as
+ /// byte-swapping is not performed.
+ ///
+ /// [`read_val`]: Io::read_val
+ ///
+ /// # Examples
+ ///
+ /// ```no_run
+ /// # use kernel::io::*;
+ /// # fn test_copy_read(mmio: Mmio<'_, [u8; 6]>) {
+ /// // let mmio: Mmio<'_, [u8; 6]>;
+ /// let val: [u8; 6] = mmio.copy_read();
+ /// # }
+ /// ```
+ #[inline]
+ fn copy_read(self) -> Self::Target
+ where
+ Self::Backend: IoCopyable,
+ Self::Target: Sized + FromBytes,
+ {
+ Self::Backend::copy_read(self.as_view())
+ }
+
+ /// Copy-write to I/O memory.
+ ///
+ /// This is equivalent to writing to the I/O memory with byte-wise copy, although the actual
+ /// implementation might be more efficient. There is no atomicity guarantee. Note that for some
+ /// backends (e.g. `Mmio`), this can read different value compared to [`write_val`] as
+ /// byte-swapping is not performed.
+ ///
+ /// [`write_val`]: Io::write_val
+ ///
+ /// # Examples
+ ///
+ /// ```no_run
+ /// # use kernel::io::*;
+ /// # fn test_copy_write(mmio: Mmio<'_, [u8; 6]>) {
+ /// // let mmio: Mmio<'_, [u8; 6]>;
+ /// mmio.copy_write([0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF]);
+ /// # }
+ /// ```
+ #[inline]
+ fn copy_write(self, value: Self::Target)
+ where
+ Self::Backend: IoCopyable,
+ Self::Target: Sized + IntoBytes,
+ {
+ Self::Backend::copy_write(self.as_view(), value);
+ }
+
+ /// Copy bytes from slice to I/O memory.
+ ///
+ /// The length of `self` must be the same as `data`, similar to [`[u8]::copy_from_slice`].
+ ///
+ /// # Examples
+ ///
+ /// ```no_run
+ /// # use kernel::io::*;
+ /// # fn test_copy_write(mmio: Mmio<'_, [u8]>) {
+ /// // let mmio: Mmio<'_, [u8]>;
+ /// mmio.copy_from_slice(&[0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF]);
+ /// # }
+ /// ```
+ #[inline]
+ fn copy_from_slice(self, data: &[u8])
+ where
+ Self::Backend: IoCopyable,
+ Self: Io<'a, Target = [u8]>,
+ {
+ assert_eq!(self.len(), data.len());
+
+ // SAFETY: `data.as_ptr()` is valid for read for `self.size()` bytes.
+ unsafe {
+ Self::Backend::copy_to_io(self.as_view(), data.as_ptr());
+ }
+ }
+
+ /// Copy bytes from I/O memory to slice.
+ ///
+ /// The length of `self` must be the same as `data`, similar to [`[u8]::copy_from_slice`].
+ ///
+ /// # Examples
+ ///
+ /// ```no_run
+ /// # use kernel::io::*;
+ /// # fn test_copy_write(mmio: Mmio<'_, [u8]>) {
+ /// // let mmio: Mmio<'_, [u8]>;
+ /// let mut buf = [0; 6];
+ /// mmio.copy_to_slice(&mut buf);
+ /// # }
+ /// ```
+ #[inline]
+ fn copy_to_slice(self, data: &mut [u8])
+ where
+ Self::Backend: IoCopyable,
+ Self: Io<'a, Target = [u8]>,
+ {
+ assert_eq!(self.len(), data.len());
+
+ // SAFETY: `data.as_ptr()` is valid for write for `self.size()` bytes.
+ unsafe {
+ Self::Backend::copy_from_io(self.as_view(), data.as_mut_ptr());
+ }
+ }
+
/// Fallible 8-bit read with runtime bounds check.
#[inline(always)]
fn try_read8(self, offset: usize) -> Result<u8>
@@ -995,6 +1178,28 @@ fn io_write(view: <$backend as IoBackend>::View<'_, $ty>, value: $ty) {
#[cfg(CONFIG_64BIT)]
impl_mmio_io_capable!(MmioBackend, u64, readq, writeq);
+impl IoCopyable for MmioBackend {
+ #[inline]
+ unsafe fn copy_from_io(view: Self::View<'_, [u8]>, buffer: *mut u8) {
+ // SAFETY:
+ // - `view.ptr` is valid MMIO memory for `view.size()` bytes.
+ // - `buffer` is valid for write for `view.size()` bytes.
+ unsafe {
+ bindings::memcpy_fromio(buffer.cast(), view.ptr.cast(), view.size());
+ }
+ }
+
+ #[inline]
+ unsafe fn copy_to_io(view: Self::View<'_, [u8]>, buffer: *const u8) {
+ // SAFETY:
+ // - `view.ptr` is valid MMIO memory for `view.size()` bytes.
+ // - `buffer` is valid for read for `view.size()` bytes.
+ unsafe {
+ bindings::memcpy_toio(view.ptr.cast(), buffer.cast(), view.size());
+ }
+ }
+}
+
/// [`Mmio`] but using relaxed accessors.
///
/// This type provides an implementation of [`Io`] that uses relaxed I/O MMIO operands instead of
@@ -1138,6 +1343,47 @@ fn io_write(view: SysMem<'_, $ty>, value: $ty) {
#[cfg(CONFIG_64BIT)]
impl_sysmem_io_capable!(u64);
+impl IoCopyable for SysMemBackend {
+ #[inline]
+ unsafe fn copy_from_io(view: Self::View<'_, [u8]>, buffer: *mut u8) {
+ // Use `bindings::memcpy` instead of `copy_nonoverlapping` for volatile.
+ // SAFETY:
+ // - `view.ptr` is in CPU address space and valid for read.
+ // - `buffer` is valid for write for `view.size()` bytes which is equal to `view.ptr.len()`.
+ unsafe { bindings::memcpy(buffer.cast(), view.ptr.cast(), view.ptr.len()) };
+ }
+
+ #[inline]
+ unsafe fn copy_to_io(view: Self::View<'_, [u8]>, buffer: *const u8) {
+ // Use `bindings::memcpy` instead of `copy_nonoverlapping` for volatile.
+ // SAFETY:
+ // - `view.ptr` is in CPU address space and valid for write.
+ // - `buffer` is valid for read for `view.size()` bytes which is equal to `view.ptr.len()`.
+ unsafe { bindings::memcpy(view.ptr.cast(), buffer.cast(), view.ptr.len()) };
+ }
+
+ #[inline]
+ fn copy_read<T: FromBytes>(view: Self::View<'_, T>) -> T {
+ // SAFETY:
+ // - Per type invariant, `ptr` is valid and aligned.
+ // - Using read_volatile() here so that race with hardware is well-defined.
+ // - Using read_volatile() here is not sound if it races with other CPU per Rust
+ // rules, but this is allowed per LKMM.
+ // - `T: FromBytes` so all bit patterns are valid.
+ unsafe { view.ptr.read_volatile() }
+ }
+
+ #[inline]
+ fn copy_write<T: IntoBytes>(view: Self::View<'_, T>, value: T) {
+ // SAFETY:
+ // - Per type invariant, `ptr` is valid and aligned.
+ // - Using write_volatile() here so that race with hardware is well-defined.
+ // - Using write_volatile() here is not sound if it races with other CPU per Rust
+ // rules, but this is allowed per LKMM.
+ unsafe { view.ptr.write_volatile(value) }
+ }
+}
+
/// System memory region.
///
/// Provides `Io` trait implementation for kernel virtual address ranges,
diff --git a/samples/rust/rust_dma.rs b/samples/rust/rust_dma.rs
index 6727c441658a..b629acc6d915 100644
--- a/samples/rust/rust_dma.rs
+++ b/samples/rust/rust_dma.rs
@@ -12,7 +12,11 @@
Device,
DmaMask, //
},
- io::io_read,
+ io::{
+ io_project,
+ io_read,
+ Io, //
+ },
page, pci,
prelude::*,
scatterlist::{Owned, SGTable},
@@ -35,6 +39,7 @@ struct DmaSampleDriver {
(0xcd, 0xef),
];
+#[derive(FromBytes, IntoBytes)]
struct MyStruct {
h: u32,
b: u32,
@@ -74,11 +79,11 @@ fn probe<'bound>(
// SAFETY: There are no concurrent calls to DMA allocation and mapping primitives.
unsafe { pdev.dma_set_mask_and_coherent(mask)? };
- let mut ca: CoherentBox<[MyStruct]> =
- CoherentBox::zeroed_slice(pdev.as_ref(), TEST_VALUES.len(), GFP_KERNEL)?;
+ let ca: Coherent<[MyStruct]> =
+ Coherent::zeroed_slice(pdev.as_ref(), TEST_VALUES.len(), GFP_KERNEL)?;
for (i, value) in TEST_VALUES.into_iter().enumerate() {
- ca.init_at(i, MyStruct::new(value.0, value.1))?;
+ io_project!(ca, [panic: i]).copy_write(MyStruct::new(value.0, value.1));
}
let size = 4 * page::PAGE_SIZE;
@@ -88,7 +93,7 @@ fn probe<'bound>(
Ok(try_pin_init!(Self {
pdev: pdev.into(),
- ca: ca.into(),
+ ca,
sgt <- sgt,
}))
})
--
2.54.0
^ permalink raw reply related
* [PATCH v5 18/20] rust: dma: drop `dma_read!` and `dma_write!` API
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
The primitive read/write use case is covered by the `io_read!` and
`io_write!` macro. The non-primitive use case was finicky; they should
either be achieved using `CoherentBox` or `as_ref()/as_mut()` to assert the
lack of concurrent access, or should be using memcpy-like APIs to express
the non-atomic and tearable nature.
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/dma.rs | 128 -----------------------------------------------
samples/rust/rust_dma.rs | 13 ++---
2 files changed, 7 insertions(+), 134 deletions(-)
diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
index ab6504910e4f..0ff4cce8e809 100644
--- a/rust/kernel/dma.rs
+++ b/rust/kernel/dma.rs
@@ -661,52 +661,6 @@ pub unsafe fn as_mut(&self) -> &mut T {
// SAFETY: per safety requirement.
unsafe { &mut *self.as_mut_ptr() }
}
-
- /// Reads the value of `field` and ensures that its type is [`FromBytes`].
- ///
- /// # Safety
- ///
- /// This must be called from the [`dma_read`] macro which ensures that the `field` pointer is
- /// validated beforehand.
- ///
- /// Public but hidden since it should only be used from [`dma_read`] macro.
- #[doc(hidden)]
- pub unsafe fn field_read<F: FromBytes>(&self, field: *const F) -> F {
- // SAFETY:
- // - By the safety requirements field is valid.
- // - Using read_volatile() here is not sound as per the usual rules, the usage here is
- // a special exception with the following notes in place. When dealing with a potential
- // race from a hardware or code outside kernel (e.g. user-space program), we need that
- // read on a valid memory is not UB. Currently read_volatile() is used for this, and the
- // rationale behind is that it should generate the same code as READ_ONCE() which the
- // kernel already relies on to avoid UB on data races. Note that the usage of
- // read_volatile() is limited to this particular case, it cannot be used to prevent
- // the UB caused by racing between two kernel functions nor do they provide atomicity.
- unsafe { field.read_volatile() }
- }
-
- /// Writes a value to `field` and ensures that its type is [`AsBytes`].
- ///
- /// # Safety
- ///
- /// This must be called from the [`dma_write`] macro which ensures that the `field` pointer is
- /// validated beforehand.
- ///
- /// Public but hidden since it should only be used from [`dma_write`] macro.
- #[doc(hidden)]
- pub unsafe fn field_write<F: AsBytes>(&self, field: *mut F, val: F) {
- // SAFETY:
- // - By the safety requirements field is valid.
- // - Using write_volatile() here is not sound as per the usual rules, the usage here is
- // a special exception with the following notes in place. When dealing with a potential
- // race from a hardware or code outside kernel (e.g. user-space program), we need that
- // write on a valid memory is not UB. Currently write_volatile() is used for this, and the
- // rationale behind is that it should generate the same code as WRITE_ONCE() which the
- // kernel already relies on to avoid UB on data races. Note that the usage of
- // write_volatile() is limited to this particular case, it cannot be used to prevent
- // the UB caused by racing between two kernel functions nor do they provide atomicity.
- unsafe { field.write_volatile(val) }
- }
}
impl<T: AsBytes + FromBytes> Coherent<T> {
@@ -1265,85 +1219,3 @@ fn as_view(self) -> CoherentView<'a, Self::Target> {
}
}
}
-
-/// Reads a field of an item from an allocated region of structs.
-///
-/// The syntax is of the form `kernel::dma_read!(dma, proj)` where `dma` is an expression evaluating
-/// to a [`Coherent`] and `proj` is a [projection specification](kernel::ptr::project!).
-///
-/// # Examples
-///
-/// ```
-/// use kernel::device::Device;
-/// use kernel::dma::{attrs::*, Coherent};
-///
-/// struct MyStruct { field: u32, }
-///
-/// // SAFETY: All bit patterns are acceptable values for `MyStruct`.
-/// unsafe impl kernel::transmute::FromBytes for MyStruct{};
-/// // SAFETY: Instances of `MyStruct` have no uninitialized portions.
-/// unsafe impl kernel::transmute::AsBytes for MyStruct{};
-///
-/// # fn test(alloc: &kernel::dma::Coherent<[MyStruct]>) -> Result {
-/// let whole = kernel::dma_read!(alloc, [try: 2]);
-/// let field = kernel::dma_read!(alloc, [panic: 1].field);
-/// # Ok::<(), Error>(()) }
-/// ```
-#[macro_export]
-macro_rules! dma_read {
- ($dma:expr, $($proj:tt)*) => {{
- let dma = &$dma;
- let ptr = $crate::ptr::project!(
- $crate::dma::Coherent::as_ptr(dma), $($proj)*
- );
- // SAFETY: The pointer created by the projection is within the DMA region.
- unsafe { $crate::dma::Coherent::field_read(dma, ptr) }
- }};
-}
-
-/// Writes to a field of an item from an allocated region of structs.
-///
-/// The syntax is of the form `kernel::dma_write!(dma, proj, val)` where `dma` is an expression
-/// evaluating to a [`Coherent`], `proj` is a
-/// [projection specification](kernel::ptr::project!), and `val` is the value to be written to the
-/// projected location.
-///
-/// # Examples
-///
-/// ```
-/// use kernel::device::Device;
-/// use kernel::dma::{attrs::*, Coherent};
-///
-/// struct MyStruct { member: u32, }
-///
-/// // SAFETY: All bit patterns are acceptable values for `MyStruct`.
-/// unsafe impl kernel::transmute::FromBytes for MyStruct{};
-/// // SAFETY: Instances of `MyStruct` have no uninitialized portions.
-/// unsafe impl kernel::transmute::AsBytes for MyStruct{};
-///
-/// # fn test(alloc: &kernel::dma::Coherent<[MyStruct]>) -> Result {
-/// kernel::dma_write!(alloc, [try: 2].member, 0xf);
-/// kernel::dma_write!(alloc, [panic: 1], MyStruct { member: 0xf });
-/// # Ok::<(), Error>(()) }
-/// ```
-#[macro_export]
-macro_rules! dma_write {
- (@parse [$dma:expr] [$($proj:tt)*] [, $val:expr]) => {{
- let dma = &$dma;
- let ptr = $crate::ptr::project!(
- mut $crate::dma::Coherent::as_mut_ptr(dma), $($proj)*
- );
- let val = $val;
- // SAFETY: The pointer created by the projection is within the DMA region.
- unsafe { $crate::dma::Coherent::field_write(dma, ptr, val) }
- }};
- (@parse [$dma:expr] [$($proj:tt)*] [.$field:tt $($rest:tt)*]) => {
- $crate::dma_write!(@parse [$dma] [$($proj)* .$field] [$($rest)*])
- };
- (@parse [$dma:expr] [$($proj:tt)*] [[$flavor:ident: $index:expr] $($rest:tt)*]) => {
- $crate::dma_write!(@parse [$dma] [$($proj)* [$flavor: $index]] [$($rest)*])
- };
- ($dma:expr, $($rest:tt)*) => {
- $crate::dma_write!(@parse [$dma] [] [$($rest)*])
- };
-}
diff --git a/samples/rust/rust_dma.rs b/samples/rust/rust_dma.rs
index 5046b4628d0e..6727c441658a 100644
--- a/samples/rust/rust_dma.rs
+++ b/samples/rust/rust_dma.rs
@@ -12,6 +12,7 @@
Device,
DmaMask, //
},
+ io::io_read,
page, pci,
prelude::*,
scatterlist::{Owned, SGTable},
@@ -73,11 +74,11 @@ fn probe<'bound>(
// SAFETY: There are no concurrent calls to DMA allocation and mapping primitives.
unsafe { pdev.dma_set_mask_and_coherent(mask)? };
- let ca: Coherent<[MyStruct]> =
- Coherent::zeroed_slice(pdev.as_ref(), TEST_VALUES.len(), GFP_KERNEL)?;
+ let mut ca: CoherentBox<[MyStruct]> =
+ CoherentBox::zeroed_slice(pdev.as_ref(), TEST_VALUES.len(), GFP_KERNEL)?;
for (i, value) in TEST_VALUES.into_iter().enumerate() {
- kernel::dma_write!(ca, [try: i], MyStruct::new(value.0, value.1));
+ ca.init_at(i, MyStruct::new(value.0, value.1))?;
}
let size = 4 * page::PAGE_SIZE;
@@ -87,7 +88,7 @@ fn probe<'bound>(
Ok(try_pin_init!(Self {
pdev: pdev.into(),
- ca,
+ ca: ca.into(),
sgt <- sgt,
}))
})
@@ -97,8 +98,8 @@ fn probe<'bound>(
impl DmaSampleDriver {
fn check_dma(&self) {
for (i, value) in TEST_VALUES.into_iter().enumerate() {
- let val0 = kernel::dma_read!(self.ca, [panic: i].h);
- let val1 = kernel::dma_read!(self.ca, [panic: i].b);
+ let val0 = io_read!(self.ca, [panic: i].h);
+ let val1 = io_read!(self.ca, [panic: i].b);
assert_eq!(val0, value.0);
assert_eq!(val1, value.1);
--
2.54.0
^ permalink raw reply related
* [PATCH v5 17/20] gpu: nova-core: use I/O projection for cleaner encapsulation
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Use `io_project!` for PTE array and message queues to restore the proper
encapsulation.
The remaining `dma_read!` and `dma_write!` is now only acting on
primitives; thus replace by `io_read!` and `io_write!`.
Signed-off-by: Gary Guo <gary@garyguo.net>
---
drivers/gpu/nova-core/gsp.rs | 53 ++++++++++++-------------
drivers/gpu/nova-core/gsp/cmdq.rs | 66 +++++++++++++++++--------------
drivers/gpu/nova-core/gsp/fw.rs | 82 +++++++++++++--------------------------
3 files changed, 90 insertions(+), 111 deletions(-)
diff --git a/drivers/gpu/nova-core/gsp.rs b/drivers/gpu/nova-core/gsp.rs
index 69175ca3315c..cfa7553cd820 100644
--- a/drivers/gpu/nova-core/gsp.rs
+++ b/drivers/gpu/nova-core/gsp.rs
@@ -9,14 +9,16 @@
dma::{
Coherent,
CoherentBox,
+ CoherentView,
DmaAddress, //
},
+ io::{
+ io_project,
+ io_write,
+ Io, //
+ },
pci,
- prelude::*,
- transmute::{
- AsBytes,
- FromBytes, //
- }, //
+ prelude::*, //
};
pub(crate) mod cmdq;
@@ -48,21 +50,21 @@
/// Array of page table entries, as understood by the GSP bootloader.
#[repr(C)]
+#[derive(FromBytes, IntoBytes)]
struct PteArray<const NUM_ENTRIES: usize>([u64; NUM_ENTRIES]);
-/// SAFETY: arrays of `u64` implement `FromBytes` and we are but a wrapper around one.
-unsafe impl<const NUM_ENTRIES: usize> FromBytes for PteArray<NUM_ENTRIES> {}
-
-/// SAFETY: arrays of `u64` implement `AsBytes` and we are but a wrapper around one.
-unsafe impl<const NUM_ENTRIES: usize> AsBytes for PteArray<NUM_ENTRIES> {}
-
impl<const NUM_PAGES: usize> PteArray<NUM_PAGES> {
- /// Returns the page table entry for `index`, for a mapping starting at `start`.
- // TODO: Replace with `IoView` projection once available.
- fn entry(start: DmaAddress, index: usize) -> Result<u64> {
- start
- .checked_add(num::usize_as_u64(index) << GSP_PAGE_SHIFT)
- .ok_or(EOVERFLOW)
+ /// Initialize a new page table array mapping `NUM_PAGES` GSP pages starting at address `start`.
+ fn init(view: CoherentView<'_, Self>, start: DmaAddress) -> Result<()> {
+ for i in 0..NUM_PAGES {
+ io_write!(view, .0[build: i],
+ start
+ .checked_add(num::usize_as_u64(i) << GSP_PAGE_SHIFT)
+ .ok_or(EOVERFLOW)?
+ );
+ }
+
+ Ok(())
}
}
@@ -89,17 +91,12 @@ fn new(dev: &device::Device<device::Bound>) -> Result<Self> {
let start_addr = obj.0.dma_handle();
- // SAFETY: `obj` has just been created and we are its sole user.
- let pte_region = unsafe {
- &mut obj.0.as_mut()[size_of::<u64>()..][..RM_LOG_BUFFER_NUM_PAGES * size_of::<u64>()]
- };
-
- // Write values one by one to avoid an on-stack instance of `PteArray`.
- for (i, chunk) in pte_region.chunks_exact_mut(size_of::<u64>()).enumerate() {
- let pte_value = PteArray::<0>::entry(start_addr, i)?;
-
- chunk.copy_from_slice(&pte_value.to_ne_bytes());
- }
+ let pte_view = io_project!(
+ obj.0,
+ [build: size_of::<u64>()..][build: ..RM_LOG_BUFFER_NUM_PAGES * size_of::<u64>()]
+ )
+ .try_cast::<PteArray<RM_LOG_BUFFER_NUM_PAGES>>()?;
+ PteArray::init(pte_view, start_addr)?;
Ok(obj)
}
diff --git a/drivers/gpu/nova-core/gsp/cmdq.rs b/drivers/gpu/nova-core/gsp/cmdq.rs
index 070de0731e95..c34b48961496 100644
--- a/drivers/gpu/nova-core/gsp/cmdq.rs
+++ b/drivers/gpu/nova-core/gsp/cmdq.rs
@@ -2,16 +2,23 @@
mod continuation;
-use core::mem;
+use core::{
+ mem,
+ sync::atomic::{
+ fence,
+ Ordering, //
+ },
+};
use kernel::{
device,
dma::{
Coherent,
+ CoherentBox,
DmaAddress, //
},
- dma_write,
io::{
+ io_project,
poll::read_poll_timeout,
Io, //
},
@@ -171,20 +178,18 @@ struct MsgqData {
#[repr(C)]
// There is no struct defined for this in the open-gpu-kernel-source headers.
// Instead it is defined by code in `GspMsgQueuesInit()`.
-// TODO: Revert to private once `IoView` projections replace the `gsp_mem` module.
-pub(super) struct Msgq {
+struct Msgq {
/// Header for sending messages, including the write pointer.
- pub(super) tx: MsgqTxHeader,
+ tx: MsgqTxHeader,
/// Header for receiving messages, including the read pointer.
- pub(super) rx: MsgqRxHeader,
+ rx: MsgqRxHeader,
/// The message queue proper.
msgq: MsgqData,
}
/// Structure shared between the driver and the GSP and containing the command and message queues.
#[repr(C)]
-// TODO: Revert to private once `IoView` projections replace the `gsp_mem` module.
-pub(super) struct GspMem {
+struct GspMem {
/// Self-mapping page table entries.
ptes: PteArray<{ Self::PTE_ARRAY_SIZE }>,
/// CPU queue: the driver writes commands here, and the GSP reads them. It also contains the
@@ -192,13 +197,13 @@ pub(super) struct GspMem {
/// index into the GSP queue.
///
/// This member is read-only for the GSP.
- pub(super) cpuq: Msgq,
+ cpuq: Msgq,
/// GSP queue: the GSP writes messages here, and the driver reads them. It also contains the
/// write and read pointers that the GSP updates. This means that the read pointer here is an
/// index into the CPU queue.
///
/// This member is read-only for the driver.
- pub(super) gspq: Msgq,
+ gspq: Msgq,
}
impl GspMem {
@@ -232,20 +237,12 @@ fn new(dev: &device::Device<device::Bound>) -> Result<Self> {
const MSGQ_SIZE: u32 = num::usize_into_u32::<{ size_of::<Msgq>() }>();
const RX_HDR_OFF: u32 = num::usize_into_u32::<{ mem::offset_of!(Msgq, rx) }>();
- let gsp_mem = Coherent::<GspMem>::zeroed(dev, GFP_KERNEL)?;
-
- let start = gsp_mem.dma_handle();
- // Write values one by one to avoid an on-stack instance of `PteArray`.
- for i in 0..GspMem::PTE_ARRAY_SIZE {
- dma_write!(gsp_mem, .ptes.0[build: i], PteArray::<0>::entry(start, i)?);
- }
+ let mut gsp_mem = CoherentBox::<GspMem>::zeroed(dev, GFP_KERNEL)?;
+ gsp_mem.cpuq.tx = MsgqTxHeader::new(MSGQ_SIZE, RX_HDR_OFF, MSGQ_NUM_PAGES);
+ gsp_mem.cpuq.rx = MsgqRxHeader::new();
- dma_write!(
- gsp_mem,
- .cpuq.tx,
- MsgqTxHeader::new(MSGQ_SIZE, RX_HDR_OFF, MSGQ_NUM_PAGES)
- );
- dma_write!(gsp_mem, .cpuq.rx, MsgqRxHeader::new());
+ let gsp_mem: Coherent<_> = gsp_mem.into();
+ PteArray::init(io_project!(gsp_mem, .ptes), gsp_mem.dma_handle())?;
Ok(Self(gsp_mem))
}
@@ -406,7 +403,7 @@ fn allocate_command(&mut self, size: usize, timeout: Delta) -> Result<GspCommand
//
// - The returned value is within `0..MSGQ_NUM_PAGES`.
fn gsp_write_ptr(&self) -> u32 {
- super::fw::gsp_mem::gsp_write_ptr(&self.0)
+ MsgqTxHeader::write_ptr(io_project!(self.0, .gspq.tx)) % MSGQ_NUM_PAGES
}
// Returns the index of the memory page the GSP will read the next command from.
@@ -415,7 +412,7 @@ fn gsp_write_ptr(&self) -> u32 {
//
// - The returned value is within `0..MSGQ_NUM_PAGES`.
fn gsp_read_ptr(&self) -> u32 {
- super::fw::gsp_mem::gsp_read_ptr(&self.0)
+ MsgqRxHeader::read_ptr(io_project!(self.0, .gspq.rx)) % MSGQ_NUM_PAGES
}
// Returns the index of the memory page the CPU can read the next message from.
@@ -424,12 +421,18 @@ fn gsp_read_ptr(&self) -> u32 {
//
// - The returned value is within `0..MSGQ_NUM_PAGES`.
fn cpu_read_ptr(&self) -> u32 {
- super::fw::gsp_mem::cpu_read_ptr(&self.0)
+ MsgqRxHeader::read_ptr(io_project!(self.0, .cpuq.rx)) % MSGQ_NUM_PAGES
}
// Informs the GSP that it can send `elem_count` new pages into the message queue.
fn advance_cpu_read_ptr(&mut self, elem_count: u32) {
- super::fw::gsp_mem::advance_cpu_read_ptr(&self.0, elem_count)
+ let rx = io_project!(self.0, .cpuq.rx);
+ let rptr = MsgqRxHeader::read_ptr(rx).wrapping_add(elem_count) % MSGQ_NUM_PAGES;
+
+ // Ensure read pointer is properly ordered.
+ fence(Ordering::SeqCst);
+
+ MsgqRxHeader::set_read_ptr(rx, rptr)
}
// Returns the index of the memory page the CPU can write the next command to.
@@ -438,12 +441,17 @@ fn advance_cpu_read_ptr(&mut self, elem_count: u32) {
//
// - The returned value is within `0..MSGQ_NUM_PAGES`.
fn cpu_write_ptr(&self) -> u32 {
- super::fw::gsp_mem::cpu_write_ptr(&self.0)
+ MsgqTxHeader::write_ptr(io_project!(self.0, .cpuq.tx)) % MSGQ_NUM_PAGES
}
// Informs the GSP that it can process `elem_count` new pages from the command queue.
fn advance_cpu_write_ptr(&mut self, elem_count: u32) {
- super::fw::gsp_mem::advance_cpu_write_ptr(&self.0, elem_count)
+ let tx = io_project!(self.0, .cpuq.tx);
+ let wptr = MsgqTxHeader::write_ptr(tx).wrapping_add(elem_count) % MSGQ_NUM_PAGES;
+ MsgqTxHeader::set_write_ptr(tx, wptr);
+
+ // Ensure all command data is visible before triggering the GSP read.
+ fence(Ordering::SeqCst);
}
}
diff --git a/drivers/gpu/nova-core/gsp/fw.rs b/drivers/gpu/nova-core/gsp/fw.rs
index 4db0cfa4dc4d..b0e7de328eaf 100644
--- a/drivers/gpu/nova-core/gsp/fw.rs
+++ b/drivers/gpu/nova-core/gsp/fw.rs
@@ -10,7 +10,14 @@
use core::ops::Range;
use kernel::{
- dma::Coherent,
+ dma::{
+ Coherent,
+ CoherentView, //
+ },
+ io::{
+ io_read,
+ io_write, //
+ },
prelude::*,
ptr::{
Alignable,
@@ -44,59 +51,6 @@
},
};
-// TODO: Replace with `IoView` projections once available.
-pub(super) mod gsp_mem {
- use core::sync::atomic::{
- fence,
- Ordering, //
- };
-
- use kernel::{
- dma::Coherent,
- dma_read,
- dma_write, //
- };
-
- use crate::gsp::cmdq::{
- GspMem,
- MSGQ_NUM_PAGES, //
- };
-
- pub(in crate::gsp) fn gsp_write_ptr(qs: &Coherent<GspMem>) -> u32 {
- dma_read!(qs, .gspq.tx.0.writePtr) % MSGQ_NUM_PAGES
- }
-
- pub(in crate::gsp) fn gsp_read_ptr(qs: &Coherent<GspMem>) -> u32 {
- dma_read!(qs, .gspq.rx.0.readPtr) % MSGQ_NUM_PAGES
- }
-
- pub(in crate::gsp) fn cpu_read_ptr(qs: &Coherent<GspMem>) -> u32 {
- dma_read!(qs, .cpuq.rx.0.readPtr) % MSGQ_NUM_PAGES
- }
-
- pub(in crate::gsp) fn advance_cpu_read_ptr(qs: &Coherent<GspMem>, count: u32) {
- let rptr = cpu_read_ptr(qs).wrapping_add(count) % MSGQ_NUM_PAGES;
-
- // Ensure read pointer is properly ordered.
- fence(Ordering::SeqCst);
-
- dma_write!(qs, .cpuq.rx.0.readPtr, rptr);
- }
-
- pub(in crate::gsp) fn cpu_write_ptr(qs: &Coherent<GspMem>) -> u32 {
- dma_read!(qs, .cpuq.tx.0.writePtr) % MSGQ_NUM_PAGES
- }
-
- pub(in crate::gsp) fn advance_cpu_write_ptr(qs: &Coherent<GspMem>, count: u32) {
- let wptr = cpu_write_ptr(qs).wrapping_add(count) % MSGQ_NUM_PAGES;
-
- dma_write!(qs, .cpuq.tx.0.writePtr, wptr);
-
- // Ensure all command data is visible before triggering the GSP read.
- fence(Ordering::SeqCst);
- }
-}
-
/// Maximum size of a single GSP message queue element in bytes.
pub(crate) const GSP_MSG_QUEUE_ELEMENT_SIZE_MAX: usize =
num::u32_as_usize(bindings::GSP_MSG_QUEUE_ELEMENT_SIZE_MAX);
@@ -720,6 +674,16 @@ pub(crate) fn new(msgq_size: u32, rx_hdr_offset: u32, msg_count: u32) -> Self {
entryOff: num::usize_into_u32::<GSP_PAGE_SIZE>(),
})
}
+
+ /// Returns the value of the write pointer for this queue.
+ pub(crate) fn write_ptr(this: CoherentView<'_, Self>) -> u32 {
+ io_read!(this, .0.writePtr)
+ }
+
+ /// Sets the value of the write pointer for this queue.
+ pub(crate) fn set_write_ptr(this: CoherentView<'_, Self>, val: u32) {
+ io_write!(this, .0.writePtr, val)
+ }
}
// SAFETY: Padding is explicit and does not contain uninitialized data.
@@ -735,6 +699,16 @@ impl MsgqRxHeader {
pub(crate) fn new() -> Self {
Self(Default::default())
}
+
+ /// Returns the value of the read pointer for this queue.
+ pub(crate) fn read_ptr(this: CoherentView<'_, Self>) -> u32 {
+ io_read!(this, .0.readPtr)
+ }
+
+ /// Sets the value of the read pointer for this queue.
+ pub(crate) fn set_read_ptr(this: CoherentView<'_, Self>, val: u32) {
+ io_write!(this, .0.readPtr, val)
+ }
}
// SAFETY: Padding is explicit and does not contain uninitialized data.
--
2.54.0
^ permalink raw reply related
* [PATCH v5 16/20] rust: io: add `read_val` and `write_val` functions on `Io`
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Provide `read_val` and `write_val` that allow I/O views to be accessed when
they're narrowed down to just views of primitives.
This is used to provide `io_read!` and `io_write!` macros, which are
generalized version of current `dma_read!` and `dma_write!` macro that work
for all types that implement `Io`.
Note though `io_read!` and `io_write!` only works if backend implements
`IoCapable` for the type; which is typically only implemented for
atomically accessible primitives. `dma_read!` and `dma_write!` currently
supports them via `read_volatile` and `write_volatile`; this can be
undesirable for aggregates as LLVM may turn them to multiple instructions
to access parts and re-assemble, even if they could be combined to a single
instruction. Thus, `io_read!()` and `io_write!()` does not fully replace
`dma_read!()` and `dma_write!()` in this scenario. The ability to
read/write aggregates (when atomicity is of no concern) is better served
with copying primitives (e.g. memcpy_{from,to}io).
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/io.rs | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 104 insertions(+)
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 5c06785facea..aa82736253ac 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -393,6 +393,50 @@ fn try_cast<U>(self) -> Result<<Self::Backend as IoBackend>::View<'a, U>>
Ok(unsafe { Self::Backend::project_view(view, ptr.cast()) })
}
+ /// Read a value from I/O.
+ ///
+ /// This only works for primitives supported by the I/O backend.
+ ///
+ /// # Examples
+ ///
+ /// ```no_run
+ /// # use kernel::io::*;
+ /// # fn test_read_val(mmio: Mmio<'_, u32>) {
+ /// // let mmio: Mmio<'_, u32>;
+ /// let val: u32 = mmio.read_val();
+ /// # }
+ /// ```
+ #[inline]
+ fn read_val(self) -> Self::Target
+ where
+ Self::Backend: IoCapable<Self::Target>,
+ Self::Target: Sized,
+ {
+ Self::Backend::io_read(self.as_view())
+ }
+
+ /// Write a value to I/O.
+ ///
+ /// This only works for primitives supported by the I/O backend.
+ ///
+ /// # Examples
+ ///
+ /// ```no_run
+ /// # use kernel::io::*;
+ /// # fn test_write_val(mmio: Mmio<'_, u32>) {
+ /// // let mmio: Mmio<'_, u32>;
+ /// mmio.write_val(1u32);
+ /// # }
+ /// ```
+ #[inline]
+ fn write_val(self, value: Self::Target)
+ where
+ Self::Backend: IoCapable<Self::Target>,
+ Self::Target: Sized,
+ {
+ Self::Backend::io_write(self.as_view(), value)
+ }
+
/// Fallible 8-bit read with runtime bounds check.
#[inline(always)]
fn try_read8(self, offset: usize) -> Result<u8>
@@ -1225,3 +1269,63 @@ macro_rules! io_project {
}
#[doc(inline)]
pub use crate::io_project;
+
+/// Read from I/O memory.
+///
+/// The syntax is of form `io_read!(io, proj)` where `io` is an expression to a type that
+/// implements [`Io`] and `proj` is a [projection specification](kernel::ptr::project!).
+///
+/// # Examples
+///
+/// ```
+/// struct MyStruct { field: u32, }
+///
+/// # fn test(mmio: kernel::io::Mmio<'_, [MyStruct]>) -> Result {
+/// // let mmio: Mmio<'_, [MyStruct]>;
+/// let field: u32 = kernel::io::io_read!(mmio, [try: 2].field);
+/// # Ok::<(), Error>(()) }
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! io_read {
+ ($io:expr, $($proj:tt)*) => {
+ $crate::io::Io::read_val($crate::io_project!($io, $($proj)*))
+ };
+}
+#[doc(inline)]
+pub use crate::io_read;
+
+/// Writes to I/O memory.
+///
+/// The syntax is of form `io_write!(io, proj, val)` where `io` is an expression to a type that
+/// implements [`Io`] and `proj` is a [projection specification](kernel::ptr::project!),
+/// and `val` is the value to be written to the projected location.
+///
+/// # Examples
+///
+/// ```
+/// struct MyStruct { field: u32, }
+///
+/// # fn test(mmio: kernel::io::Mmio<'_, [MyStruct]>) -> Result {
+/// // let mmio: Mmio<'_, [MyStruct]>;
+/// kernel::io::io_write!(mmio, [try: 2].field, 10);
+/// # Ok::<(), Error>(()) }
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! io_write {
+ (@parse [$io:expr] [$($proj:tt)*] [, $val:expr]) => {
+ $crate::io::Io::write_val($crate::io_project!($io, $($proj)*), $val)
+ };
+ (@parse [$io:expr] [$($proj:tt)*] [.$field:tt $($rest:tt)*]) => {
+ $crate::io_write!(@parse [$io] [$($proj)* .$field] [$($rest)*])
+ };
+ (@parse [$io:expr] [$($proj:tt)*] [[$flavor:ident: $index:expr] $($rest:tt)*]) => {
+ $crate::io_write!(@parse [$io] [$($proj)* [$flavor: $index]] [$($rest)*])
+ };
+ ($io:expr, $($rest:tt)*) => {
+ $crate::io_write!(@parse [$io] [] [$($rest)*])
+ };
+}
+#[doc(inline)]
+pub use crate::io_write;
--
2.54.0
^ permalink raw reply related
* [PATCH v5 07/20] rust: io: implement `Mmio` as view type
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Implement `Mmio` as view type and convert `RelaxedMmio` to view type as
well. I/O implementations of `MmioOwned` are changed to delegate to the
`Mmio` view type.
All existing users of `MmioOwned` in the documentation which do not
actually reflect the owning semantics is converted.
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/io.rs | 176 ++++++++++++++++++++++++++++++++++-----------
rust/kernel/io/poll.rs | 10 +--
rust/kernel/io/register.rs | 24 +++----
3 files changed, 153 insertions(+), 57 deletions(-)
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index f93be7f78069..8110b49aa430 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -4,6 +4,10 @@
//!
//! C header: [`include/asm-generic/io.h`](srctree/include/asm-generic/io.h)
+use core::{
+ marker::PhantomData, //
+};
+
use crate::{
bindings,
prelude::*,
@@ -537,10 +541,11 @@ fn write64(self, value: u64, offset: usize)
/// ```no_run
/// use kernel::io::{
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// };
///
- /// fn do_reads(io: &MmioOwned) -> Result {
+ /// fn do_reads(io: Mmio<'_, Region>) -> Result {
/// // 32-bit read from address `0x10`.
/// let v: u32 = io.try_read(0x10)?;
///
@@ -571,10 +576,11 @@ fn try_read<T, L>(self, location: L) -> Result<T>
/// ```no_run
/// use kernel::io::{
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// };
///
- /// fn do_writes(io: &MmioOwned) -> Result {
+ /// fn do_writes(io: Mmio<'_, Region>) -> Result {
/// // 32-bit write of value `1` at address `0x10`.
/// io.try_write(0x10, 1u32)?;
///
@@ -609,7 +615,8 @@ fn try_write<T, L>(self, location: L, value: T) -> Result
/// use kernel::io::{
/// register,
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// };
///
/// register! {
@@ -625,7 +632,7 @@ fn try_write<T, L>(self, location: L, value: T) -> Result
/// }
/// }
///
- /// fn do_write_reg(io: &MmioOwned) -> Result {
+ /// fn do_write_reg(io: Mmio<'_, Region>) -> Result {
///
/// io.try_write_reg(VERSION::new(1, 0))
/// }
@@ -654,10 +661,11 @@ fn try_write_reg<T, L, V>(self, value: V) -> Result
/// ```no_run
/// use kernel::io::{
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// };
///
- /// fn do_update(io: &MmioOwned<0x1000>) -> Result {
+ /// fn do_update(io: Mmio<'_, Region<0x1000>>) -> Result {
/// io.try_update(0x10, |v: u32| {
/// v + 1
/// })
@@ -691,10 +699,11 @@ fn try_update<T, L, F>(self, location: L, f: F) -> Result
/// ```no_run
/// use kernel::io::{
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// };
///
- /// fn do_reads(io: &MmioOwned<0x1000>) {
+ /// fn do_reads(io: Mmio<'_, Region<0x1000>>) {
/// // 32-bit read from address `0x10`.
/// let v: u32 = io.read(0x10);
///
@@ -723,10 +732,11 @@ fn read<T, L>(self, location: L) -> T
/// ```no_run
/// use kernel::io::{
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// };
///
- /// fn do_writes(io: &MmioOwned<0x1000>) {
+ /// fn do_writes(io: Mmio<'_, Region<0x1000>>) {
/// // 32-bit write of value `1` at address `0x10`.
/// io.write(0x10, 1u32);
///
@@ -757,7 +767,8 @@ fn write<T, L>(self, location: L, value: T)
/// use kernel::io::{
/// register,
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// };
///
/// register! {
@@ -773,7 +784,7 @@ fn write<T, L>(self, location: L, value: T)
/// }
/// }
///
- /// fn do_write_reg(io: &MmioOwned<0x1000>) {
+ /// fn do_write_reg(io: Mmio<'_, Region<0x1000>>) {
/// io.write_reg(VERSION::new(1, 0));
/// }
/// ```
@@ -801,10 +812,11 @@ fn write_reg<T, L, V>(self, value: V)
/// ```no_run
/// use kernel::io::{
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// };
///
- /// fn do_update(io: &MmioOwned<0x1000>) {
+ /// fn do_update(io: Mmio<'_, Region<0x1000>>) {
/// io.update(0x10, |v: u32| {
/// v + 1
/// })
@@ -828,16 +840,72 @@ fn update<T, L, F>(self, location: L, f: F)
}
}
+/// A view of memory-mapped I/O region.
+///
+/// # Invariant
+///
+/// `ptr` points to a valid and aligned memory-mapped I/O region for the duration lifetime `'a`.
+pub struct Mmio<'a, T: ?Sized> {
+ ptr: *mut T,
+ phantom: PhantomData<&'a ()>,
+}
+
+impl<T: ?Sized> Copy for Mmio<'_, T> {}
+impl<T: ?Sized> Clone for Mmio<'_, T> {
+ #[inline]
+ fn clone(&self) -> Self {
+ *self
+ }
+}
+
+impl<'a, T: ?Sized> Mmio<'a, T> {
+ /// Create a `Mmio`, providing the accessors to the MMIO mapping.
+ ///
+ /// # Safety
+ ///
+ /// `raw` represents a valid and aligned memory-mapped I/O region while `'a` is alive.
+ #[inline]
+ pub unsafe fn from_raw(raw: MmioRaw<T>) -> Self {
+ // INVARIANT: Per safety requirement.
+ Self {
+ ptr: raw.ptr,
+ phantom: PhantomData,
+ }
+ }
+}
+
+// SAFETY: `Mmio<'_, T>` is conceptually `&T` but in I/O memory.
+unsafe impl<T: ?Sized + Sync> Send for Mmio<'_, T> {}
+
+// SAFETY: `Mmio<'_, T>` is conceptually `&T` but in I/O memory.
+unsafe impl<T: ?Sized + Sync> Sync for Mmio<'_, T> {}
+
+impl<T: ?Sized + KnownSize> Io for Mmio<'_, T> {
+ type Target = T;
+
+ #[inline]
+ fn addr(self) -> usize {
+ self.ptr.addr()
+ }
+
+ #[inline]
+ fn maxsize(self) -> usize {
+ KnownSize::size(self.ptr)
+ }
+}
+
/// Implements [`IoCapable`] on `$mmio` for `$ty` using `$read_fn` and `$write_fn`.
macro_rules! impl_mmio_io_capable {
($mmio:ident, $(#[$attr:meta])* $ty:ty, $read_fn:ident, $write_fn:ident) => {
$(#[$attr])*
- impl<const SIZE: usize> IoCapable<$ty> for &$mmio<SIZE> {
+ impl<T: ?Sized> IoCapable<$ty> for $mmio<'_, T> {
+ #[inline]
unsafe fn io_read(self, address: usize) -> $ty {
// SAFETY: By the trait invariant `address` is a valid address for MMIO operations.
unsafe { bindings::$read_fn(address as *const c_void) }
}
+ #[inline]
unsafe fn io_write(self, value: $ty, address: usize) {
// SAFETY: By the trait invariant `address` is a valid address for MMIO operations.
unsafe { bindings::$write_fn(value, address as *mut c_void) }
@@ -847,17 +915,12 @@ unsafe fn io_write(self, value: $ty, address: usize) {
}
// MMIO regions support 8, 16, and 32-bit accesses.
-impl_mmio_io_capable!(MmioOwned, u8, readb, writeb);
-impl_mmio_io_capable!(MmioOwned, u16, readw, writew);
-impl_mmio_io_capable!(MmioOwned, u32, readl, writel);
+impl_mmio_io_capable!(Mmio, u8, readb, writeb);
+impl_mmio_io_capable!(Mmio, u16, readw, writew);
+impl_mmio_io_capable!(Mmio, u32, readl, writel);
// MMIO regions on 64-bit systems also support 64-bit accesses.
-impl_mmio_io_capable!(
- MmioOwned,
- #[cfg(CONFIG_64BIT)]
- u64,
- readq,
- writeq
-);
+#[cfg(CONFIG_64BIT)]
+impl_mmio_io_capable!(Mmio, u64, readq, writeq);
impl<'a, const SIZE: usize> Io for &'a MmioOwned<SIZE> {
type Target = Region<SIZE>;
@@ -875,6 +938,23 @@ fn maxsize(self) -> usize {
}
}
+impl<'a, const SIZE: usize, T> IoCapable<T> for &'a MmioOwned<SIZE>
+where
+ Mmio<'a, Region<SIZE>>: IoCapable<T>,
+{
+ #[inline]
+ unsafe fn io_read(self, address: usize) -> T {
+ // SAFETY: Per safety requirement.
+ unsafe { self.as_view().io_read(address) }
+ }
+
+ #[inline]
+ unsafe fn io_write(self, value: T, address: usize) {
+ // SAFETY: Per safety requirement.
+ unsafe { self.as_view().io_write(value, address) }
+ }
+}
+
impl<const SIZE: usize> MmioOwned<SIZE> {
/// Converts an `MmioRaw` into an `MmioOwned` instance, providing the accessors to the MMIO
/// mapping.
@@ -887,19 +967,33 @@ pub unsafe fn from_raw(raw: &MmioRaw<Region<SIZE>>) -> &Self {
// SAFETY: `MmioOwned` is a transparent wrapper around `MmioRaw`.
unsafe { &*core::ptr::from_ref(raw).cast() }
}
+
+ /// Return a view that covers the full region.
+ #[inline]
+ pub fn as_view(&self) -> Mmio<'_, Region<SIZE>> {
+ // SAFETY: `Mmio` has same invariant as `MmioOwned`.
+ unsafe { Mmio::from_raw(self.0) }
+ }
}
-/// [`MmioOwned`] wrapper using relaxed accessors.
+/// [`Mmio`] but using relaxed accessors.
///
/// This type provides an implementation of [`Io`] that uses relaxed I/O MMIO operands instead of
/// the regular ones.
///
-/// See [`MmioOwned::relaxed`] for a usage example.
-#[repr(transparent)]
-pub struct RelaxedMmio<const SIZE: usize = 0>(MmioOwned<SIZE>);
+/// See [`Mmio::relaxed`] for a usage example.
+pub struct RelaxedMmio<'a, T: ?Sized>(Mmio<'a, T>);
-impl<'a, const SIZE: usize> Io for &'a RelaxedMmio<SIZE> {
- type Target = Region<SIZE>;
+impl<T: ?Sized> Copy for RelaxedMmio<'_, T> {}
+impl<T: ?Sized> Clone for RelaxedMmio<'_, T> {
+ #[inline]
+ fn clone(&self) -> Self {
+ *self
+ }
+}
+
+impl<T: ?Sized + KnownSize> Io for RelaxedMmio<'_, T> {
+ type Target = T;
#[inline]
fn addr(self) -> usize {
@@ -912,8 +1006,8 @@ fn maxsize(self) -> usize {
}
}
-impl<const SIZE: usize> MmioOwned<SIZE> {
- /// Returns a [`RelaxedMmio`] reference that performs relaxed I/O operations.
+impl<'a, T: ?Sized> Mmio<'a, T> {
+ /// Returns a [`RelaxedMmio`] that performs relaxed I/O operations.
///
/// Relaxed accessors do not provide ordering guarantees with respect to DMA or memory accesses
/// and can be used when such ordering is not required.
@@ -923,20 +1017,20 @@ impl<const SIZE: usize> MmioOwned<SIZE> {
/// ```no_run
/// use kernel::io::{
/// Io,
- /// MmioOwned,
+ /// Mmio,
+ /// Region,
/// RelaxedMmio,
/// };
///
- /// fn do_io(io: &MmioOwned<0x100>) {
+ /// fn do_io(io: Mmio<'_, Region<0x100>>) {
/// // The access is performed using `readl_relaxed` instead of `readl`.
/// let v = io.relaxed().read32(0x10);
/// }
///
/// ```
- pub fn relaxed(&self) -> &RelaxedMmio<SIZE> {
- // SAFETY: `RelaxedMmio` is `#[repr(transparent)]` over `MmioOwned`, so `MmioOwned<SIZE>`
- // and `RelaxedMmio<SIZE>` have identical layout.
- unsafe { core::mem::transmute(self) }
+ #[inline]
+ pub fn relaxed(self) -> RelaxedMmio<'a, T> {
+ RelaxedMmio(self)
}
}
diff --git a/rust/kernel/io/poll.rs b/rust/kernel/io/poll.rs
index 79828a8006b5..d75f2fcf46f2 100644
--- a/rust/kernel/io/poll.rs
+++ b/rust/kernel/io/poll.rs
@@ -47,14 +47,15 @@
/// ```no_run
/// use kernel::io::{
/// Io,
-/// MmioOwned,
+/// Mmio,
+/// Region,
/// poll::read_poll_timeout, //
/// };
/// use kernel::time::Delta;
///
/// const HW_READY: u16 = 0x01;
///
-/// fn wait_for_hardware<const SIZE: usize>(io: &MmioOwned<SIZE>) -> Result {
+/// fn wait_for_hardware<const SIZE: usize>(io: Mmio<'_, Region<SIZE>>) -> Result {
/// read_poll_timeout(
/// // The `op` closure reads the value of a specific status register.
/// || io.try_read16(0x1000),
@@ -134,14 +135,15 @@ pub fn read_poll_timeout<Op, Cond, T>(
/// ```no_run
/// use kernel::io::{
/// Io,
-/// MmioOwned,
+/// Mmio,
+/// Region,
/// poll::read_poll_timeout_atomic, //
/// };
/// use kernel::time::Delta;
///
/// const HW_READY: u16 = 0x01;
///
-/// fn wait_for_hardware<const SIZE: usize>(io: &MmioOwned<SIZE>) -> Result {
+/// fn wait_for_hardware<const SIZE: usize>(io: Mmio<'_, Region<SIZE>>) -> Result {
/// read_poll_timeout_atomic(
/// // The `op` closure reads the value of a specific status register.
/// || io.try_read16(0x1000),
diff --git a/rust/kernel/io/register.rs b/rust/kernel/io/register.rs
index 43284d9fba96..80e638a892d7 100644
--- a/rust/kernel/io/register.rs
+++ b/rust/kernel/io/register.rs
@@ -58,7 +58,7 @@
//! },
//! num::Bounded,
//! };
-//! # use kernel::io::MmioOwned;
+//! # use kernel::io::{Mmio, Region};
//! # register! {
//! # pub BOOT_0(u32) @ 0x00000100 {
//! # 15:8 vendor_id;
@@ -66,7 +66,7 @@
//! # 3:0 minor_revision;
//! # }
//! # }
-//! # fn test(io: &MmioOwned<0x1000>) {
+//! # fn test(io: Mmio<'_, Region<0x1000>>) {
//! # fn obtain_vendor_id() -> u8 { 0xff }
//!
//! // Read from the register's defined offset (0x100).
@@ -446,7 +446,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// Io,
/// },
/// };
-/// # use kernel::io::MmioOwned;
+/// # use kernel::io::{Mmio, Region};
///
/// register! {
/// FIXED_REG(u32) @ 0x100 {
@@ -455,7 +455,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test(io: &MmioOwned<0x1000>) {
+/// # fn test(io: Mmio<'_, Region<0x1000>>) {
/// let val = io.read(FIXED_REG);
///
/// // Write from an already-existing value.
@@ -559,7 +559,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// Io,
/// },
/// };
-/// # use kernel::io::MmioOwned;
+/// # use kernel::io::{Mmio, Region};
///
/// // Type used to identify the base.
/// pub struct CpuCtlBase;
@@ -584,7 +584,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test(io: MmioOwned<0x1000>) {
+/// # fn test(io: Mmio<'_, Region<0x1000>>) {
/// // Read the status of `Cpu0`.
/// let cpu0_started = io.read(CPU_CTL::of::<Cpu0>());
///
@@ -601,7 +601,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test2(io: MmioOwned<0x1000>) {
+/// # fn test2(io: Mmio<'_, Region<0x1000>>) {
/// // Start the aliased `CPU0`, leaving its other fields untouched.
/// io.update(CPU_CTL_ALIAS::of::<Cpu0>(), |r| r.with_alias_start(true));
/// # }
@@ -638,7 +638,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// Io,
/// },
/// };
-/// # use kernel::io::MmioOwned;
+/// # use kernel::io::{Mmio, Region};
/// # fn get_scratch_idx() -> usize {
/// # 0x15
/// # }
@@ -651,7 +651,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test(io: &MmioOwned<0x1000>)
+/// # fn test(io: Mmio<'_, Region<0x1000>>)
/// # -> Result<(), Error>{
/// // Read scratch register 0, i.e. I/O address `0x80`.
/// let scratch_0 = io.read(SCRATCH::at(0)).value();
@@ -724,7 +724,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// Io,
/// },
/// };
-/// # use kernel::io::MmioOwned;
+/// # use kernel::io::{Mmio, Region};
/// # fn get_scratch_idx() -> usize {
/// # 0x15
/// # }
@@ -752,7 +752,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test(io: &MmioOwned<0x1000>) -> Result<(), Error> {
+/// # fn test(io: Mmio<'_, Region<0x1000>>) -> Result<(), Error> {
/// // Read scratch register 0 of CPU0.
/// let scratch = io.read(CPU_SCRATCH::of::<Cpu0>().at(0));
///
@@ -794,7 +794,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test2(io: &MmioOwned<0x1000>) -> Result<(), Error> {
+/// # fn test2(io: Mmio<'_, Region<0x1000>>) -> Result<(), Error> {
/// let cpu0_status = io.read(CPU_FIRMWARE_STATUS::of::<Cpu0>()).status();
/// # Ok(())
/// # }
--
2.54.0
^ permalink raw reply related
* [PATCH v5 15/20] rust: io: implement a view type for `Coherent`
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Implement a `CoherentView` type which is a view of `Coherent`. To be able
to give out DMA handles, the view type contains both CPU and DMA pointers,
and the projection method projects both at once.
Delegate most of the `Io` implementation to `SysMemBackend`. Provide a
method to erase the DMA handle and give out a `SysMem` view, if the user
does not need the `dma_handle`.
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/dma.rs | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 135 insertions(+), 2 deletions(-)
diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
index 200def84fb69..ab6504910e4f 100644
--- a/rust/kernel/dma.rs
+++ b/rust/kernel/dma.rs
@@ -14,14 +14,21 @@
},
error::to_result,
fs::file,
+ io::{
+ IoBackend,
+ IoBase,
+ IoCapable,
+ SysMem,
+ SysMemBackend, //
+ },
prelude::*,
ptr::KnownSize,
sync::aref::ARef,
transmute::{
AsBytes,
FromBytes, //
- }, //
- uaccess::UserSliceWriter,
+ },
+ uaccess::UserSliceWriter, //
};
use core::{
ops::{
@@ -1133,6 +1140,132 @@ unsafe impl Send for CoherentHandle {}
// plain `Copy` values.
unsafe impl Sync for CoherentHandle {}
+/// View type for `Coherent`.
+///
+/// This is same as [`SysMem`] but with additional information that allows handing out a DMA handle.
+pub struct CoherentView<'a, T: ?Sized> {
+ cpu_addr: SysMem<'a, T>,
+ dma_handle: DmaAddress,
+}
+
+impl<T: ?Sized> Copy for CoherentView<'_, T> {}
+impl<T: ?Sized> Clone for CoherentView<'_, T> {
+ #[inline]
+ fn clone(&self) -> Self {
+ *self
+ }
+}
+
+impl<'a, T: ?Sized> CoherentView<'a, T> {
+ /// Erase the DMA handle information and obtain a [`SysMem`] view of the same memory region.
+ #[inline]
+ pub fn as_sys_mem(self) -> SysMem<'a, T> {
+ self.cpu_addr
+ }
+
+ /// Returns a DMA handle which may be given to the device as the DMA address base of the region.
+ #[inline]
+ pub fn dma_handle(self) -> DmaAddress {
+ self.dma_handle
+ }
+
+ /// Returns a reference to the data in the region.
+ ///
+ /// # Safety
+ ///
+ /// * Callers must ensure that the device does not read/write to/from memory while the returned
+ /// reference is live.
+ /// * Callers must ensure that this call does not race with a write to the same region while
+ /// the returned reference is live.
+ #[inline]
+ pub unsafe fn as_ref(self) -> &'a T {
+ // SAFETY: pointer is aligned and valid per type invariant. Aliasing rule is satisfied per
+ // safety requirement.
+ unsafe { &*self.cpu_addr.as_ptr() }
+ }
+
+ /// Returns a mutable reference to the data in the region.
+ ///
+ /// # Safety
+ ///
+ /// * Callers must ensure that the device does not read/write to/from memory while the returned
+ /// reference is live.
+ /// * Callers must ensure that this call does not race with a read or write to the same region
+ /// while the returned reference is live.
+ #[inline]
+ pub unsafe fn as_mut(self) -> &'a mut T {
+ // SAFETY: pointer is aligned and valid per type invariant. Aliasing rule is satisfied per
+ // safety requirement.
+ unsafe { &mut *self.cpu_addr.as_ptr() }
+ }
+}
+
+/// `IoBackend` implementation for `Coherent`.
+pub struct CoherentBackend;
+
+impl IoBackend for CoherentBackend {
+ type View<'a, T: ?Sized + KnownSize> = CoherentView<'a, T>;
+
+ #[inline]
+ fn as_ptr<'a, T: ?Sized + KnownSize>(view: Self::View<'a, T>) -> *mut T {
+ SysMemBackend::as_ptr(view.cpu_addr)
+ }
+
+ #[inline]
+ unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>(
+ view: Self::View<'a, T>,
+ ptr: *mut U,
+ ) -> Self::View<'a, U> {
+ let offset = ptr.addr() - view.cpu_addr.as_ptr().addr();
+ // CAST: The offset DMA address can never overflow.
+ let dma_handle = view.dma_handle + offset as DmaAddress;
+ CoherentView {
+ dma_handle,
+ // SAFETY: Per safety requirement.
+ cpu_addr: unsafe { SysMemBackend::project_view(view.cpu_addr, ptr) },
+ }
+ }
+}
+
+impl<T> IoCapable<T> for CoherentBackend
+where
+ SysMemBackend: IoCapable<T>,
+{
+ #[inline]
+ fn io_read<'a>(view: Self::View<'a, T>) -> T {
+ SysMemBackend::io_read(view.cpu_addr)
+ }
+
+ #[inline]
+ fn io_write<'a>(view: Self::View<'a, T>, value: T) {
+ SysMemBackend::io_write(view.cpu_addr, value)
+ }
+}
+
+impl<'a, T: ?Sized + KnownSize> IoBase<'a> for CoherentView<'a, T> {
+ type Backend = CoherentBackend;
+ type Target = T;
+
+ #[inline]
+ fn as_view(self) -> CoherentView<'a, Self::Target> {
+ self
+ }
+}
+
+impl<'a, T: ?Sized + KnownSize> IoBase<'a> for &'a Coherent<T> {
+ type Backend = CoherentBackend;
+ type Target = T;
+
+ #[inline]
+ fn as_view(self) -> CoherentView<'a, Self::Target> {
+ CoherentView {
+ // SAFETY: `cpu_addr` is valid and aligned kernel accessible memory.
+ cpu_addr: unsafe { SysMem::new(self.cpu_addr.as_ptr()) },
+ dma_handle: self.dma_handle,
+ }
+ }
+}
+
/// Reads a field of an item from an allocated region of structs.
///
/// The syntax is of the form `kernel::dma_read!(dma, proj)` where `dma` is an expression evaluating
--
2.54.0
^ permalink raw reply related
* [PATCH v5 06/20] rust: io: rename `Mmio` to `MmioOwned`
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Most users would more commonly reach out to a view of `Mmio` rather than an
owned instance of `Mmio`. Only implementor of `Io` like `Bar` or `IoMem`
would need the owned version. Thus, rename `Mmio` to `MmioOwned` so that
the name `Mmio` can be used for the view type instead.
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/devres.rs | 6 ++--
rust/kernel/io.rs | 77 +++++++++++++++++++++++-----------------------
rust/kernel/io/mem.rs | 8 ++---
rust/kernel/io/poll.rs | 8 ++---
rust/kernel/io/register.rs | 24 +++++++--------
rust/kernel/pci/io.rs | 6 ++--
6 files changed, 65 insertions(+), 64 deletions(-)
diff --git a/rust/kernel/devres.rs b/rust/kernel/devres.rs
index d0c677fd7932..aed0c994fd30 100644
--- a/rust/kernel/devres.rs
+++ b/rust/kernel/devres.rs
@@ -68,7 +68,7 @@ struct Inner<T> {
/// devres::Devres,
/// io::{
/// Io,
-/// Mmio,
+/// MmioOwned,
/// MmioRaw,
/// PhysAddr,
/// Region, //
@@ -105,11 +105,11 @@ struct Inner<T> {
/// }
///
/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
-/// type Target = Mmio<SIZE>;
+/// type Target = MmioOwned<SIZE>;
///
/// fn deref(&self) -> &Self::Target {
/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
-/// unsafe { Mmio::from_raw(&self.0) }
+/// unsafe { MmioOwned::from_raw(&self.0) }
/// }
/// }
/// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> {
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 12be266d7ed7..f93be7f78069 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -94,8 +94,8 @@ fn size(p: *const Self) -> usize {
/// the represented MMIO region does exist or is properly mapped.
///
/// Instead, the bus specific MMIO implementation must convert this raw representation into an
-/// `Mmio` instance providing the actual memory accessors. Only by the conversion into an `Mmio`
-/// structure any guarantees are given.
+/// `MmioOwned` instance providing the actual memory accessors. Only by the conversion into an
+/// `MmioOwned` structure any guarantees are given.
pub struct MmioRaw<T: ?Sized> {
/// Pointer is in I/O address space.
///
@@ -170,7 +170,7 @@ pub fn size(&self) -> usize {
/// ffi::c_void,
/// io::{
/// Io,
-/// Mmio,
+/// MmioOwned,
/// MmioRaw,
/// PhysAddr,
/// Region,
@@ -206,11 +206,11 @@ pub fn size(&self) -> usize {
/// }
///
/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
-/// type Target = Mmio<SIZE>;
+/// type Target = MmioOwned<SIZE>;
///
/// fn deref(&self) -> &Self::Target {
/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
-/// unsafe { Mmio::from_raw(&self.0) }
+/// unsafe { MmioOwned::from_raw(&self.0) }
/// }
/// }
///
@@ -224,7 +224,7 @@ pub fn size(&self) -> usize {
/// # }
/// ```
#[repr(transparent)]
-pub struct Mmio<const SIZE: usize = 0>(MmioRaw<Region<SIZE>>);
+pub struct MmioOwned<const SIZE: usize = 0>(MmioRaw<Region<SIZE>>);
/// Checks whether an access of type `U` at the given `base` and the given `offset`
/// is valid within this region.
@@ -537,10 +537,10 @@ fn write64(self, value: u64, offset: usize)
/// ```no_run
/// use kernel::io::{
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// };
///
- /// fn do_reads(io: &Mmio) -> Result {
+ /// fn do_reads(io: &MmioOwned) -> Result {
/// // 32-bit read from address `0x10`.
/// let v: u32 = io.try_read(0x10)?;
///
@@ -571,10 +571,10 @@ fn try_read<T, L>(self, location: L) -> Result<T>
/// ```no_run
/// use kernel::io::{
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// };
///
- /// fn do_writes(io: &Mmio) -> Result {
+ /// fn do_writes(io: &MmioOwned) -> Result {
/// // 32-bit write of value `1` at address `0x10`.
/// io.try_write(0x10, 1u32)?;
///
@@ -609,7 +609,7 @@ fn try_write<T, L>(self, location: L, value: T) -> Result
/// use kernel::io::{
/// register,
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// };
///
/// register! {
@@ -625,7 +625,7 @@ fn try_write<T, L>(self, location: L, value: T) -> Result
/// }
/// }
///
- /// fn do_write_reg(io: &Mmio) -> Result {
+ /// fn do_write_reg(io: &MmioOwned) -> Result {
///
/// io.try_write_reg(VERSION::new(1, 0))
/// }
@@ -654,10 +654,10 @@ fn try_write_reg<T, L, V>(self, value: V) -> Result
/// ```no_run
/// use kernel::io::{
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// };
///
- /// fn do_update(io: &Mmio<0x1000>) -> Result {
+ /// fn do_update(io: &MmioOwned<0x1000>) -> Result {
/// io.try_update(0x10, |v: u32| {
/// v + 1
/// })
@@ -691,10 +691,10 @@ fn try_update<T, L, F>(self, location: L, f: F) -> Result
/// ```no_run
/// use kernel::io::{
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// };
///
- /// fn do_reads(io: &Mmio<0x1000>) {
+ /// fn do_reads(io: &MmioOwned<0x1000>) {
/// // 32-bit read from address `0x10`.
/// let v: u32 = io.read(0x10);
///
@@ -723,10 +723,10 @@ fn read<T, L>(self, location: L) -> T
/// ```no_run
/// use kernel::io::{
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// };
///
- /// fn do_writes(io: &Mmio<0x1000>) {
+ /// fn do_writes(io: &MmioOwned<0x1000>) {
/// // 32-bit write of value `1` at address `0x10`.
/// io.write(0x10, 1u32);
///
@@ -757,7 +757,7 @@ fn write<T, L>(self, location: L, value: T)
/// use kernel::io::{
/// register,
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// };
///
/// register! {
@@ -773,7 +773,7 @@ fn write<T, L>(self, location: L, value: T)
/// }
/// }
///
- /// fn do_write_reg(io: &Mmio<0x1000>) {
+ /// fn do_write_reg(io: &MmioOwned<0x1000>) {
/// io.write_reg(VERSION::new(1, 0));
/// }
/// ```
@@ -801,10 +801,10 @@ fn write_reg<T, L, V>(self, value: V)
/// ```no_run
/// use kernel::io::{
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// };
///
- /// fn do_update(io: &Mmio<0x1000>) {
+ /// fn do_update(io: &MmioOwned<0x1000>) {
/// io.update(0x10, |v: u32| {
/// v + 1
/// })
@@ -847,19 +847,19 @@ unsafe fn io_write(self, value: $ty, address: usize) {
}
// MMIO regions support 8, 16, and 32-bit accesses.
-impl_mmio_io_capable!(Mmio, u8, readb, writeb);
-impl_mmio_io_capable!(Mmio, u16, readw, writew);
-impl_mmio_io_capable!(Mmio, u32, readl, writel);
+impl_mmio_io_capable!(MmioOwned, u8, readb, writeb);
+impl_mmio_io_capable!(MmioOwned, u16, readw, writew);
+impl_mmio_io_capable!(MmioOwned, u32, readl, writel);
// MMIO regions on 64-bit systems also support 64-bit accesses.
impl_mmio_io_capable!(
- Mmio,
+ MmioOwned,
#[cfg(CONFIG_64BIT)]
u64,
readq,
writeq
);
-impl<'a, const SIZE: usize> Io for &'a Mmio<SIZE> {
+impl<'a, const SIZE: usize> Io for &'a MmioOwned<SIZE> {
type Target = Region<SIZE>;
/// Returns the base address of this mapping.
@@ -875,27 +875,28 @@ fn maxsize(self) -> usize {
}
}
-impl<const SIZE: usize> Mmio<SIZE> {
- /// Converts an `MmioRaw` into an `Mmio` instance, providing the accessors to the MMIO mapping.
+impl<const SIZE: usize> MmioOwned<SIZE> {
+ /// Converts an `MmioRaw` into an `MmioOwned` instance, providing the accessors to the MMIO
+ /// mapping.
///
/// # Safety
///
/// Callers must ensure that `addr` is the start of a valid I/O mapped memory region of size
/// `maxsize`.
pub unsafe fn from_raw(raw: &MmioRaw<Region<SIZE>>) -> &Self {
- // SAFETY: `Mmio` is a transparent wrapper around `MmioRaw`.
+ // SAFETY: `MmioOwned` is a transparent wrapper around `MmioRaw`.
unsafe { &*core::ptr::from_ref(raw).cast() }
}
}
-/// [`Mmio`] wrapper using relaxed accessors.
+/// [`MmioOwned`] wrapper using relaxed accessors.
///
/// This type provides an implementation of [`Io`] that uses relaxed I/O MMIO operands instead of
/// the regular ones.
///
-/// See [`Mmio::relaxed`] for a usage example.
+/// See [`MmioOwned::relaxed`] for a usage example.
#[repr(transparent)]
-pub struct RelaxedMmio<const SIZE: usize = 0>(Mmio<SIZE>);
+pub struct RelaxedMmio<const SIZE: usize = 0>(MmioOwned<SIZE>);
impl<'a, const SIZE: usize> Io for &'a RelaxedMmio<SIZE> {
type Target = Region<SIZE>;
@@ -911,7 +912,7 @@ fn maxsize(self) -> usize {
}
}
-impl<const SIZE: usize> Mmio<SIZE> {
+impl<const SIZE: usize> MmioOwned<SIZE> {
/// Returns a [`RelaxedMmio`] reference that performs relaxed I/O operations.
///
/// Relaxed accessors do not provide ordering guarantees with respect to DMA or memory accesses
@@ -922,19 +923,19 @@ impl<const SIZE: usize> Mmio<SIZE> {
/// ```no_run
/// use kernel::io::{
/// Io,
- /// Mmio,
+ /// MmioOwned,
/// RelaxedMmio,
/// };
///
- /// fn do_io(io: &Mmio<0x100>) {
+ /// fn do_io(io: &MmioOwned<0x100>) {
/// // The access is performed using `readl_relaxed` instead of `readl`.
/// let v = io.relaxed().read32(0x10);
/// }
///
/// ```
pub fn relaxed(&self) -> &RelaxedMmio<SIZE> {
- // SAFETY: `RelaxedMmio` is `#[repr(transparent)]` over `Mmio`, so `Mmio<SIZE>` and
- // `RelaxedMmio<SIZE>` have identical layout.
+ // SAFETY: `RelaxedMmio` is `#[repr(transparent)]` over `MmioOwned`, so `MmioOwned<SIZE>`
+ // and `RelaxedMmio<SIZE>` have identical layout.
unsafe { core::mem::transmute(self) }
}
}
diff --git a/rust/kernel/io/mem.rs b/rust/kernel/io/mem.rs
index 9e15bc8fde78..8f6c257c5b8e 100644
--- a/rust/kernel/io/mem.rs
+++ b/rust/kernel/io/mem.rs
@@ -16,7 +16,7 @@
Region,
Resource, //
},
- Mmio,
+ MmioOwned,
MmioRaw, //
},
prelude::*,
@@ -211,7 +211,7 @@ pub fn into_devres(self) -> Result<Devres<ExclusiveIoMem<'static, SIZE>>> {
}
impl<const SIZE: usize> Deref for ExclusiveIoMem<'_, SIZE> {
- type Target = Mmio<SIZE>;
+ type Target = MmioOwned<SIZE>;
fn deref(&self) -> &Self::Target {
&self.iomem
@@ -291,10 +291,10 @@ fn drop(&mut self) {
}
impl<const SIZE: usize> Deref for IoMem<'_, SIZE> {
- type Target = Mmio<SIZE>;
+ type Target = MmioOwned<SIZE>;
fn deref(&self) -> &Self::Target {
// SAFETY: Safe as by the invariant of `IoMem`.
- unsafe { Mmio::from_raw(&self.io) }
+ unsafe { MmioOwned::from_raw(&self.io) }
}
}
diff --git a/rust/kernel/io/poll.rs b/rust/kernel/io/poll.rs
index 75d1b3e8596c..79828a8006b5 100644
--- a/rust/kernel/io/poll.rs
+++ b/rust/kernel/io/poll.rs
@@ -47,14 +47,14 @@
/// ```no_run
/// use kernel::io::{
/// Io,
-/// Mmio,
+/// MmioOwned,
/// poll::read_poll_timeout, //
/// };
/// use kernel::time::Delta;
///
/// const HW_READY: u16 = 0x01;
///
-/// fn wait_for_hardware<const SIZE: usize>(io: &Mmio<SIZE>) -> Result {
+/// fn wait_for_hardware<const SIZE: usize>(io: &MmioOwned<SIZE>) -> Result {
/// read_poll_timeout(
/// // The `op` closure reads the value of a specific status register.
/// || io.try_read16(0x1000),
@@ -134,14 +134,14 @@ pub fn read_poll_timeout<Op, Cond, T>(
/// ```no_run
/// use kernel::io::{
/// Io,
-/// Mmio,
+/// MmioOwned,
/// poll::read_poll_timeout_atomic, //
/// };
/// use kernel::time::Delta;
///
/// const HW_READY: u16 = 0x01;
///
-/// fn wait_for_hardware<const SIZE: usize>(io: &Mmio<SIZE>) -> Result {
+/// fn wait_for_hardware<const SIZE: usize>(io: &MmioOwned<SIZE>) -> Result {
/// read_poll_timeout_atomic(
/// // The `op` closure reads the value of a specific status register.
/// || io.try_read16(0x1000),
diff --git a/rust/kernel/io/register.rs b/rust/kernel/io/register.rs
index 3122b17098ee..43284d9fba96 100644
--- a/rust/kernel/io/register.rs
+++ b/rust/kernel/io/register.rs
@@ -58,7 +58,7 @@
//! },
//! num::Bounded,
//! };
-//! # use kernel::io::Mmio;
+//! # use kernel::io::MmioOwned;
//! # register! {
//! # pub BOOT_0(u32) @ 0x00000100 {
//! # 15:8 vendor_id;
@@ -66,7 +66,7 @@
//! # 3:0 minor_revision;
//! # }
//! # }
-//! # fn test(io: &Mmio<0x1000>) {
+//! # fn test(io: &MmioOwned<0x1000>) {
//! # fn obtain_vendor_id() -> u8 { 0xff }
//!
//! // Read from the register's defined offset (0x100).
@@ -446,7 +446,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// Io,
/// },
/// };
-/// # use kernel::io::Mmio;
+/// # use kernel::io::MmioOwned;
///
/// register! {
/// FIXED_REG(u32) @ 0x100 {
@@ -455,7 +455,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test(io: &Mmio<0x1000>) {
+/// # fn test(io: &MmioOwned<0x1000>) {
/// let val = io.read(FIXED_REG);
///
/// // Write from an already-existing value.
@@ -559,7 +559,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// Io,
/// },
/// };
-/// # use kernel::io::Mmio;
+/// # use kernel::io::MmioOwned;
///
/// // Type used to identify the base.
/// pub struct CpuCtlBase;
@@ -584,7 +584,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test(io: Mmio<0x1000>) {
+/// # fn test(io: MmioOwned<0x1000>) {
/// // Read the status of `Cpu0`.
/// let cpu0_started = io.read(CPU_CTL::of::<Cpu0>());
///
@@ -601,7 +601,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test2(io: Mmio<0x1000>) {
+/// # fn test2(io: MmioOwned<0x1000>) {
/// // Start the aliased `CPU0`, leaving its other fields untouched.
/// io.update(CPU_CTL_ALIAS::of::<Cpu0>(), |r| r.with_alias_start(true));
/// # }
@@ -638,7 +638,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// Io,
/// },
/// };
-/// # use kernel::io::Mmio;
+/// # use kernel::io::MmioOwned;
/// # fn get_scratch_idx() -> usize {
/// # 0x15
/// # }
@@ -651,7 +651,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test(io: &Mmio<0x1000>)
+/// # fn test(io: &MmioOwned<0x1000>)
/// # -> Result<(), Error>{
/// // Read scratch register 0, i.e. I/O address `0x80`.
/// let scratch_0 = io.read(SCRATCH::at(0)).value();
@@ -724,7 +724,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// Io,
/// },
/// };
-/// # use kernel::io::Mmio;
+/// # use kernel::io::MmioOwned;
/// # fn get_scratch_idx() -> usize {
/// # 0x15
/// # }
@@ -752,7 +752,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test(io: &Mmio<0x1000>) -> Result<(), Error> {
+/// # fn test(io: &MmioOwned<0x1000>) -> Result<(), Error> {
/// // Read scratch register 0 of CPU0.
/// let scratch = io.read(CPU_SCRATCH::of::<Cpu0>().at(0));
///
@@ -794,7 +794,7 @@ fn into_io_op(self) -> (FixedRegisterLoc<T>, T) {
/// }
/// }
///
-/// # fn test2(io: &Mmio<0x1000>) -> Result<(), Error> {
+/// # fn test2(io: &MmioOwned<0x1000>) -> Result<(), Error> {
/// let cpu0_status = io.read(CPU_FIRMWARE_STATUS::of::<Cpu0>()).status();
/// # Ok(())
/// # }
diff --git a/rust/kernel/pci/io.rs b/rust/kernel/pci/io.rs
index 42f840d64a6f..e0acb62f58a2 100644
--- a/rust/kernel/pci/io.rs
+++ b/rust/kernel/pci/io.rs
@@ -10,7 +10,7 @@
io::{
Io,
IoCapable,
- Mmio,
+ MmioOwned,
MmioRaw,
Region, //
},
@@ -242,11 +242,11 @@ fn drop(&mut self) {
}
impl<const SIZE: usize> Deref for Bar<'_, SIZE> {
- type Target = Mmio<SIZE>;
+ type Target = MmioOwned<SIZE>;
fn deref(&self) -> &Self::Target {
// SAFETY: By the type invariant of `Self`, the MMIO range in `self.io` is properly mapped.
- unsafe { Mmio::from_raw(&self.io) }
+ unsafe { MmioOwned::from_raw(&self.io) }
}
}
--
2.54.0
^ permalink raw reply related
* [PATCH v5 14/20] rust: io: add I/O backend for system memory with volatile access
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm, Laura Nao
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
From: Laura Nao <laura.nao@collabora.com>
Add `SysMem`, an `Io` trait implementation for kernel virtual address
ranges. It uses volatile accessors to provide safe access to shared
memory that may be concurrently accessed by external hardware. Implement
`IoCapable` for `u8`, `u16`, `u32`, and `u64` (for 64-bit system).
This can be used for instead of `Coherent` for cases where a different
layer takes care of mapping the system memory to the device (e.g. dma-buf
or GPUVM).
Signed-off-by: Laura Nao <laura.nao@collabora.com>
[ Rebased and adapted on top of I/O rework. - Gary ]
Co-developed-by: Gary Guo <gary@garyguo.net>
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/io.rs | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 122 insertions(+)
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 96962498af77..5c06785facea 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -1034,6 +1034,128 @@ pub fn relaxed(self) -> RelaxedMmio<'a, T> {
#[cfg(CONFIG_64BIT)]
impl_mmio_io_capable!(RelaxedMmioBackend, u64, readq_relaxed, writeq_relaxed);
+/// I/O Backend for system memory.
+pub struct SysMemBackend;
+
+impl IoBackend for SysMemBackend {
+ type View<'a, T: ?Sized + KnownSize> = SysMem<'a, T>;
+
+ #[inline]
+ fn as_ptr<'a, T: ?Sized + KnownSize>(view: Self::View<'a, T>) -> *mut T {
+ view.ptr
+ }
+
+ #[inline]
+ unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>(
+ _view: Self::View<'a, T>,
+ ptr: *mut U,
+ ) -> Self::View<'a, U> {
+ // INVARIANT: Per safety requirement, `ptr` is projection from `view`, so it is also a valid
+ // kernel accessible memory region.
+ SysMem {
+ ptr,
+ phantom: PhantomData,
+ }
+ }
+}
+
+/// Implements [`IoCapable`] on `SysMemBackend` for `$ty` using `read_volatile` and
+/// `write_volatile`.
+macro_rules! impl_sysmem_io_capable {
+ ($ty:ty) => {
+ impl IoCapable<$ty> for SysMemBackend {
+ #[inline]
+ fn io_read(view: SysMem<'_, $ty>) -> $ty {
+ // SAFETY:
+ // - Per type invariant, `ptr` is valid and aligned.
+ // - Using read_volatile() here so that race with hardware is well-defined.
+ // - Using read_volatile() here is not sound if it races with other CPU per Rust
+ // rules, but this is allowed per LKMM.
+ // - The macro is only used on primitives so all bit patterns are valid.
+ unsafe { view.ptr.read_volatile() }
+ }
+
+ #[inline]
+ fn io_write(view: SysMem<'_, $ty>, value: $ty) {
+ // SAFETY:
+ // - Per type invariant, `ptr` is valid and aligned.
+ // - Using write_volatile() here so that race with hardware is well-defined.
+ // - Using write_volatile() here is not sound if it races with other CPU per Rust
+ // rules, but this is allowed per LKMM.
+ unsafe { view.ptr.write_volatile(value) }
+ }
+ }
+ };
+}
+
+impl_sysmem_io_capable!(u8);
+impl_sysmem_io_capable!(u16);
+impl_sysmem_io_capable!(u32);
+#[cfg(CONFIG_64BIT)]
+impl_sysmem_io_capable!(u64);
+
+/// System memory region.
+///
+/// Provides `Io` trait implementation for kernel virtual address ranges,
+/// using volatile read/write to safely access shared memory that may be
+/// concurrently accessed by external hardware.
+///
+/// # Invariants
+///
+/// `self.ptr.addr() .. self.ptr.addr() + KnownSize::size(self.ptr)` is valid and aligned kernel
+/// accessible memory region for the lifetime `'a`.
+pub struct SysMem<'a, T: ?Sized> {
+ ptr: *mut T,
+ phantom: PhantomData<&'a ()>,
+}
+
+impl<T: ?Sized> Copy for SysMem<'_, T> {}
+impl<T: ?Sized> Clone for SysMem<'_, T> {
+ #[inline]
+ fn clone(&self) -> Self {
+ *self
+ }
+}
+
+// SAFETY: `SysMem<'_, T>` is conceptually `&T` but in I/O memory.
+unsafe impl<T: ?Sized + Sync> Send for SysMem<'_, T> {}
+
+// SAFETY: `SysMem<'_, T>` is conceptually `&T` but in I/O memory.
+unsafe impl<T: ?Sized + Sync> Sync for SysMem<'_, T> {}
+
+impl<'a, T: ?Sized> SysMem<'a, T> {
+ /// Create a `SysMem` from a raw pointer.
+ ///
+ /// # Safety
+ ///
+ /// `ptr.addr() .. ptr.addr() + KnownSize::size(ptr)` must be valid and aligned kernel
+ /// accessible memory region for the lifetime `'a`.
+ #[inline]
+ pub unsafe fn new(ptr: *mut T) -> Self {
+ // INVARIANT: Per safety requirement.
+ Self {
+ ptr,
+ phantom: PhantomData,
+ }
+ }
+
+ /// Obtain the raw pointer to the memory.
+ #[inline]
+ pub fn as_ptr(self) -> *mut T {
+ self.ptr
+ }
+}
+
+impl<'a, T: ?Sized + KnownSize> IoBase<'a> for SysMem<'a, T> {
+ type Backend = SysMemBackend;
+ type Target = T;
+
+ #[inline]
+ fn as_view(self) -> <Self::Backend as IoBackend>::View<'a, Self::Target> {
+ self
+ }
+}
+
// This helper turns associated functions to methods so it can be invoked in macro.
// Used by `io_project!()` only.
#[doc(hidden)]
--
2.54.0
^ permalink raw reply related
* [PATCH v5 13/20] rust: io: add projection macro and methods
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Add an `io_project!()` macro allows projection from `Io` to a subview of
it, using the pointer projection mechanism to perform compile-time checks.
For cases where type-casting is required, the `try_cast()` function may be
used where the size and alignment checks are performed at runtime.
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/io.rs | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 124 insertions(+)
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 0746b0d209ef..96962498af77 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -49,6 +49,7 @@
/// - Size of the region is at least as large as the `SIZE` generic parameter.
/// - Size of the region is multiple of 4.
#[repr(C, align(4))]
+#[derive(FromBytes)]
pub struct Region<const SIZE: usize = 0> {
inner: [u8],
}
@@ -90,6 +91,16 @@ fn size(p: *const Self) -> usize {
}
}
+// SAFETY: Values read from I/O are always treated as initialized.
+//
+// This cannot be derived as `derive(IntoBytes)` does not know that this type is padding free (given
+// `repr(align(4))`).
+unsafe impl<const SIZE: usize> IntoBytes for Region<SIZE> {
+ #[inline]
+ #[allow(unused)] // Rust 1.87+ stops requiring this and will emit unused warnings.
+ fn only_derive_is_allowed_to_implement_this_trait() {}
+}
+
/// Raw representation of an MMIO region.
///
/// `MmioRaw<T>` is equivalent to `T __iomem *` in C.
@@ -339,6 +350,49 @@ fn size(self) -> usize {
KnownSize::size(Self::Backend::as_ptr(self.as_view()))
}
+ /// Try to convert into a different typed I/O view.
+ ///
+ /// The target type must be of same or smaller size to current type, and the current view must
+ /// be properly aligned for the target type.
+ ///
+ /// # Examples
+ ///
+ /// ```no_run
+ /// use kernel::io::{
+ /// io_project,
+ /// Mmio,
+ /// Io,
+ /// Region,
+ /// };
+ /// #[derive(FromBytes, IntoBytes)]
+ /// struct MyStruct { field: u32, }
+ ///
+ /// # fn test(mmio: &Mmio<'_, Region>) -> Result {
+ /// // let mmio: Mmio<'_, Region>;
+ /// let whole: Mmio<'_, MyStruct> = mmio.try_cast()?;
+ /// # Ok::<(), Error>(()) }
+ /// ```
+ #[inline]
+ fn try_cast<U>(self) -> Result<<Self::Backend as IoBackend>::View<'a, U>>
+ where
+ Self::Target: FromBytes + IntoBytes,
+ U: FromBytes + IntoBytes,
+ {
+ let view = self.as_view();
+ let ptr = Self::Backend::as_ptr(view);
+
+ if size_of::<U>() > KnownSize::size(ptr) {
+ return Err(EINVAL);
+ }
+
+ if ptr.addr() % align_of::<U>() != 0 {
+ return Err(EINVAL);
+ }
+
+ // SAFETY: We have checked bounds and alignment, so this is a valid projection.
+ Ok(unsafe { Self::Backend::project_view(view, ptr.cast()) })
+ }
+
/// Fallible 8-bit read with runtime bounds check.
#[inline(always)]
fn try_read8(self, offset: usize) -> Result<u8>
@@ -979,3 +1033,73 @@ pub fn relaxed(self) -> RelaxedMmio<'a, T> {
// MMIO regions on 64-bit systems also support 64-bit accesses.
#[cfg(CONFIG_64BIT)]
impl_mmio_io_capable!(RelaxedMmioBackend, u64, readq_relaxed, writeq_relaxed);
+
+// This helper turns associated functions to methods so it can be invoked in macro.
+// Used by `io_project!()` only.
+#[doc(hidden)]
+#[derive(Clone, Copy)]
+pub struct ProjectHelper<T>(pub T);
+
+impl<'a, T> ProjectHelper<T>
+where
+ T: Io<'a, Backend: IoBackend<View<'a, T::Target> = T>>,
+{
+ // These helper methods must not have symbols present in binary to avoid confusion.
+ #[inline(always)]
+ pub fn as_ptr(self) -> *mut T::Target {
+ T::Backend::as_ptr(self.0)
+ }
+
+ /// # Safety
+ ///
+ /// Same as `IoBackend::project_view`
+ #[inline(always)]
+ pub unsafe fn project_view<U: ?Sized + KnownSize>(
+ self,
+ ptr: *mut U,
+ ) -> <T::Backend as IoBackend>::View<'a, U> {
+ // SAFETY: Per safety requirement.
+ unsafe { T::Backend::project_view::<T::Target, _>(self.0, ptr) }
+ }
+}
+
+/// Project an I/O type to a subview of it.
+///
+/// The syntax is of form `io_project!(io, proj)` where `io` is an expression to a type that
+/// implements [`Io`] and `proj` is a [projection specification](kernel::ptr::project!).
+///
+/// In addition to projecting from [`Io`], you may also project from a [`View`] of an [`Io`].
+///
+/// # Examples
+///
+/// ```
+/// use kernel::io::{
+/// io_project,
+/// Mmio,
+/// };
+/// struct MyStruct { field: u32, }
+///
+/// # fn test(mmio: Mmio<'_, [MyStruct]>) -> Result {
+/// // let mmio: Mmio<[MyStruct]>;
+/// let field: Mmio<'_, u32> = io_project!(mmio, [try: 1].field);
+/// let whole: Mmio<'_, MyStruct> = io_project!(mmio, [try: 2]);
+/// let nested: Mmio<'_, u32> = io_project!(whole, .field);
+/// # Ok::<(), Error>(()) }
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! io_project {
+ ($io:expr, $($proj:tt)*) => {{
+ #[allow(unused)]
+ use $crate::io::IoBase as _;
+ let view = $crate::io::ProjectHelper($io.as_view());
+ let ptr = $crate::ptr::project!(
+ mut view.as_ptr(), $($proj)*
+ );
+ #[allow(unused_unsafe)]
+ // SAFETY: `ptr` is a projection.
+ unsafe { view.project_view(ptr) }
+ }};
+}
+#[doc(inline)]
+pub use crate::io_project;
--
2.54.0
^ permalink raw reply related
* [PATCH v5 11/20] rust: io: remove `MmioOwned`
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
`Io` trait is now very easy to implement. Thus, implement it on `Bar` and
`IoMem` directly and remove the `MmioOwned` struct.
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/devres.rs | 12 +++---
rust/kernel/io.rs | 103 +-------------------------------------------------
rust/kernel/io/mem.rs | 26 +++++++------
rust/kernel/pci/io.rs | 16 ++++----
4 files changed, 32 insertions(+), 125 deletions(-)
diff --git a/rust/kernel/devres.rs b/rust/kernel/devres.rs
index aed0c994fd30..3545ffc5345d 100644
--- a/rust/kernel/devres.rs
+++ b/rust/kernel/devres.rs
@@ -68,8 +68,9 @@ struct Inner<T> {
/// devres::Devres,
/// io::{
/// Io,
-/// MmioOwned,
+/// Mmio,
/// MmioRaw,
+/// MmioBackend,
/// PhysAddr,
/// Region, //
/// },
@@ -104,12 +105,13 @@ struct Inner<T> {
/// }
/// }
///
-/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
-/// type Target = MmioOwned<SIZE>;
+/// impl<'a, const SIZE: usize> Io<'a> for &'a IoMem<SIZE> {
+/// type Backend = MmioBackend;
+/// type Target = Region<SIZE>;
///
-/// fn deref(&self) -> &Self::Target {
+/// fn as_view(self) -> Mmio<'a, Region<SIZE>> {
/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
-/// unsafe { MmioOwned::from_raw(&self.0) }
+/// unsafe { Mmio::from_raw(self.0) }
/// }
/// }
/// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> {
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 67b8c62f3771..adafd273920f 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -98,8 +98,8 @@ fn size(p: *const Self) -> usize {
/// the represented MMIO region does exist or is properly mapped.
///
/// Instead, the bus specific MMIO implementation must convert this raw representation into an
-/// `MmioOwned` instance providing the actual memory accessors. Only by the conversion into an
-/// `MmioOwned` structure any guarantees are given.
+/// `Mmio` instance providing the actual memory accessors. Only by the conversion into an `Mmio`
+/// structure any guarantees are given.
pub struct MmioRaw<T: ?Sized> {
/// Pointer is in I/O address space.
///
@@ -156,80 +156,6 @@ pub fn size(&self) -> usize {
}
}
-/// IO-mapped memory region.
-///
-/// The creator (usually a subsystem / bus such as PCI) is responsible for creating the
-/// mapping, performing an additional region request etc.
-///
-/// # Invariant
-///
-/// `addr` is the start and `maxsize` the length of valid I/O mapped memory region of size
-/// `maxsize`.
-///
-/// # Examples
-///
-/// ```no_run
-/// use kernel::{
-/// bindings,
-/// ffi::c_void,
-/// io::{
-/// Io,
-/// MmioOwned,
-/// MmioRaw,
-/// PhysAddr,
-/// Region,
-/// },
-/// };
-/// use core::ops::Deref;
-///
-/// // See also `pci::Bar` for a real example.
-/// struct IoMem<const SIZE: usize>(MmioRaw<Region<SIZE>>);
-///
-/// impl<const SIZE: usize> IoMem<SIZE> {
-/// /// # Safety
-/// ///
-/// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs
-/// /// virtual address space.
-/// unsafe fn new(paddr: usize) -> Result<Self>{
-/// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is
-/// // valid for `ioremap`.
-/// let addr = unsafe { bindings::ioremap(paddr as PhysAddr, SIZE) };
-/// if addr.is_null() {
-/// return Err(ENOMEM);
-/// }
-///
-/// Ok(IoMem(MmioRaw::new_region(addr as usize, SIZE)?))
-/// }
-/// }
-///
-/// impl<const SIZE: usize> Drop for IoMem<SIZE> {
-/// fn drop(&mut self) {
-/// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`.
-/// unsafe { bindings::iounmap(self.0.addr() as *mut c_void); };
-/// }
-/// }
-///
-/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
-/// type Target = MmioOwned<SIZE>;
-///
-/// fn deref(&self) -> &Self::Target {
-/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
-/// unsafe { MmioOwned::from_raw(&self.0) }
-/// }
-/// }
-///
-///# fn no_run() -> Result<(), Error> {
-/// // SAFETY: Invalid usage for example purposes.
-/// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? };
-/// iomem.write32(0x42, 0x0);
-/// assert!(iomem.try_write32(0x42, 0x0).is_ok());
-/// assert!(iomem.try_write32(0x42, 0x4).is_err());
-/// # Ok(())
-/// # }
-/// ```
-#[repr(transparent)]
-pub struct MmioOwned<const SIZE: usize = 0>(MmioRaw<Region<SIZE>>);
-
/// Checks whether an access of type `U` at the given `base` and the given `offset`
/// is valid within this region.
///
@@ -957,31 +883,6 @@ fn io_write(view: <$backend as IoBackend>::View<'_, $ty>, value: $ty) {
#[cfg(CONFIG_64BIT)]
impl_mmio_io_capable!(MmioBackend, u64, readq, writeq);
-impl<'a, const SIZE: usize> Io<'a> for &'a MmioOwned<SIZE> {
- type Backend = MmioBackend;
- type Target = Region<SIZE>;
-
- #[inline]
- fn as_view(self) -> Mmio<'a, Self::Target> {
- // SAFETY: `Mmio` has same invariant as `MmioOwned`
- unsafe { Mmio::from_raw(self.0) }
- }
-}
-
-impl<const SIZE: usize> MmioOwned<SIZE> {
- /// Converts an `MmioRaw` into an `MmioOwned` instance, providing the accessors to the MMIO
- /// mapping.
- ///
- /// # Safety
- ///
- /// Callers must ensure that `addr` is the start of a valid I/O mapped memory region of size
- /// `maxsize`.
- pub unsafe fn from_raw(raw: &MmioRaw<Region<SIZE>>) -> &Self {
- // SAFETY: `MmioOwned` is a transparent wrapper around `MmioRaw`.
- unsafe { &*core::ptr::from_ref(raw).cast() }
- }
-}
-
/// [`Mmio`] but using relaxed accessors.
///
/// This type provides an implementation of [`Io`] that uses relaxed I/O MMIO operands instead of
diff --git a/rust/kernel/io/mem.rs b/rust/kernel/io/mem.rs
index 8f6c257c5b8e..d9b3189d09b4 100644
--- a/rust/kernel/io/mem.rs
+++ b/rust/kernel/io/mem.rs
@@ -2,8 +2,6 @@
//! Generic memory-mapped IO.
-use core::ops::Deref;
-
use crate::{
device::{
Bound,
@@ -16,7 +14,9 @@
Region,
Resource, //
},
- MmioOwned,
+ Io,
+ Mmio,
+ MmioBackend,
MmioRaw, //
},
prelude::*,
@@ -210,11 +210,13 @@ pub fn into_devres(self) -> Result<Devres<ExclusiveIoMem<'static, SIZE>>> {
}
}
-impl<const SIZE: usize> Deref for ExclusiveIoMem<'_, SIZE> {
- type Target = MmioOwned<SIZE>;
+impl<'a, const SIZE: usize> Io<'a> for &'a ExclusiveIoMem<'_, SIZE> {
+ type Backend = MmioBackend;
+ type Target = super::Region<SIZE>;
- fn deref(&self) -> &Self::Target {
- &self.iomem
+ #[inline]
+ fn as_view(self) -> Mmio<'a, Self::Target> {
+ self.iomem.as_view()
}
}
@@ -290,11 +292,13 @@ fn drop(&mut self) {
}
}
-impl<const SIZE: usize> Deref for IoMem<'_, SIZE> {
- type Target = MmioOwned<SIZE>;
+impl<'a, const SIZE: usize> Io<'a> for &'a IoMem<'_, SIZE> {
+ type Backend = MmioBackend;
+ type Target = super::Region<SIZE>;
- fn deref(&self) -> &Self::Target {
+ #[inline]
+ fn as_view(self) -> Mmio<'a, Self::Target> {
// SAFETY: Safe as by the invariant of `IoMem`.
- unsafe { MmioOwned::from_raw(&self.io) }
+ unsafe { Mmio::from_raw(self.io) }
}
}
diff --git a/rust/kernel/pci/io.rs b/rust/kernel/pci/io.rs
index e67c1e3694fb..4be33ecb4192 100644
--- a/rust/kernel/pci/io.rs
+++ b/rust/kernel/pci/io.rs
@@ -11,16 +11,14 @@
Io,
IoBackend,
IoCapable,
- MmioOwned,
+ Mmio,
+ MmioBackend,
MmioRaw,
Region, //
},
prelude::*,
ptr::KnownSize, //
};
-use core::{
- ops::Deref, //
-};
/// Represents the size of a PCI configuration space.
///
@@ -269,12 +267,14 @@ fn drop(&mut self) {
}
}
-impl<const SIZE: usize> Deref for Bar<'_, SIZE> {
- type Target = MmioOwned<SIZE>;
+impl<'a, const SIZE: usize> Io<'a> for &'a Bar<'_, SIZE> {
+ type Backend = MmioBackend;
+ type Target = crate::io::Region<SIZE>;
- fn deref(&self) -> &Self::Target {
+ #[inline]
+ fn as_view(self) -> Mmio<'a, Self::Target> {
// SAFETY: By the type invariant of `Self`, the MMIO range in `self.io` is properly mapped.
- unsafe { MmioOwned::from_raw(&self.io) }
+ unsafe { Mmio::from_raw(self.io) }
}
}
--
2.54.0
^ permalink raw reply related
* [PATCH v5 05/20] rust: io: generalize `MmioRaw` to pointer to arbitrary type
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Conceptually, `MmioRaw` is just `__iomem *`, so it should work for any
types. Update the existing use case where it represents a region of
compile-time known minimum size and run-time known actual size to use the
dynamic-sized type `Region<SIZE>` instead. Rename `maxsize` method to
reflect that it is the actual size (not a bound) of the region.
Implement `Clone` and `Copy` manually, which cannot be derived due to the
generic parameter. The use of raw pointers also cause the `Send` and `Sync`
auto trait implementation to be lost, so add them back by manual
implementation.
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/devres.rs | 7 +++---
rust/kernel/io.rs | 67 +++++++++++++++++++++++++++++++++++++--------------
rust/kernel/io/mem.rs | 5 ++--
rust/kernel/pci/io.rs | 4 +--
4 files changed, 57 insertions(+), 26 deletions(-)
diff --git a/rust/kernel/devres.rs b/rust/kernel/devres.rs
index ed30ccc6e68e..d0c677fd7932 100644
--- a/rust/kernel/devres.rs
+++ b/rust/kernel/devres.rs
@@ -70,14 +70,15 @@ struct Inner<T> {
/// Io,
/// Mmio,
/// MmioRaw,
-/// PhysAddr, //
+/// PhysAddr,
+/// Region, //
/// },
/// prelude::*,
/// };
/// use core::ops::Deref;
///
/// // See also [`pci::Bar`] for a real example.
-/// struct IoMem<const SIZE: usize>(MmioRaw<SIZE>);
+/// struct IoMem<const SIZE: usize>(MmioRaw<Region<SIZE>>);
///
/// impl<const SIZE: usize> IoMem<SIZE> {
/// /// # Safety
@@ -92,7 +93,7 @@ struct Inner<T> {
/// return Err(ENOMEM);
/// }
///
-/// Ok(IoMem(MmioRaw::new(addr as usize, SIZE)?))
+/// Ok(IoMem(MmioRaw::new_region(addr as usize, SIZE)?))
/// }
/// }
///
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 9f060dd29182..12be266d7ed7 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -88,37 +88,67 @@ fn size(p: *const Self) -> usize {
/// Raw representation of an MMIO region.
///
+/// `MmioRaw<T>` is equivalent to `T __iomem *` in C.
+///
/// By itself, the existence of an instance of this structure does not provide any guarantees that
/// the represented MMIO region does exist or is properly mapped.
///
/// Instead, the bus specific MMIO implementation must convert this raw representation into an
/// `Mmio` instance providing the actual memory accessors. Only by the conversion into an `Mmio`
/// structure any guarantees are given.
-pub struct MmioRaw<const SIZE: usize = 0> {
- addr: usize,
- maxsize: usize,
+pub struct MmioRaw<T: ?Sized> {
+ /// Pointer is in I/O address space.
+ ///
+ /// The provenance does not matter, only the address and metadata do.
+ ptr: *mut T,
}
-impl<const SIZE: usize> MmioRaw<SIZE> {
- /// Returns a new `MmioRaw` instance on success, an error otherwise.
- pub fn new(addr: usize, maxsize: usize) -> Result<Self> {
- if maxsize < SIZE {
- return Err(EINVAL);
+impl<T: ?Sized> Copy for MmioRaw<T> {}
+impl<T: ?Sized> Clone for MmioRaw<T> {
+ #[inline]
+ fn clone(&self) -> Self {
+ *self
+ }
+}
+
+// SAFETY: `MmioRaw` is just an address, so is thread-safe.
+unsafe impl<T: ?Sized> Send for MmioRaw<T> {}
+// SAFETY: `MmioRaw` is just an address, so is thread-safe.
+unsafe impl<T: ?Sized> Sync for MmioRaw<T> {}
+
+impl<T> MmioRaw<T> {
+ /// Create a `MmioRaw` from address.
+ #[inline]
+ pub fn new(addr: usize) -> Self {
+ Self {
+ ptr: core::ptr::without_provenance_mut(addr),
}
+ }
+}
- Ok(Self { addr, maxsize })
+impl<const SIZE: usize> MmioRaw<Region<SIZE>> {
+ /// Create a `MmioRaw` representing a I/O region with given size.
+ ///
+ /// The size is checked against the minimum size specified via const generics.
+ #[inline]
+ pub fn new_region(addr: usize, size: usize) -> Result<Self> {
+ Ok(Self {
+ ptr: Region::ptr_try_from_raw_parts_mut(core::ptr::without_provenance_mut(addr), size)?,
+ })
}
+}
+impl<T: ?Sized + KnownSize> MmioRaw<T> {
/// Returns the base address of the MMIO region.
#[inline]
pub fn addr(&self) -> usize {
- self.addr
+ self.ptr.addr()
}
- /// Returns the maximum size of the MMIO region.
+ /// Returns the size of the MMIO region.
#[inline]
- pub fn maxsize(&self) -> usize {
- self.maxsize
+ pub fn size(&self) -> usize {
+ KnownSize::size(self.ptr)
}
}
@@ -143,12 +173,13 @@ pub fn maxsize(&self) -> usize {
/// Mmio,
/// MmioRaw,
/// PhysAddr,
+/// Region,
/// },
/// };
/// use core::ops::Deref;
///
/// // See also `pci::Bar` for a real example.
-/// struct IoMem<const SIZE: usize>(MmioRaw<SIZE>);
+/// struct IoMem<const SIZE: usize>(MmioRaw<Region<SIZE>>);
///
/// impl<const SIZE: usize> IoMem<SIZE> {
/// /// # Safety
@@ -163,7 +194,7 @@ pub fn maxsize(&self) -> usize {
/// return Err(ENOMEM);
/// }
///
-/// Ok(IoMem(MmioRaw::new(addr as usize, SIZE)?))
+/// Ok(IoMem(MmioRaw::new_region(addr as usize, SIZE)?))
/// }
/// }
///
@@ -193,7 +224,7 @@ pub fn maxsize(&self) -> usize {
/// # }
/// ```
#[repr(transparent)]
-pub struct Mmio<const SIZE: usize = 0>(MmioRaw<SIZE>);
+pub struct Mmio<const SIZE: usize = 0>(MmioRaw<Region<SIZE>>);
/// Checks whether an access of type `U` at the given `base` and the given `offset`
/// is valid within this region.
@@ -840,7 +871,7 @@ fn addr(self) -> usize {
/// Returns the maximum size of this mapping.
#[inline]
fn maxsize(self) -> usize {
- self.0.maxsize()
+ self.0.size()
}
}
@@ -851,7 +882,7 @@ impl<const SIZE: usize> Mmio<SIZE> {
///
/// Callers must ensure that `addr` is the start of a valid I/O mapped memory region of size
/// `maxsize`.
- pub unsafe fn from_raw(raw: &MmioRaw<SIZE>) -> &Self {
+ pub unsafe fn from_raw(raw: &MmioRaw<Region<SIZE>>) -> &Self {
// SAFETY: `Mmio` is a transparent wrapper around `MmioRaw`.
unsafe { &*core::ptr::from_ref(raw).cast() }
}
diff --git a/rust/kernel/io/mem.rs b/rust/kernel/io/mem.rs
index fc2a3e24f8d5..9e15bc8fde78 100644
--- a/rust/kernel/io/mem.rs
+++ b/rust/kernel/io/mem.rs
@@ -229,7 +229,7 @@ fn deref(&self) -> &Self::Target {
/// start of the I/O memory mapped region.
pub struct IoMem<'a, const SIZE: usize = 0> {
dev: &'a Device<Bound>,
- io: MmioRaw<SIZE>,
+ io: MmioRaw<super::Region<SIZE>>,
}
impl<'a, const SIZE: usize> IoMem<'a, SIZE> {
@@ -264,8 +264,7 @@ fn ioremap(dev: &'a Device<Bound>, resource: &Resource) -> Result<Self> {
return Err(ENOMEM);
}
- let io = MmioRaw::new(addr as usize, size)?;
-
+ let io = MmioRaw::new_region(addr as usize, size)?;
Ok(IoMem { dev, io })
}
diff --git a/rust/kernel/pci/io.rs b/rust/kernel/pci/io.rs
index 505305cd9b86..42f840d64a6f 100644
--- a/rust/kernel/pci/io.rs
+++ b/rust/kernel/pci/io.rs
@@ -139,7 +139,7 @@ fn maxsize(self) -> usize {
/// memory mapped PCI BAR and its size.
pub struct Bar<'a, const SIZE: usize = 0> {
pdev: &'a Device<device::Bound>,
- io: MmioRaw<SIZE>,
+ io: MmioRaw<crate::io::Region<SIZE>>,
num: i32,
}
@@ -179,7 +179,7 @@ pub(super) fn new(
return Err(ENOMEM);
}
- let io = match MmioRaw::new(ioptr, len as usize) {
+ let io = match MmioRaw::new_region(ioptr, len as usize) {
Ok(io) => io,
Err(err) => {
// SAFETY:
--
2.54.0
^ permalink raw reply related
* [PATCH v5 12/20] rust: io: move `Io` methods to extension trait
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
`Io` trait now has a single required methods with many more provided
methods. Provided methods may want to rely on their implementations to not
be arbitrarily overridden by implementers for correctness or soundness.
Thus, extract these methods to a new trait and provide a blanket
implementation. This pattern is used extensively in userspace Rust
libraries e.g. `tokio` where `AsyncRead` has minimum methods and
`AsyncReadExt` is what users mostly interact with.
To avoid changing all user imports, the base trait is renamed to `IoBase`
and the newly added trait takes the existing `Io` name.
A `size` method is added as an example of methods that users should not
override.
Suggested-by: Danilo Krummrich <dakr@kernel.org>
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/devres.rs | 3 ++-
rust/kernel/io.rs | 34 ++++++++++++++++++++++++----------
rust/kernel/io/mem.rs | 6 +++---
rust/kernel/pci/io.rs | 6 +++---
4 files changed, 32 insertions(+), 17 deletions(-)
diff --git a/rust/kernel/devres.rs b/rust/kernel/devres.rs
index 3545ffc5345d..6e0b845b229b 100644
--- a/rust/kernel/devres.rs
+++ b/rust/kernel/devres.rs
@@ -68,6 +68,7 @@ struct Inner<T> {
/// devres::Devres,
/// io::{
/// Io,
+/// IoBase,
/// Mmio,
/// MmioRaw,
/// MmioBackend,
@@ -105,7 +106,7 @@ struct Inner<T> {
/// }
/// }
///
-/// impl<'a, const SIZE: usize> Io<'a> for &'a IoMem<SIZE> {
+/// impl<'a, const SIZE: usize> IoBase<'a> for &'a IoMem<SIZE> {
/// type Backend = MmioBackend;
/// type Target = Region<SIZE>;
///
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index adafd273920f..0746b0d209ef 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -223,7 +223,7 @@ fn io_view<'a, IO: Io<'a>, U>(
/// operation.
pub trait IoBackend {
/// View type for this I/O backend.
- type View<'a, T: ?Sized + KnownSize>: Io<'a, Backend = Self, Target = T>;
+ type View<'a, T: ?Sized + KnownSize>: IoBase<'a, Backend = Self, Target = T>;
/// Convert a `view` to a raw pointer for projection.
///
@@ -309,15 +309,12 @@ fn offset(self) -> usize {
/// Types implementing this trait (e.g. MMIO BARs or PCI config regions)
/// can perform I/O operations on regions of memory.
///
-/// The [`Io`] trait provides:
-/// - Method to convert into [`IoBackend::View`].
-/// - Helper methods for offset validation and address calculation
-/// - Fallible (runtime checked) accessors for different data widths
-///
-/// Which I/O methods are available depends on the associated [`IoBackend`] implementation.
+/// This trait defines which backend shall be used for I/O operations and provides a method to
+/// convert into [`IoBackend::View`]. Users should use the [`Io`] trait which provides the actual
+/// methods to perform I/O operations.
///
/// This should be implemented on cheaply copyable handles, such as references or view types.
-pub trait Io<'a>: Copy {
+pub trait IoBase<'a>: Copy {
/// Type that defines all I/O operations.
type Backend: IoBackend;
@@ -326,6 +323,21 @@ pub trait Io<'a>: Copy {
/// Return a view that covers the full region.
fn as_view(self) -> <Self::Backend as IoBackend>::View<'a, Self::Target>;
+}
+
+/// Extension trait to provide I/O operation methods to types that implement [`IoBase`].
+///
+/// This trait provides:
+/// - Helper methods for offset validation and address calculation
+/// - Fallible (runtime checked) accessors for different data widths
+///
+/// Which I/O methods are available depends on the associated [`IoBackend`] implementation.
+pub trait Io<'a>: IoBase<'a> {
+ /// Returns the size of this I/O region.
+ #[inline]
+ fn size(self) -> usize {
+ KnownSize::size(Self::Backend::as_ptr(self.as_view()))
+ }
/// Fallible 8-bit read with runtime bounds check.
#[inline(always)]
@@ -779,6 +791,8 @@ fn update<T, L, F>(self, location: L, f: F)
}
}
+impl<'a, T: IoBase<'a>> Io<'a> for T {}
+
/// A view of memory-mapped I/O region.
///
/// # Invariant
@@ -819,7 +833,7 @@ unsafe impl<T: ?Sized + Sync> Send for Mmio<'_, T> {}
// SAFETY: `Mmio<'_, T>` is conceptually `&T` but in I/O memory.
unsafe impl<T: ?Sized + Sync> Sync for Mmio<'_, T> {}
-impl<'a, T: ?Sized + KnownSize> Io<'a> for Mmio<'a, T> {
+impl<'a, T: ?Sized + KnownSize> IoBase<'a> for Mmio<'a, T> {
type Backend = MmioBackend;
type Target = T;
@@ -920,7 +934,7 @@ unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>(
}
}
-impl<'a, T: ?Sized + KnownSize> Io<'a> for RelaxedMmio<'a, T> {
+impl<'a, T: ?Sized + KnownSize> IoBase<'a> for RelaxedMmio<'a, T> {
type Backend = RelaxedMmioBackend;
type Target = T;
diff --git a/rust/kernel/io/mem.rs b/rust/kernel/io/mem.rs
index d9b3189d09b4..e95b769ebe47 100644
--- a/rust/kernel/io/mem.rs
+++ b/rust/kernel/io/mem.rs
@@ -14,7 +14,7 @@
Region,
Resource, //
},
- Io,
+ IoBase,
Mmio,
MmioBackend,
MmioRaw, //
@@ -210,7 +210,7 @@ pub fn into_devres(self) -> Result<Devres<ExclusiveIoMem<'static, SIZE>>> {
}
}
-impl<'a, const SIZE: usize> Io<'a> for &'a ExclusiveIoMem<'_, SIZE> {
+impl<'a, const SIZE: usize> IoBase<'a> for &'a ExclusiveIoMem<'_, SIZE> {
type Backend = MmioBackend;
type Target = super::Region<SIZE>;
@@ -292,7 +292,7 @@ fn drop(&mut self) {
}
}
-impl<'a, const SIZE: usize> Io<'a> for &'a IoMem<'_, SIZE> {
+impl<'a, const SIZE: usize> IoBase<'a> for &'a IoMem<'_, SIZE> {
type Backend = MmioBackend;
type Target = super::Region<SIZE>;
diff --git a/rust/kernel/pci/io.rs b/rust/kernel/pci/io.rs
index 4be33ecb4192..4d1d0afdc491 100644
--- a/rust/kernel/pci/io.rs
+++ b/rust/kernel/pci/io.rs
@@ -8,8 +8,8 @@
device,
devres::Devres,
io::{
- Io,
IoBackend,
+ IoBase,
IoCapable,
Mmio,
MmioBackend,
@@ -144,7 +144,7 @@ fn io_write(view: ConfigSpace<'_, $ty>, value: $ty) {
impl_config_space_io_capable!(u16, pci_read_config_word, pci_write_config_word);
impl_config_space_io_capable!(u32, pci_read_config_dword, pci_write_config_dword);
-impl<'a, T: ?Sized + KnownSize> Io<'a> for ConfigSpace<'a, T> {
+impl<'a, T: ?Sized + KnownSize> IoBase<'a> for ConfigSpace<'a, T> {
type Backend = ConfigSpaceBackend;
type Target = T;
@@ -267,7 +267,7 @@ fn drop(&mut self) {
}
}
-impl<'a, const SIZE: usize> Io<'a> for &'a Bar<'_, SIZE> {
+impl<'a, const SIZE: usize> IoBase<'a> for &'a Bar<'_, SIZE> {
type Backend = MmioBackend;
type Target = crate::io::Region<SIZE>;
--
2.54.0
^ permalink raw reply related
* [PATCH v5 04/20] rust: io: implement `Io` on reference types instead
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Currently, `Io` is implemented on owned I/O objects (e.g. `Bar`). This is
going to change with I/O projections, as then `Io` needs to work both for
owned objects and views of them. Views are themselves reference-like
(however they obviously cannot be references, because they belong to a
different address space).
To facilitate the change, change `Io` to be implemented on reference types
for the owned I/O objects, and make methods take `self` instead of `&self`.
When I/O views are implemented, we can then naturally implement `Io` for
these objects.
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/io.rs | 82 ++++++++++++++++++++++++++-------------------------
rust/kernel/pci/io.rs | 12 ++++----
2 files changed, 48 insertions(+), 46 deletions(-)
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 87141eb07056..9f060dd29182 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -223,7 +223,7 @@ pub trait IoCapable<T> {
///
/// - The range `[address..address + size_of::<T>()]` must be within the bounds of `Self`.
/// - `address` must be aligned.
- unsafe fn io_read(&self, address: usize) -> T;
+ unsafe fn io_read(self, address: usize) -> T;
/// Performs an I/O write of `value` at `address`.
///
@@ -231,7 +231,7 @@ pub trait IoCapable<T> {
///
/// - The range `[address..address + size_of::<T>()]` must be within the bounds of `Self`.
/// - `address` must be aligned.
- unsafe fn io_write(&self, value: T, address: usize);
+ unsafe fn io_write(self, value: T, address: usize);
}
/// Describes a given I/O location: its offset, width, and type to convert the raw value from and
@@ -294,25 +294,27 @@ fn offset(self) -> usize {
/// Which I/O methods are available depends on which [`IoCapable<T>`] traits
/// are implemented for the type.
///
+/// This should be implemented on cheaply copyable handles, such as references or view types.
+///
/// # Examples
///
/// 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 {
+pub trait Io: Copy {
/// 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;
+ fn addr(self) -> usize;
/// Returns the maximum size of this mapping.
- fn maxsize(&self) -> usize;
+ fn maxsize(self) -> usize;
/// Returns the absolute I/O address for a given `offset`,
/// performing compile-time bound checks.
// Always inline to optimize out error path of `build_assert`.
#[inline(always)]
- fn io_addr_assert<U>(&self, offset: usize) -> usize {
+ fn io_addr_assert<U>(self, offset: usize) -> usize {
// We cannot check alignment with `offset_valid` using `self.addr()`. So set 0 for it and
// ensure alignment by checking that the alignment of `U` is smaller or equal to the
// alignment of `Self::Target`.
@@ -325,7 +327,7 @@ fn io_addr_assert<U>(&self, offset: usize) -> usize {
/// Returns the absolute I/O address for a given `offset`,
/// performing runtime bound checks.
#[inline]
- fn io_addr<U>(&self, offset: usize) -> Result<usize> {
+ fn io_addr<U>(self, offset: usize) -> Result<usize> {
if !offset_valid::<U>(self.addr(), offset, self.maxsize()) {
return Err(EINVAL);
}
@@ -337,7 +339,7 @@ fn io_addr<U>(&self, offset: usize) -> Result<usize> {
/// Fallible 8-bit read with runtime bounds check.
#[inline(always)]
- fn try_read8(&self, offset: usize) -> Result<u8>
+ fn try_read8(self, offset: usize) -> Result<u8>
where
usize: IoLoc<Self::Target, u8, IoType = u8>,
Self: IoCapable<u8>,
@@ -347,7 +349,7 @@ fn try_read8(&self, offset: usize) -> Result<u8>
/// Fallible 16-bit read with runtime bounds check.
#[inline(always)]
- fn try_read16(&self, offset: usize) -> Result<u16>
+ fn try_read16(self, offset: usize) -> Result<u16>
where
usize: IoLoc<Self::Target, u16, IoType = u16>,
Self: IoCapable<u16>,
@@ -357,7 +359,7 @@ fn try_read16(&self, offset: usize) -> Result<u16>
/// Fallible 32-bit read with runtime bounds check.
#[inline(always)]
- fn try_read32(&self, offset: usize) -> Result<u32>
+ fn try_read32(self, offset: usize) -> Result<u32>
where
usize: IoLoc<Self::Target, u32, IoType = u32>,
Self: IoCapable<u32>,
@@ -367,7 +369,7 @@ fn try_read32(&self, offset: usize) -> Result<u32>
/// Fallible 64-bit read with runtime bounds check.
#[inline(always)]
- fn try_read64(&self, offset: usize) -> Result<u64>
+ fn try_read64(self, offset: usize) -> Result<u64>
where
usize: IoLoc<Self::Target, u64, IoType = u64>,
Self: IoCapable<u64>,
@@ -377,7 +379,7 @@ fn try_read64(&self, offset: usize) -> Result<u64>
/// Fallible 8-bit write with runtime bounds check.
#[inline(always)]
- fn try_write8(&self, value: u8, offset: usize) -> Result
+ fn try_write8(self, value: u8, offset: usize) -> Result
where
usize: IoLoc<Self::Target, u8, IoType = u8>,
Self: IoCapable<u8>,
@@ -387,7 +389,7 @@ fn try_write8(&self, value: u8, offset: usize) -> Result
/// Fallible 16-bit write with runtime bounds check.
#[inline(always)]
- fn try_write16(&self, value: u16, offset: usize) -> Result
+ fn try_write16(self, value: u16, offset: usize) -> Result
where
usize: IoLoc<Self::Target, u16, IoType = u16>,
Self: IoCapable<u16>,
@@ -397,7 +399,7 @@ fn try_write16(&self, value: u16, offset: usize) -> Result
/// Fallible 32-bit write with runtime bounds check.
#[inline(always)]
- fn try_write32(&self, value: u32, offset: usize) -> Result
+ fn try_write32(self, value: u32, offset: usize) -> Result
where
usize: IoLoc<Self::Target, u32, IoType = u32>,
Self: IoCapable<u32>,
@@ -407,7 +409,7 @@ fn try_write32(&self, value: u32, offset: usize) -> Result
/// Fallible 64-bit write with runtime bounds check.
#[inline(always)]
- fn try_write64(&self, value: u64, offset: usize) -> Result
+ fn try_write64(self, value: u64, offset: usize) -> Result
where
usize: IoLoc<Self::Target, u64, IoType = u64>,
Self: IoCapable<u64>,
@@ -417,7 +419,7 @@ fn try_write64(&self, value: u64, offset: usize) -> Result
/// Infallible 8-bit read with compile-time bounds check.
#[inline(always)]
- fn read8(&self, offset: usize) -> u8
+ fn read8(self, offset: usize) -> u8
where
usize: IoLoc<Self::Target, u8, IoType = u8>,
Self: IoCapable<u8>,
@@ -427,7 +429,7 @@ fn read8(&self, offset: usize) -> u8
/// Infallible 16-bit read with compile-time bounds check.
#[inline(always)]
- fn read16(&self, offset: usize) -> u16
+ fn read16(self, offset: usize) -> u16
where
usize: IoLoc<Self::Target, u16, IoType = u16>,
Self: IoCapable<u16>,
@@ -437,7 +439,7 @@ fn read16(&self, offset: usize) -> u16
/// Infallible 32-bit read with compile-time bounds check.
#[inline(always)]
- fn read32(&self, offset: usize) -> u32
+ fn read32(self, offset: usize) -> u32
where
usize: IoLoc<Self::Target, u32, IoType = u32>,
Self: IoCapable<u32>,
@@ -447,7 +449,7 @@ fn read32(&self, offset: usize) -> u32
/// Infallible 64-bit read with compile-time bounds check.
#[inline(always)]
- fn read64(&self, offset: usize) -> u64
+ fn read64(self, offset: usize) -> u64
where
usize: IoLoc<Self::Target, u64, IoType = u64>,
Self: IoCapable<u64>,
@@ -457,7 +459,7 @@ fn read64(&self, offset: usize) -> u64
/// Infallible 8-bit write with compile-time bounds check.
#[inline(always)]
- fn write8(&self, value: u8, offset: usize)
+ fn write8(self, value: u8, offset: usize)
where
usize: IoLoc<Self::Target, u8, IoType = u8>,
Self: IoCapable<u8>,
@@ -467,7 +469,7 @@ fn write8(&self, value: u8, offset: usize)
/// Infallible 16-bit write with compile-time bounds check.
#[inline(always)]
- fn write16(&self, value: u16, offset: usize)
+ fn write16(self, value: u16, offset: usize)
where
usize: IoLoc<Self::Target, u16, IoType = u16>,
Self: IoCapable<u16>,
@@ -477,7 +479,7 @@ fn write16(&self, value: u16, offset: usize)
/// Infallible 32-bit write with compile-time bounds check.
#[inline(always)]
- fn write32(&self, value: u32, offset: usize)
+ fn write32(self, value: u32, offset: usize)
where
usize: IoLoc<Self::Target, u32, IoType = u32>,
Self: IoCapable<u32>,
@@ -487,7 +489,7 @@ fn write32(&self, value: u32, offset: usize)
/// Infallible 64-bit write with compile-time bounds check.
#[inline(always)]
- fn write64(&self, value: u64, offset: usize)
+ fn write64(self, value: u64, offset: usize)
where
usize: IoLoc<Self::Target, u64, IoType = u64>,
Self: IoCapable<u64>,
@@ -518,7 +520,7 @@ fn write64(&self, value: u64, offset: usize)
/// }
/// ```
#[inline(always)]
- fn try_read<T, L>(&self, location: L) -> Result<T>
+ fn try_read<T, L>(self, location: L) -> Result<T>
where
L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
@@ -552,7 +554,7 @@ fn try_read<T, L>(&self, location: L) -> Result<T>
/// }
/// ```
#[inline(always)]
- fn try_write<T, L>(&self, location: L, value: T) -> Result
+ fn try_write<T, L>(self, location: L, value: T) -> Result
where
L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
@@ -598,7 +600,7 @@ fn try_write<T, L>(&self, location: L, value: T) -> Result
/// }
/// ```
#[inline(always)]
- fn try_write_reg<T, L, V>(&self, value: V) -> Result
+ fn try_write_reg<T, L, V>(self, value: V) -> Result
where
L: IoLoc<Self::Target, T>,
V: LocatedRegister<Self::Target, Location = L, Value = T>,
@@ -631,7 +633,7 @@ fn try_write_reg<T, L, V>(&self, value: V) -> Result
/// }
/// ```
#[inline(always)]
- fn try_update<T, L, F>(&self, location: L, f: F) -> Result
+ fn try_update<T, L, F>(self, location: L, f: F) -> Result
where
L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
@@ -670,7 +672,7 @@ fn try_update<T, L, F>(&self, location: L, f: F) -> Result
/// }
/// ```
#[inline(always)]
- fn read<T, L>(&self, location: L) -> T
+ fn read<T, L>(self, location: L) -> T
where
L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
@@ -702,7 +704,7 @@ fn read<T, L>(&self, location: L) -> T
/// }
/// ```
#[inline(always)]
- fn write<T, L>(&self, location: L, value: T)
+ fn write<T, L>(self, location: L, value: T)
where
L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
@@ -745,7 +747,7 @@ fn write<T, L>(&self, location: L, value: T)
/// }
/// ```
#[inline(always)]
- fn write_reg<T, L, V>(&self, value: V)
+ fn write_reg<T, L, V>(self, value: V)
where
L: IoLoc<Self::Target, T>,
V: LocatedRegister<Self::Target, Location = L, Value = T>,
@@ -778,7 +780,7 @@ fn write_reg<T, L, V>(&self, value: V)
/// }
/// ```
#[inline(always)]
- fn update<T, L, F>(&self, location: L, f: F)
+ fn update<T, L, F>(self, location: L, f: F)
where
L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
@@ -799,13 +801,13 @@ fn update<T, L, F>(&self, location: L, f: F)
macro_rules! impl_mmio_io_capable {
($mmio:ident, $(#[$attr:meta])* $ty:ty, $read_fn:ident, $write_fn:ident) => {
$(#[$attr])*
- impl<const SIZE: usize> IoCapable<$ty> for $mmio<SIZE> {
- unsafe fn io_read(&self, address: usize) -> $ty {
+ impl<const SIZE: usize> IoCapable<$ty> for &$mmio<SIZE> {
+ unsafe fn io_read(self, address: usize) -> $ty {
// SAFETY: By the trait invariant `address` is a valid address for MMIO operations.
unsafe { bindings::$read_fn(address as *const c_void) }
}
- unsafe fn io_write(&self, value: $ty, address: usize) {
+ unsafe fn io_write(self, value: $ty, address: usize) {
// SAFETY: By the trait invariant `address` is a valid address for MMIO operations.
unsafe { bindings::$write_fn(value, address as *mut c_void) }
}
@@ -826,18 +828,18 @@ unsafe fn io_write(&self, value: $ty, address: usize) {
writeq
);
-impl<const SIZE: usize> Io for Mmio<SIZE> {
+impl<'a, const SIZE: usize> Io for &'a Mmio<SIZE> {
type Target = Region<SIZE>;
/// Returns the base address of this mapping.
#[inline]
- fn addr(&self) -> usize {
+ fn addr(self) -> usize {
self.0.addr()
}
/// Returns the maximum size of this mapping.
#[inline]
- fn maxsize(&self) -> usize {
+ fn maxsize(self) -> usize {
self.0.maxsize()
}
}
@@ -864,16 +866,16 @@ pub unsafe fn from_raw(raw: &MmioRaw<SIZE>) -> &Self {
#[repr(transparent)]
pub struct RelaxedMmio<const SIZE: usize = 0>(Mmio<SIZE>);
-impl<const SIZE: usize> Io for RelaxedMmio<SIZE> {
+impl<'a, const SIZE: usize> Io for &'a RelaxedMmio<SIZE> {
type Target = Region<SIZE>;
#[inline]
- fn addr(&self) -> usize {
+ fn addr(self) -> usize {
self.0.addr()
}
#[inline]
- fn maxsize(&self) -> usize {
+ fn maxsize(self) -> usize {
self.0.maxsize()
}
}
diff --git a/rust/kernel/pci/io.rs b/rust/kernel/pci/io.rs
index b4996aa059d8..505305cd9b86 100644
--- a/rust/kernel/pci/io.rs
+++ b/rust/kernel/pci/io.rs
@@ -79,8 +79,8 @@ pub struct ConfigSpace<'a, S: ?Sized + ConfigSpaceKind = Extended> {
/// Implements [`IoCapable`] on [`ConfigSpace`] for `$ty` using `$read_fn` and `$write_fn`.
macro_rules! impl_config_space_io_capable {
($ty:ty, $read_fn:ident, $write_fn:ident) => {
- impl<'a, S: ?Sized + ConfigSpaceKind> IoCapable<$ty> for ConfigSpace<'a, S> {
- unsafe fn io_read(&self, address: usize) -> $ty {
+ impl<'a, S: ?Sized + ConfigSpaceKind> IoCapable<$ty> for &ConfigSpace<'a, S> {
+ unsafe fn io_read(self, address: usize) -> $ty {
let mut val: $ty = 0;
// Return value from C function is ignored in infallible accessors.
@@ -94,7 +94,7 @@ unsafe fn io_read(&self, address: usize) -> $ty {
val
}
- unsafe fn io_write(&self, value: $ty, address: usize) {
+ unsafe fn io_write(self, value: $ty, address: usize) {
// Return value from C function is ignored in infallible accessors.
let _ret =
// SAFETY: By the type invariant `self.pdev` is a valid address.
@@ -112,18 +112,18 @@ unsafe fn io_write(&self, value: $ty, address: usize) {
impl_config_space_io_capable!(u16, pci_read_config_word, pci_write_config_word);
impl_config_space_io_capable!(u32, pci_read_config_dword, pci_write_config_dword);
-impl<'a, S: ?Sized + ConfigSpaceKind> Io for ConfigSpace<'a, S> {
+impl<'a, S: ?Sized + ConfigSpaceKind> Io for &ConfigSpace<'a, S> {
type Target = S;
/// Returns the base address of the I/O region. It is always 0 for configuration space.
#[inline]
- fn addr(&self) -> usize {
+ fn addr(self) -> usize {
0
}
/// Returns the maximum size of the configuration space.
#[inline]
- fn maxsize(&self) -> usize {
+ fn maxsize(self) -> usize {
self.pdev.cfg_size().into_raw()
}
}
--
2.54.0
^ permalink raw reply related
* [PATCH v5 09/20] rust: io: use view types instead of addresses for `Io`
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Currently, `io_read` and `io_write` methods require the exact type of `Io`
plus an address. This means that they need to be monomorphized for each
different `Io` instance. This also means that multiple I/O implementors for
the same I/O kind needs to duplicate implementation (e.g. `Mmio` and
`MmioOwned`).
Create a new `IoBackend` trait and define these operations on it instead.
The operations are just going to receive a view type and operate on them.
This has the additional advantage that the invariants can be moved from the
trait (and guaranteed via `unsafe`) to type invariants on the canonical
view types of the backends, so `io_read` and `io_write` can be safe.
Note that view type is needed; addresses are insufficient in this
design, as they do not carry sufficient information. For example,
`ConfigSpace` needs `&pci::Device` in addition to the address.
`io_addr_assert` and `io_addr` are renamed to `io_view*` to reflect
that they operate on views now, and make them standalone functions so
they cannot be used by users to cast types outside io.rs.
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/io.rs | 382 ++++++++++++++++++++++++++------------------------
rust/kernel/pci/io.rs | 70 +++++----
2 files changed, 246 insertions(+), 206 deletions(-)
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 8110b49aa430..67b8c62f3771 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -243,6 +243,81 @@ const fn offset_valid<U>(base: usize, offset: usize, size: usize) -> bool {
}
}
+/// Returns a view for a given `offset`, performing compile-time bound checks.
+// Always inline to optimize out error path of `build_assert`.
+#[inline(always)]
+fn io_view_assert<'a, IO: Io<'a>, U>(
+ this: IO,
+ offset: usize,
+) -> <IO::Backend as IoBackend>::View<'a, U> {
+ // We cannot check alignment with `offset_valid` using `ptr.addr()`. So set 0 for it and
+ // ensure alignment by checking that the alignment of `U` is smaller or equal to the
+ // alignment of `IO::Target`.
+ const_assert!(Alignment::of::<U>().as_usize() <= IO::Target::MIN_ALIGN.as_usize());
+ build_assert!(offset_valid::<U>(0, offset, IO::Target::MIN_SIZE));
+
+ let view = this.as_view();
+ let ptr = IO::Backend::as_ptr(view);
+ let projected_ptr = ptr.cast::<U>().wrapping_byte_add(offset);
+ // SAFETY: `offset_valid` checks for size and alignment and therefore `projected_ptr` is a
+ // valid projection.
+ unsafe { IO::Backend::project_view(view, projected_ptr) }
+}
+
+/// Returns a view for a given `offset`, performing runtime bound checks.
+#[inline]
+fn io_view<'a, IO: Io<'a>, U>(
+ this: IO,
+ offset: usize,
+) -> Result<<IO::Backend as IoBackend>::View<'a, U>> {
+ let view = this.as_view();
+ let ptr = IO::Backend::as_ptr(view);
+
+ if !offset_valid::<U>(ptr.addr(), offset, KnownSize::size(ptr)) {
+ return Err(EINVAL);
+ }
+
+ let projected_ptr = ptr.cast::<U>().wrapping_byte_add(offset);
+ // SAFETY: `offset_valid` checks for size and alignment and therefore `projected_ptr` is a
+ // valid projection.
+ Ok(unsafe { IO::Backend::project_view(view, projected_ptr) })
+}
+
+/// I/O backends.
+///
+/// This is an abstract representation to be implemented by arbitrary I/O
+/// backends (e.g. MMIO, PCI config space, etc.).
+///
+/// The base trait only defines the projection operations; which I/O methods are available depends
+/// on which [`IoCapable<T>`] traits are implemented for the type. For example, 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.
+///
+/// This trait is separate from the `Io` trait as multiple different I/O types may share the same
+/// operation.
+pub trait IoBackend {
+ /// View type for this I/O backend.
+ type View<'a, T: ?Sized + KnownSize>: Io<'a, Backend = Self, Target = T>;
+
+ /// Convert a `view` to a raw pointer for projection.
+ ///
+ /// The returned pointer is private implementation detail of the backend; it is likely not
+ /// valid. It should be used for projection only.
+ fn as_ptr<'a, T: ?Sized + KnownSize>(view: Self::View<'a, T>) -> *mut T;
+
+ /// Project `view` to its subregion indicated by `ptr`.
+ ///
+ /// If input `view` is valid, returned view must also be valid.
+ ///
+ /// # Safety
+ ///
+ /// `ptr` must be a projection of `Self::as_ptr(view)`.
+ unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>(
+ view: Self::View<'a, T>,
+ ptr: *mut U,
+ ) -> Self::View<'a, U>;
+}
+
/// Trait indicating that an I/O backend supports operations of a certain type and providing an
/// implementation for these operations.
///
@@ -251,22 +326,12 @@ const fn offset_valid<U>(base: usize, offset: usize, size: usize) -> bool {
/// For example, a PCI configuration space may implement `IoCapable<u8>`, `IoCapable<u16>`,
/// and `IoCapable<u32>`, but not `IoCapable<u64>`, while an MMIO region on a 64-bit
/// system might implement all four.
-pub trait IoCapable<T> {
- /// Performs an I/O read of type `T` at `address` and returns the result.
- ///
- /// # Safety
- ///
- /// - The range `[address..address + size_of::<T>()]` must be within the bounds of `Self`.
- /// - `address` must be aligned.
- unsafe fn io_read(self, address: usize) -> T;
+pub trait IoCapable<T>: IoBackend {
+ /// Performs an I/O read of type `T` at `view` and returns the result.
+ fn io_read<'a>(view: Self::View<'a, T>) -> T;
- /// Performs an I/O write of `value` at `address`.
- ///
- /// # Safety
- ///
- /// - The range `[address..address + size_of::<T>()]` must be within the bounds of `Self`.
- /// - `address` must be aligned.
- unsafe fn io_write(self, value: T, address: usize);
+ /// Performs an I/O write of `value` at `view`.
+ fn io_write<'a>(view: Self::View<'a, T>, value: T);
}
/// Describes a given I/O location: its offset, width, and type to convert the raw value from and
@@ -318,66 +383,30 @@ fn offset(self) -> usize {
/// Types implementing this trait (e.g. MMIO BARs or PCI config regions)
/// can perform I/O operations on regions of memory.
///
-/// This is an abstract representation to be implemented by arbitrary I/O
-/// backends (e.g. MMIO, PCI config space, etc.).
-///
/// The [`Io`] trait provides:
-/// - Base address and size information
+/// - Method to convert into [`IoBackend::View`].
/// - Helper methods for offset validation and address calculation
/// - Fallible (runtime checked) accessors for different data widths
///
-/// Which I/O methods are available depends on which [`IoCapable<T>`] traits
-/// are implemented for the type.
+/// Which I/O methods are available depends on the associated [`IoBackend`] implementation.
///
/// This should be implemented on cheaply copyable handles, such as references or view types.
-///
-/// # Examples
-///
-/// 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: Copy {
+pub trait Io<'a>: Copy {
+ /// Type that defines all I/O operations.
+ type Backend: IoBackend;
+
/// 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.
- // Always inline to optimize out error path of `build_assert`.
- #[inline(always)]
- fn io_addr_assert<U>(self, offset: usize) -> usize {
- // We cannot check alignment with `offset_valid` using `self.addr()`. So set 0 for it and
- // ensure alignment by checking that the alignment of `U` is smaller or equal to the
- // alignment of `Self::Target`.
- const_assert!(Alignment::of::<U>().as_usize() <= Self::Target::MIN_ALIGN.as_usize());
- build_assert!(offset_valid::<U>(0, offset, Self::Target::MIN_SIZE));
-
- self.addr() + offset
- }
-
- /// Returns the absolute I/O address for a given `offset`,
- /// performing runtime bound checks.
- #[inline]
- fn io_addr<U>(self, offset: usize) -> Result<usize> {
- if !offset_valid::<U>(self.addr(), offset, self.maxsize()) {
- return Err(EINVAL);
- }
-
- // Probably no need to check, since the safety requirements of `Self::new` guarantee that
- // this can't overflow.
- self.addr().checked_add(offset).ok_or(EINVAL)
- }
+ /// Return a view that covers the full region.
+ fn as_view(self) -> <Self::Backend as IoBackend>::View<'a, Self::Target>;
/// Fallible 8-bit read with runtime bounds check.
#[inline(always)]
fn try_read8(self, offset: usize) -> Result<u8>
where
usize: IoLoc<Self::Target, u8, IoType = u8>,
- Self: IoCapable<u8>,
+ Self::Backend: IoCapable<u8>,
{
self.try_read(offset)
}
@@ -387,7 +416,7 @@ fn try_read8(self, offset: usize) -> Result<u8>
fn try_read16(self, offset: usize) -> Result<u16>
where
usize: IoLoc<Self::Target, u16, IoType = u16>,
- Self: IoCapable<u16>,
+ Self::Backend: IoCapable<u16>,
{
self.try_read(offset)
}
@@ -397,7 +426,7 @@ fn try_read16(self, offset: usize) -> Result<u16>
fn try_read32(self, offset: usize) -> Result<u32>
where
usize: IoLoc<Self::Target, u32, IoType = u32>,
- Self: IoCapable<u32>,
+ Self::Backend: IoCapable<u32>,
{
self.try_read(offset)
}
@@ -407,7 +436,7 @@ fn try_read32(self, offset: usize) -> Result<u32>
fn try_read64(self, offset: usize) -> Result<u64>
where
usize: IoLoc<Self::Target, u64, IoType = u64>,
- Self: IoCapable<u64>,
+ Self::Backend: IoCapable<u64>,
{
self.try_read(offset)
}
@@ -417,7 +446,7 @@ fn try_read64(self, offset: usize) -> Result<u64>
fn try_write8(self, value: u8, offset: usize) -> Result
where
usize: IoLoc<Self::Target, u8, IoType = u8>,
- Self: IoCapable<u8>,
+ Self::Backend: IoCapable<u8>,
{
self.try_write(offset, value)
}
@@ -427,7 +456,7 @@ fn try_write8(self, value: u8, offset: usize) -> Result
fn try_write16(self, value: u16, offset: usize) -> Result
where
usize: IoLoc<Self::Target, u16, IoType = u16>,
- Self: IoCapable<u16>,
+ Self::Backend: IoCapable<u16>,
{
self.try_write(offset, value)
}
@@ -437,7 +466,7 @@ fn try_write16(self, value: u16, offset: usize) -> Result
fn try_write32(self, value: u32, offset: usize) -> Result
where
usize: IoLoc<Self::Target, u32, IoType = u32>,
- Self: IoCapable<u32>,
+ Self::Backend: IoCapable<u32>,
{
self.try_write(offset, value)
}
@@ -447,7 +476,7 @@ fn try_write32(self, value: u32, offset: usize) -> Result
fn try_write64(self, value: u64, offset: usize) -> Result
where
usize: IoLoc<Self::Target, u64, IoType = u64>,
- Self: IoCapable<u64>,
+ Self::Backend: IoCapable<u64>,
{
self.try_write(offset, value)
}
@@ -457,7 +486,7 @@ fn try_write64(self, value: u64, offset: usize) -> Result
fn read8(self, offset: usize) -> u8
where
usize: IoLoc<Self::Target, u8, IoType = u8>,
- Self: IoCapable<u8>,
+ Self::Backend: IoCapable<u8>,
{
self.read(offset)
}
@@ -467,7 +496,7 @@ fn read8(self, offset: usize) -> u8
fn read16(self, offset: usize) -> u16
where
usize: IoLoc<Self::Target, u16, IoType = u16>,
- Self: IoCapable<u16>,
+ Self::Backend: IoCapable<u16>,
{
self.read(offset)
}
@@ -477,7 +506,7 @@ fn read16(self, offset: usize) -> u16
fn read32(self, offset: usize) -> u32
where
usize: IoLoc<Self::Target, u32, IoType = u32>,
- Self: IoCapable<u32>,
+ Self::Backend: IoCapable<u32>,
{
self.read(offset)
}
@@ -487,7 +516,7 @@ fn read32(self, offset: usize) -> u32
fn read64(self, offset: usize) -> u64
where
usize: IoLoc<Self::Target, u64, IoType = u64>,
- Self: IoCapable<u64>,
+ Self::Backend: IoCapable<u64>,
{
self.read(offset)
}
@@ -497,7 +526,7 @@ fn read64(self, offset: usize) -> u64
fn write8(self, value: u8, offset: usize)
where
usize: IoLoc<Self::Target, u8, IoType = u8>,
- Self: IoCapable<u8>,
+ Self::Backend: IoCapable<u8>,
{
self.write(offset, value)
}
@@ -507,7 +536,7 @@ fn write8(self, value: u8, offset: usize)
fn write16(self, value: u16, offset: usize)
where
usize: IoLoc<Self::Target, u16, IoType = u16>,
- Self: IoCapable<u16>,
+ Self::Backend: IoCapable<u16>,
{
self.write(offset, value)
}
@@ -517,7 +546,7 @@ fn write16(self, value: u16, offset: usize)
fn write32(self, value: u32, offset: usize)
where
usize: IoLoc<Self::Target, u32, IoType = u32>,
- Self: IoCapable<u32>,
+ Self::Backend: IoCapable<u32>,
{
self.write(offset, value)
}
@@ -527,7 +556,7 @@ fn write32(self, value: u32, offset: usize)
fn write64(self, value: u64, offset: usize)
where
usize: IoLoc<Self::Target, u64, IoType = u64>,
- Self: IoCapable<u64>,
+ Self::Backend: IoCapable<u64>,
{
self.write(offset, value)
}
@@ -559,12 +588,10 @@ fn write64(self, value: u64, offset: usize)
fn try_read<T, L>(self, location: L) -> Result<T>
where
L: IoLoc<Self::Target, T>,
- Self: IoCapable<L::IoType>,
+ Self::Backend: IoCapable<L::IoType>,
{
- let address = self.io_addr::<L::IoType>(location.offset())?;
-
- // SAFETY: `address` has been validated by `io_addr`.
- Ok(unsafe { self.io_read(address) }.into())
+ let view = io_view::<Self, L::IoType>(self, location.offset())?;
+ Ok(Self::Backend::io_read(view).into())
}
/// Generic fallible write with runtime bounds check.
@@ -594,14 +621,11 @@ fn try_read<T, L>(self, location: L) -> Result<T>
fn try_write<T, L>(self, location: L, value: T) -> Result
where
L: IoLoc<Self::Target, T>,
- Self: IoCapable<L::IoType>,
+ Self::Backend: IoCapable<L::IoType>,
{
- let address = self.io_addr::<L::IoType>(location.offset())?;
+ let view = io_view::<Self, L::IoType>(self, location.offset())?;
let io_value = value.into();
-
- // SAFETY: `address` has been validated by `io_addr`.
- unsafe { self.io_write(io_value, address) }
-
+ Self::Backend::io_write(view, io_value);
Ok(())
}
@@ -642,7 +666,7 @@ fn try_write_reg<T, L, V>(self, value: V) -> Result
where
L: IoLoc<Self::Target, T>,
V: LocatedRegister<Self::Target, Location = L, Value = T>,
- Self: IoCapable<L::IoType>,
+ Self::Backend: IoCapable<L::IoType>,
{
let (location, value) = value.into_io_op();
@@ -675,17 +699,14 @@ fn try_write_reg<T, L, V>(self, value: V) -> Result
fn try_update<T, L, F>(self, location: L, f: F) -> Result
where
L: IoLoc<Self::Target, T>,
- Self: IoCapable<L::IoType>,
+ Self::Backend: IoCapable<L::IoType>,
F: FnOnce(T) -> T,
{
- let address = self.io_addr::<L::IoType>(location.offset())?;
+ let view = io_view::<Self, L::IoType>(self, location.offset())?;
- // SAFETY: `address` has been validated by `io_addr`.
- let value: T = unsafe { self.io_read(address) }.into();
+ let value: T = Self::Backend::io_read(view).into();
let io_value = f(value).into();
-
- // SAFETY: `address` has been validated by `io_addr`.
- unsafe { self.io_write(io_value, address) }
+ Self::Backend::io_write(view, io_value);
Ok(())
}
@@ -715,12 +736,10 @@ fn try_update<T, L, F>(self, location: L, f: F) -> Result
fn read<T, L>(self, location: L) -> T
where
L: IoLoc<Self::Target, T>,
- Self: IoCapable<L::IoType>,
+ Self::Backend: IoCapable<L::IoType>,
{
- let address = self.io_addr_assert::<L::IoType>(location.offset());
-
- // SAFETY: `address` has been validated by `io_addr_assert`.
- unsafe { self.io_read(address) }.into()
+ let view = io_view_assert::<Self, L::IoType>(self, location.offset());
+ Self::Backend::io_read(view).into()
}
/// Generic infallible write with compile-time bounds check.
@@ -748,13 +767,11 @@ fn read<T, L>(self, location: L) -> T
fn write<T, L>(self, location: L, value: T)
where
L: IoLoc<Self::Target, T>,
- Self: IoCapable<L::IoType>,
+ Self::Backend: IoCapable<L::IoType>,
{
- let address = self.io_addr_assert::<L::IoType>(location.offset());
+ let view = io_view_assert::<Self, L::IoType>(self, location.offset());
let io_value = value.into();
-
- // SAFETY: `address` has been validated by `io_addr_assert`.
- unsafe { self.io_write(io_value, address) }
+ Self::Backend::io_write(view, io_value);
}
/// Generic infallible write of a fully-located register value.
@@ -793,7 +810,7 @@ fn write_reg<T, L, V>(self, value: V)
where
L: IoLoc<Self::Target, T>,
V: LocatedRegister<Self::Target, Location = L, Value = T>,
- Self: IoCapable<L::IoType>,
+ Self::Backend: IoCapable<L::IoType>,
{
let (location, value) = value.into_io_op();
@@ -826,17 +843,13 @@ fn write_reg<T, L, V>(self, value: V)
fn update<T, L, F>(self, location: L, f: F)
where
L: IoLoc<Self::Target, T>,
- Self: IoCapable<L::IoType>,
+ Self::Backend: IoCapable<L::IoType>,
F: FnOnce(T) -> T,
{
- let address = self.io_addr_assert::<L::IoType>(location.offset());
-
- // SAFETY: `address` has been validated by `io_addr_assert`.
- let value: T = unsafe { self.io_read(address) }.into();
+ let view = io_view_assert::<Self, L::IoType>(self, location.offset());
+ let value: T = Self::Backend::io_read(view).into();
let io_value = f(value).into();
-
- // SAFETY: `address` has been validated by `io_addr_assert`.
- unsafe { self.io_write(io_value, address) }
+ Self::Backend::io_write(view, io_value);
}
}
@@ -880,78 +893,78 @@ unsafe impl<T: ?Sized + Sync> Send for Mmio<'_, T> {}
// SAFETY: `Mmio<'_, T>` is conceptually `&T` but in I/O memory.
unsafe impl<T: ?Sized + Sync> Sync for Mmio<'_, T> {}
-impl<T: ?Sized + KnownSize> Io for Mmio<'_, T> {
+impl<'a, T: ?Sized + KnownSize> Io<'a> for Mmio<'a, T> {
+ type Backend = MmioBackend;
type Target = T;
#[inline]
- fn addr(self) -> usize {
- self.ptr.addr()
+ fn as_view(self) -> Mmio<'a, T> {
+ self
}
+}
+
+/// I/O Backend for memory-mapped I/O.
+pub struct MmioBackend;
+
+impl IoBackend for MmioBackend {
+ type View<'a, T: ?Sized + KnownSize> = Mmio<'a, T>;
#[inline]
- fn maxsize(self) -> usize {
- KnownSize::size(self.ptr)
+ fn as_ptr<'a, T: ?Sized + KnownSize>(view: Self::View<'a, T>) -> *mut T {
+ view.ptr
+ }
+
+ #[inline]
+ unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>(
+ _view: Self::View<'a, T>,
+ ptr: *mut U,
+ ) -> Self::View<'a, U> {
+ // INVARIANT: Per safety requirement, `ptr` is projection from `view`, so it is also a valid
+ // memory-mapped I/O region.
+ Mmio {
+ ptr,
+ phantom: PhantomData,
+ }
}
}
-/// Implements [`IoCapable`] on `$mmio` for `$ty` using `$read_fn` and `$write_fn`.
+/// Implements [`IoCapable`] on `$backend` for `$ty` using `$read_fn` and `$write_fn`.
macro_rules! impl_mmio_io_capable {
- ($mmio:ident, $(#[$attr:meta])* $ty:ty, $read_fn:ident, $write_fn:ident) => {
- $(#[$attr])*
- impl<T: ?Sized> IoCapable<$ty> for $mmio<'_, T> {
+ ($backend: ident, $ty:ty, $read_fn:ident, $write_fn:ident) => {
+ impl IoCapable<$ty> for $backend {
#[inline]
- unsafe fn io_read(self, address: usize) -> $ty {
- // SAFETY: By the trait invariant `address` is a valid address for MMIO operations.
- unsafe { bindings::$read_fn(address as *const c_void) }
+ fn io_read(view: <$backend as IoBackend>::View<'_, $ty>) -> $ty {
+ // SAFETY: `$backend::as_ptr(view)` is a valid pointer for MMIO operations for both
+ // `MmioBackend` and `RelaxedMmioBackend`.
+ unsafe { bindings::$read_fn($backend::as_ptr(view).cast_const().cast()) }
}
#[inline]
- unsafe fn io_write(self, value: $ty, address: usize) {
- // SAFETY: By the trait invariant `address` is a valid address for MMIO operations.
- unsafe { bindings::$write_fn(value, address as *mut c_void) }
+ fn io_write(view: <$backend as IoBackend>::View<'_, $ty>, value: $ty) {
+ // SAFETY: `$backend::as_ptr(view)` is a valid pointer for MMIO operations for both
+ // `MmioBackend` and `RelaxedMmioBackend`.
+ unsafe { bindings::$write_fn(value, $backend::as_ptr(view).cast()) }
}
}
};
}
// MMIO regions support 8, 16, and 32-bit accesses.
-impl_mmio_io_capable!(Mmio, u8, readb, writeb);
-impl_mmio_io_capable!(Mmio, u16, readw, writew);
-impl_mmio_io_capable!(Mmio, u32, readl, writel);
+impl_mmio_io_capable!(MmioBackend, u8, readb, writeb);
+impl_mmio_io_capable!(MmioBackend, u16, readw, writew);
+impl_mmio_io_capable!(MmioBackend, u32, readl, writel);
// MMIO regions on 64-bit systems also support 64-bit accesses.
#[cfg(CONFIG_64BIT)]
-impl_mmio_io_capable!(Mmio, u64, readq, writeq);
+impl_mmio_io_capable!(MmioBackend, u64, readq, writeq);
-impl<'a, const SIZE: usize> Io for &'a MmioOwned<SIZE> {
+impl<'a, const SIZE: usize> Io<'a> for &'a MmioOwned<SIZE> {
+ type Backend = MmioBackend;
type Target = Region<SIZE>;
- /// Returns the base address of this mapping.
#[inline]
- fn addr(self) -> usize {
- self.0.addr()
- }
-
- /// Returns the maximum size of this mapping.
- #[inline]
- fn maxsize(self) -> usize {
- self.0.size()
- }
-}
-
-impl<'a, const SIZE: usize, T> IoCapable<T> for &'a MmioOwned<SIZE>
-where
- Mmio<'a, Region<SIZE>>: IoCapable<T>,
-{
- #[inline]
- unsafe fn io_read(self, address: usize) -> T {
- // SAFETY: Per safety requirement.
- unsafe { self.as_view().io_read(address) }
- }
-
- #[inline]
- unsafe fn io_write(self, value: T, address: usize) {
- // SAFETY: Per safety requirement.
- unsafe { self.as_view().io_write(value, address) }
+ fn as_view(self) -> Mmio<'a, Self::Target> {
+ // SAFETY: `Mmio` has same invariant as `MmioOwned`
+ unsafe { Mmio::from_raw(self.0) }
}
}
@@ -967,13 +980,6 @@ pub unsafe fn from_raw(raw: &MmioRaw<Region<SIZE>>) -> &Self {
// SAFETY: `MmioOwned` is a transparent wrapper around `MmioRaw`.
unsafe { &*core::ptr::from_ref(raw).cast() }
}
-
- /// Return a view that covers the full region.
- #[inline]
- pub fn as_view(&self) -> Mmio<'_, Region<SIZE>> {
- // SAFETY: `Mmio` has same invariant as `MmioOwned`.
- unsafe { Mmio::from_raw(self.0) }
- }
}
/// [`Mmio`] but using relaxed accessors.
@@ -992,17 +998,34 @@ fn clone(&self) -> Self {
}
}
-impl<T: ?Sized + KnownSize> Io for RelaxedMmio<'_, T> {
- type Target = T;
+/// I/O Backend for memory-mapped I/O, with relaxed access semantics.
+pub struct RelaxedMmioBackend;
+
+impl IoBackend for RelaxedMmioBackend {
+ type View<'a, T: ?Sized + KnownSize> = RelaxedMmio<'a, T>;
#[inline]
- fn addr(self) -> usize {
- self.0.addr()
+ fn as_ptr<'a, T: ?Sized + KnownSize>(view: Self::View<'a, T>) -> *mut T {
+ MmioBackend::as_ptr(view.0)
}
#[inline]
- fn maxsize(self) -> usize {
- self.0.maxsize()
+ unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>(
+ view: Self::View<'a, T>,
+ ptr: *mut U,
+ ) -> Self::View<'a, U> {
+ // SAFETY: Per safety requirement.
+ RelaxedMmio(unsafe { MmioBackend::project_view(view.0, ptr) })
+ }
+}
+
+impl<'a, T: ?Sized + KnownSize> Io<'a> for RelaxedMmio<'a, T> {
+ type Backend = RelaxedMmioBackend;
+ type Target = T;
+
+ #[inline]
+ fn as_view(self) -> RelaxedMmio<'a, T> {
+ self
}
}
@@ -1035,14 +1058,9 @@ pub fn relaxed(self) -> RelaxedMmio<'a, T> {
}
// MMIO regions support 8, 16, and 32-bit accesses.
-impl_mmio_io_capable!(RelaxedMmio, u8, readb_relaxed, writeb_relaxed);
-impl_mmio_io_capable!(RelaxedMmio, u16, readw_relaxed, writew_relaxed);
-impl_mmio_io_capable!(RelaxedMmio, u32, readl_relaxed, writel_relaxed);
+impl_mmio_io_capable!(RelaxedMmioBackend, u8, readb_relaxed, writeb_relaxed);
+impl_mmio_io_capable!(RelaxedMmioBackend, u16, readw_relaxed, writew_relaxed);
+impl_mmio_io_capable!(RelaxedMmioBackend, u32, readl_relaxed, writel_relaxed);
// MMIO regions on 64-bit systems also support 64-bit accesses.
-impl_mmio_io_capable!(
- RelaxedMmio,
- #[cfg(CONFIG_64BIT)]
- u64,
- readq_relaxed,
- writeq_relaxed
-);
+#[cfg(CONFIG_64BIT)]
+impl_mmio_io_capable!(RelaxedMmioBackend, u64, readq_relaxed, writeq_relaxed);
diff --git a/rust/kernel/pci/io.rs b/rust/kernel/pci/io.rs
index 89f4bb483a7f..e67c1e3694fb 100644
--- a/rust/kernel/pci/io.rs
+++ b/rust/kernel/pci/io.rs
@@ -9,6 +9,7 @@
devres::Devres,
io::{
Io,
+ IoBackend,
IoCapable,
MmioOwned,
MmioRaw,
@@ -84,32 +85,57 @@ unsafe impl<T: ?Sized + Sync> Send for ConfigSpace<'_, T> {}
// SAFETY: `ConfigSpace<'_, T>` is conceptually `&T` but in I/O memory.
unsafe impl<T: ?Sized + Sync> Sync for ConfigSpace<'_, T> {}
+/// I/O Backend for PCI configuration space.
+pub struct ConfigSpaceBackend;
+
+impl IoBackend for ConfigSpaceBackend {
+ type View<'a, T: ?Sized + KnownSize> = ConfigSpace<'a, T>;
+
+ #[inline]
+ fn as_ptr<'a, T: ?Sized + KnownSize>(view: ConfigSpace<'a, T>) -> *mut T {
+ view.ptr
+ }
+
+ #[inline]
+ unsafe fn project_view<'a, T: ?Sized + KnownSize, U: ?Sized + KnownSize>(
+ view: Self::View<'a, T>,
+ ptr: *mut U,
+ ) -> Self::View<'a, U> {
+ // INVARIANT: Per safety requirement.
+ ConfigSpace {
+ pdev: view.pdev,
+ ptr,
+ }
+ }
+}
+
/// Implements [`IoCapable`] on [`ConfigSpace`] for `$ty` using `$read_fn` and `$write_fn`.
macro_rules! impl_config_space_io_capable {
($ty:ty, $read_fn:ident, $write_fn:ident) => {
- impl<'a, T: ?Sized> IoCapable<$ty> for ConfigSpace<'a, T> {
- unsafe fn io_read(self, address: usize) -> $ty {
+ impl IoCapable<$ty> for ConfigSpaceBackend {
+ fn io_read(view: ConfigSpace<'_, $ty>) -> $ty {
+ // CAST: The offset is cast to `i32` because the C functions expect a 32-bit
+ // signed offset parameter. PCI configuration space size is at most 4096 bytes,
+ // so the value always fits within `i32` without truncation or sign change.
+ let addr = view.ptr.addr() as i32;
+
let mut val: $ty = 0;
// Return value from C function is ignored in infallible accessors.
- let _ret =
- // SAFETY: By the type invariant `self.pdev` is a valid address.
- // CAST: The offset is cast to `i32` because the C functions expect a 32-bit
- // signed offset parameter. PCI configuration space size is at most 4096 bytes,
- // so the value always fits within `i32` without truncation or sign change.
- unsafe { bindings::$read_fn(self.pdev.as_raw(), address as i32, &mut val) };
-
+ // SAFETY: By the type invariant `pdev` is a valid address.
+ let _ = unsafe { bindings::$read_fn(view.pdev.as_raw(), addr, &mut val) };
val
}
- unsafe fn io_write(self, value: $ty, address: usize) {
+ fn io_write(view: ConfigSpace<'_, $ty>, value: $ty) {
+ // CAST: The offset is cast to `i32` because the C functions expect a 32-bit
+ // signed offset parameter. PCI configuration space size is at most 4096 bytes,
+ // so the value always fits within `i32` without truncation or sign change.
+ let addr = view.ptr.addr() as i32;
+
// Return value from C function is ignored in infallible accessors.
- let _ret =
- // SAFETY: By the type invariant `self.pdev` is a valid address.
- // CAST: The offset is cast to `i32` because the C functions expect a 32-bit
- // signed offset parameter. PCI configuration space size is at most 4096 bytes,
- // so the value always fits within `i32` without truncation or sign change.
- unsafe { bindings::$write_fn(self.pdev.as_raw(), address as i32, value) };
+ // SAFETY: By the type invariant `pdev` is a valid address.
+ let _ = unsafe { bindings::$write_fn(view.pdev.as_raw(), addr, value) };
}
}
};
@@ -120,17 +146,13 @@ unsafe fn io_write(self, value: $ty, address: usize) {
impl_config_space_io_capable!(u16, pci_read_config_word, pci_write_config_word);
impl_config_space_io_capable!(u32, pci_read_config_dword, pci_write_config_dword);
-impl<'a, T: ?Sized + KnownSize> Io for ConfigSpace<'a, T> {
+impl<'a, T: ?Sized + KnownSize> Io<'a> for ConfigSpace<'a, T> {
+ type Backend = ConfigSpaceBackend;
type Target = T;
#[inline]
- fn addr(self) -> usize {
- self.ptr.addr()
- }
-
- #[inline]
- fn maxsize(self) -> usize {
- KnownSize::size(self.ptr)
+ fn as_view(self) -> ConfigSpace<'a, T> {
+ self
}
}
--
2.54.0
^ permalink raw reply related
* [PATCH v5 10/20] pwm: th1520: remove unnecessary `deref`
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
`Deref` is automatic and should normally not be used directly.
Also, `IoMem` is going to be implementing `Io` directly, so it will no
longer to be implementing `Deref`.
Reported-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://rust-for-linux.zulipchat.com/#narrow/channel/291565-Help/topic/.E2.9C.94.20Projection.20in.20dma.20bus.20address.20space/near/606672061
Signed-off-by: Gary Guo <gary@garyguo.net>
---
drivers/pwm/pwm_th1520.rs | 7 ++-----
1 file changed, 2 insertions(+), 5 deletions(-)
diff --git a/drivers/pwm/pwm_th1520.rs b/drivers/pwm/pwm_th1520.rs
index 3e3fa51ccef9..022338d17218 100644
--- a/drivers/pwm/pwm_th1520.rs
+++ b/drivers/pwm/pwm_th1520.rs
@@ -20,7 +20,6 @@
//! this method is not used in this driver.
//!
-use core::ops::Deref;
use kernel::{
clk::Clk,
device::{Bound, Core, Device},
@@ -213,8 +212,7 @@ fn read_waveform(
) -> Result<Self::WfHw> {
let data = chip.drvdata();
let hwpwm = pwm.hwpwm();
- let iomem_accessor = data.iomem.access(parent_dev)?;
- let iomap = iomem_accessor.deref();
+ let iomap = data.iomem.access(parent_dev)?;
let ctrl = iomap.try_read32(th1520_pwm_ctrl(hwpwm))?;
let period_cycles = iomap.try_read32(th1520_pwm_per(hwpwm))?;
@@ -248,8 +246,7 @@ fn write_waveform(
) -> Result {
let data = chip.drvdata();
let hwpwm = pwm.hwpwm();
- let iomem_accessor = data.iomem.access(parent_dev)?;
- let iomap = iomem_accessor.deref();
+ let iomap = data.iomem.access(parent_dev)?;
let duty_cycles = iomap.try_read32(th1520_pwm_fp(hwpwm))?;
let was_enabled = duty_cycles != 0;
--
2.54.0
^ permalink raw reply related
* [PATCH v5 03/20] rust: io: restrict untyped IO access and `register!` to `Region`
From: Gary Guo @ 2026-06-26 14:45 UTC (permalink / raw)
To: Alice Ryhl, Daniel Almeida, Greg Kroah-Hartman, Rafael J. Wysocki,
Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Tamir Duberstein,
Onur Özkan, Bjorn Helgaas, Krzysztof Wilczyński,
Abdiel Janulgue, Robin Murphy, Alexandre Courbot, David Airlie,
Simona Vetter, Michal Wilczynski, Uwe Kleine-König
Cc: Danilo Krummrich, driver-core, rust-for-linux, linux-kernel,
linux-pci, nova-gpu, dri-devel, linux-pwm
In-Reply-To: <20260626-io_projection-v5-0-d0961471ae50@garyguo.net>
Currently the `Io` trait exposes a bunch of untyped IO accesses, but if the
`Io` region itself is typed, then it might be weird to have
let io: Mmio<u32> = /* ... */;
io.read8(1);
while not unsound, it is surely strange. Thus, restrict the untyped methods
and also the register macro to `Region` type only.
Implement it by adding a generic type to `IoLoc` indicating allowed base
types. This also paves the way to add typed register blocks in the future;
for example, we could use this mechanism to block driver A's `register!()`
generated macro from being used on driver B's MMIO. The same mechanism
could be used for relative IO registers. These are future opportunities,
and for now restrict everything to require `IoLoc<Region<SIZE>, _>`.
Suggested-by: Alexandre Courbot <acourbot@nvidia.com>
Link: https://lore.kernel.org/rust-for-linux/DHLB3RO3OSF5.2R7F27U99BKLN@nvidia.com/
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Gary Guo <gary@garyguo.net>
---
rust/kernel/io.rs | 49 +++++++++++++++++++++++++++++++---------------
rust/kernel/io/register.rs | 20 ++++++++++---------
2 files changed, 44 insertions(+), 25 deletions(-)
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index d821ee48ed31..87141eb07056 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -243,15 +243,16 @@ pub trait IoCapable<T> {
/// (for primitive types like [`u32`]) and typed ones (like those generated by the [`register!`]
/// macro).
///
-/// An `IoLoc<T>` carries three pieces of information:
+/// An `IoLoc<Base, T>` carries the following pieces of information:
///
+/// - The valid `Base` to operate on. For most registers, this should be [`Region`].
/// - The offset to access (returned by [`IoLoc::offset`]),
/// - The width of the access (determined by [`IoLoc::IoType`]),
/// - The type `T` in which the raw data is returned or provided.
///
/// `T` and `IoLoc::IoType` may differ: for instance, a typed register has `T` = the register type
/// with its bitfields, and `IoType` = its backing primitive (e.g. `u32`).
-pub trait IoLoc<T> {
+pub trait IoLoc<Base: ?Sized, T> {
/// Size ([`u8`], [`u16`], etc) of the I/O performed on the returned [`offset`](IoLoc::offset).
type IoType: Into<T> + From<T>;
@@ -259,12 +260,12 @@ pub trait IoLoc<T> {
fn offset(self) -> usize;
}
-/// Implements [`IoLoc<$ty>`] for [`usize`], allowing [`usize`] to be used as a parameter of
-/// [`Io::read`] and [`Io::write`].
+/// Implements [`IoLoc<Region<SIZE>, $ty>`] for [`usize`], allowing [`usize`] to be used as a
+/// parameter of [`Io::read`] and [`Io::write`].
macro_rules! impl_usize_ioloc {
($($ty:ty),*) => {
$(
- impl IoLoc<$ty> for usize {
+ impl<const SIZE: usize> IoLoc<Region<SIZE>, $ty> for usize {
type IoType = $ty;
#[inline(always)]
@@ -338,6 +339,7 @@ fn io_addr<U>(&self, offset: usize) -> Result<usize> {
#[inline(always)]
fn try_read8(&self, offset: usize) -> Result<u8>
where
+ usize: IoLoc<Self::Target, u8, IoType = u8>,
Self: IoCapable<u8>,
{
self.try_read(offset)
@@ -347,6 +349,7 @@ fn try_read8(&self, offset: usize) -> Result<u8>
#[inline(always)]
fn try_read16(&self, offset: usize) -> Result<u16>
where
+ usize: IoLoc<Self::Target, u16, IoType = u16>,
Self: IoCapable<u16>,
{
self.try_read(offset)
@@ -356,6 +359,7 @@ fn try_read16(&self, offset: usize) -> Result<u16>
#[inline(always)]
fn try_read32(&self, offset: usize) -> Result<u32>
where
+ usize: IoLoc<Self::Target, u32, IoType = u32>,
Self: IoCapable<u32>,
{
self.try_read(offset)
@@ -365,6 +369,7 @@ fn try_read32(&self, offset: usize) -> Result<u32>
#[inline(always)]
fn try_read64(&self, offset: usize) -> Result<u64>
where
+ usize: IoLoc<Self::Target, u64, IoType = u64>,
Self: IoCapable<u64>,
{
self.try_read(offset)
@@ -374,6 +379,7 @@ fn try_read64(&self, offset: usize) -> Result<u64>
#[inline(always)]
fn try_write8(&self, value: u8, offset: usize) -> Result
where
+ usize: IoLoc<Self::Target, u8, IoType = u8>,
Self: IoCapable<u8>,
{
self.try_write(offset, value)
@@ -383,6 +389,7 @@ fn try_write8(&self, value: u8, offset: usize) -> Result
#[inline(always)]
fn try_write16(&self, value: u16, offset: usize) -> Result
where
+ usize: IoLoc<Self::Target, u16, IoType = u16>,
Self: IoCapable<u16>,
{
self.try_write(offset, value)
@@ -392,6 +399,7 @@ fn try_write16(&self, value: u16, offset: usize) -> Result
#[inline(always)]
fn try_write32(&self, value: u32, offset: usize) -> Result
where
+ usize: IoLoc<Self::Target, u32, IoType = u32>,
Self: IoCapable<u32>,
{
self.try_write(offset, value)
@@ -401,6 +409,7 @@ fn try_write32(&self, value: u32, offset: usize) -> Result
#[inline(always)]
fn try_write64(&self, value: u64, offset: usize) -> Result
where
+ usize: IoLoc<Self::Target, u64, IoType = u64>,
Self: IoCapable<u64>,
{
self.try_write(offset, value)
@@ -410,6 +419,7 @@ fn try_write64(&self, value: u64, offset: usize) -> Result
#[inline(always)]
fn read8(&self, offset: usize) -> u8
where
+ usize: IoLoc<Self::Target, u8, IoType = u8>,
Self: IoCapable<u8>,
{
self.read(offset)
@@ -419,6 +429,7 @@ fn read8(&self, offset: usize) -> u8
#[inline(always)]
fn read16(&self, offset: usize) -> u16
where
+ usize: IoLoc<Self::Target, u16, IoType = u16>,
Self: IoCapable<u16>,
{
self.read(offset)
@@ -428,6 +439,7 @@ fn read16(&self, offset: usize) -> u16
#[inline(always)]
fn read32(&self, offset: usize) -> u32
where
+ usize: IoLoc<Self::Target, u32, IoType = u32>,
Self: IoCapable<u32>,
{
self.read(offset)
@@ -437,6 +449,7 @@ fn read32(&self, offset: usize) -> u32
#[inline(always)]
fn read64(&self, offset: usize) -> u64
where
+ usize: IoLoc<Self::Target, u64, IoType = u64>,
Self: IoCapable<u64>,
{
self.read(offset)
@@ -446,6 +459,7 @@ fn read64(&self, offset: usize) -> u64
#[inline(always)]
fn write8(&self, value: u8, offset: usize)
where
+ usize: IoLoc<Self::Target, u8, IoType = u8>,
Self: IoCapable<u8>,
{
self.write(offset, value)
@@ -455,6 +469,7 @@ fn write8(&self, value: u8, offset: usize)
#[inline(always)]
fn write16(&self, value: u16, offset: usize)
where
+ usize: IoLoc<Self::Target, u16, IoType = u16>,
Self: IoCapable<u16>,
{
self.write(offset, value)
@@ -464,6 +479,7 @@ fn write16(&self, value: u16, offset: usize)
#[inline(always)]
fn write32(&self, value: u32, offset: usize)
where
+ usize: IoLoc<Self::Target, u32, IoType = u32>,
Self: IoCapable<u32>,
{
self.write(offset, value)
@@ -473,6 +489,7 @@ fn write32(&self, value: u32, offset: usize)
#[inline(always)]
fn write64(&self, value: u64, offset: usize)
where
+ usize: IoLoc<Self::Target, u64, IoType = u64>,
Self: IoCapable<u64>,
{
self.write(offset, value)
@@ -503,7 +520,7 @@ fn write64(&self, value: u64, offset: usize)
#[inline(always)]
fn try_read<T, L>(&self, location: L) -> Result<T>
where
- L: IoLoc<T>,
+ L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
{
let address = self.io_addr::<L::IoType>(location.offset())?;
@@ -537,7 +554,7 @@ fn try_read<T, L>(&self, location: L) -> Result<T>
#[inline(always)]
fn try_write<T, L>(&self, location: L, value: T) -> Result
where
- L: IoLoc<T>,
+ L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
{
let address = self.io_addr::<L::IoType>(location.offset())?;
@@ -583,8 +600,8 @@ fn try_write<T, L>(&self, location: L, value: T) -> Result
#[inline(always)]
fn try_write_reg<T, L, V>(&self, value: V) -> Result
where
- L: IoLoc<T>,
- V: LocatedRegister<Location = L, Value = T>,
+ L: IoLoc<Self::Target, T>,
+ V: LocatedRegister<Self::Target, Location = L, Value = T>,
Self: IoCapable<L::IoType>,
{
let (location, value) = value.into_io_op();
@@ -616,7 +633,7 @@ fn try_write_reg<T, L, V>(&self, value: V) -> Result
#[inline(always)]
fn try_update<T, L, F>(&self, location: L, f: F) -> Result
where
- L: IoLoc<T>,
+ L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
F: FnOnce(T) -> T,
{
@@ -655,7 +672,7 @@ fn try_update<T, L, F>(&self, location: L, f: F) -> Result
#[inline(always)]
fn read<T, L>(&self, location: L) -> T
where
- L: IoLoc<T>,
+ L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
{
let address = self.io_addr_assert::<L::IoType>(location.offset());
@@ -687,7 +704,7 @@ fn read<T, L>(&self, location: L) -> T
#[inline(always)]
fn write<T, L>(&self, location: L, value: T)
where
- L: IoLoc<T>,
+ L: IoLoc<Self::Target, T>,
Self: IoCapable<L::IoType>,
{
let address = self.io_addr_assert::<L::IoType>(location.offset());
@@ -730,8 +747,8 @@ fn write<T, L>(&self, location: L, value: T)
#[inline(always)]
fn write_reg<T, L, V>(&self, value: V)
where
- L: IoLoc<T>,
- V: LocatedRegister<Location = L, Value = T>,
+ L: IoLoc<Self::Target, T>,
+ V: LocatedRegister<Self::Target, Location = L, Value = T>,
Self: IoCapable<L::IoType>,
{
let (location, value) = value.into_io_op();
@@ -763,8 +780,8 @@ fn write_reg<T, L, V>(&self, value: V)
#[inline(always)]
fn update<T, L, F>(&self, location: L, f: F)
where
- L: IoLoc<T>,
- Self: IoCapable<L::IoType> + Sized,
+ L: IoLoc<Self::Target, T>,
+ Self: IoCapable<L::IoType>,
F: FnOnce(T) -> T,
{
let address = self.io_addr_assert::<L::IoType>(location.offset());
diff --git a/rust/kernel/io/register.rs b/rust/kernel/io/register.rs
index f924c7c7c1db..3122b17098ee 100644
--- a/rust/kernel/io/register.rs
+++ b/rust/kernel/io/register.rs
@@ -113,6 +113,8 @@
io::IoLoc, //
};
+use super::Region;
+
/// Trait implemented by all registers.
pub trait Register: Sized {
/// Backing primitive type of the register.
@@ -129,7 +131,7 @@ pub trait FixedRegister: Register {}
/// Allows `()` to be used as the `location` parameter of [`Io::write`](super::Io::write) when
/// passing a [`FixedRegister`] value.
-impl<T> IoLoc<T> for ()
+impl<const SIZE: usize, T> IoLoc<Region<SIZE>, T> for ()
where
T: FixedRegister,
{
@@ -143,7 +145,7 @@ fn offset(self) -> usize {
/// A [`FixedRegister`] carries its location in its type. Thus `FixedRegister` values can be used
/// as an [`IoLoc`].
-impl<T> IoLoc<T> for T
+impl<const SIZE: usize, T> IoLoc<Region<SIZE>, T> for T
where
T: FixedRegister,
{
@@ -168,7 +170,7 @@ pub const fn new() -> Self {
}
}
-impl<T> IoLoc<T> for FixedRegisterLoc<T>
+impl<const SIZE: usize, T> IoLoc<Region<SIZE>, T> for FixedRegisterLoc<T>
where
T: FixedRegister,
{
@@ -239,7 +241,7 @@ const fn offset(self) -> usize {
}
}
-impl<T, B> IoLoc<T> for RelativeRegisterLoc<T, B>
+impl<const SIZE: usize, T, B> IoLoc<Region<SIZE>, T> for RelativeRegisterLoc<T, B>
where
T: RelativeRegister,
B: RegisterBase<T::BaseFamily> + ?Sized,
@@ -283,7 +285,7 @@ pub fn try_new(idx: usize) -> Option<Self> {
}
}
-impl<T> IoLoc<T> for RegisterArrayLoc<T>
+impl<const SIZE: usize, T> IoLoc<Region<SIZE>, T> for RegisterArrayLoc<T>
where
T: RegisterArray,
{
@@ -370,7 +372,7 @@ pub fn try_at(self, idx: usize) -> Option<RelativeRegisterArrayLoc<T, B>> {
}
}
-impl<T, B> IoLoc<T> for RelativeRegisterArrayLoc<T, B>
+impl<const SIZE: usize, T, B> IoLoc<Region<SIZE>, T> for RelativeRegisterArrayLoc<T, B>
where
T: RelativeRegisterArray,
B: RegisterBase<T::BaseFamily> + ?Sized,
@@ -387,18 +389,18 @@ fn offset(self) -> usize {
/// which to write it.
///
/// Implementors can be used with [`Io::write_reg`](super::Io::write_reg).
-pub trait LocatedRegister {
+pub trait LocatedRegister<Base: ?Sized> {
/// Register value to write.
type Value: Register;
/// Full location information at which to write the value.
- type Location: IoLoc<Self::Value>;
+ type Location: IoLoc<Base, Self::Value>;
/// Consumes `self` and returns a `(location, value)` tuple describing a valid I/O write
/// operation.
fn into_io_op(self) -> (Self::Location, Self::Value);
}
-impl<T> LocatedRegister for T
+impl<const SIZE: usize, T> LocatedRegister<Region<SIZE>> for T
where
T: FixedRegister,
{
--
2.54.0
^ permalink raw reply related
page: next (older)
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox