rust/kernel/dma.rs | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+)
The base dma address of `Coherent` and `CoherentHandle` is a bare
`DmaAddress` integer so any arithmetic, a driver does on it is unchecked
and can potentially go past the end of the allocation or overflow.
Add a `dma::Range` type that couples a base `DmaAddress` with a length
and only hands out addresses and sub-ranges within `[start, start + len)`
with all arithmetics checked against both the length and the overflow of
of the underlying `dma_addr_t`. Let `Coherent` and `CoherentHandle`
provide the `Range` covering their allocation.
Suggested-by: Danilo Krummrich <dakr@kernel.org>
Link: https://github.com/Rust-for-Linux/linux/issues/1248
Signed-off-by: Vasileios Almpanis <vasilisalmpanis@gmail.com>
---
This is one of my first rust-for-linux patches, so any suggestions are
extremely welcome. Some words about the decisions taken:
- I chose lengths offsets to be `DmaAddress` instead of usize since the
bus space can be 64-bit on 32-bit CPUS.
- The constructor returns EOVERFLOW for `dma_addr_t` overflow, while
out-of-bounds requests return EINVAL; happy to use a single error
code if preferred.
- `dma_range()` is added to both `Coherent` and `CoherentHandle` so the
type has users from the start. I could split it into a follow-up if
that is preferred.
Tested with `make rustdoc`, `make rustfmtcheck`, `CLIPPY=1`, and the
KUnit doctests `rust_doctests_kernel`.
---
rust/kernel/dma.rs | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 174 insertions(+)
diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
index 200def84fb69e006bca0b1c578bac9f1dc8da708..e65e99ae4d915ac2e385df8b72fc518c07e4c82d 100644
--- a/rust/kernel/dma.rs
+++ b/rust/kernel/dma.rs
@@ -41,6 +41,142 @@
/// Note that this may be `u64` even on 32-bit architectures.
pub type DmaAddress = bindings::dma_addr_t;
+/// A range of DMA addresses.
+///
+/// Couples a base [`DmaAddress`] with the length in bytes of the region it belongs to,
+/// representing the half-open range `[start, start + len)` of DMA addresses.
+///
+/// Unlike a bare [`DmaAddress`], a [`Range`] only hands out addresses and sub-ranges that are
+/// guaranteed to lie within `[start, start + len)`; all arithmetic is checked against both the
+/// length of the range and overflow of the underlying [`DmaAddress`].
+///
+/// # Invariants
+///
+/// `start + len` does not overflow [`DmaAddress`].
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Range {
+ start: DmaAddress,
+ len: DmaAddress,
+}
+
+impl Range {
+ /// Creates a new [`Range`] of `len` bytes, starting at `start`.
+ ///
+ /// Returns [`EOVERFLOW`] if `start + len` overflows [`DmaAddress`].
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::dma::{DmaAddress, Range};
+ ///
+ /// let range = Range::new(0x1000, 0x200)?;
+ /// assert_eq!(range.start(), 0x1000);
+ /// assert_eq!(range.end(), 0x1200);
+ /// assert_eq!(range.len(), 0x200);
+ ///
+ /// assert!(Range::new(DmaAddress::MAX, 1).is_err());
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ pub const fn new(start: DmaAddress, len: DmaAddress) -> Result<Self> {
+ if start.checked_add(len).is_none() {
+ return Err(EOVERFLOW);
+ }
+
+ // INVARIANT: We just checked that `start + len` does not overflow `DmaAddress`.
+ Ok(Self { start, len })
+ }
+
+ /// Returns the first address of the range.
+ #[inline]
+ pub const fn start(&self) -> DmaAddress {
+ self.start
+ }
+
+ /// Returns the first address after the end of the range.
+ #[inline]
+ pub const fn end(&self) -> DmaAddress {
+ // By the type invariant, `start + len` does not overflow `DmaAddress`.
+ self.start + self.len
+ }
+
+ /// Returns the length of the range in bytes.
+ #[inline]
+ pub const fn len(&self) -> DmaAddress {
+ self.len
+ }
+
+ /// Returns `true` if the range is empty.
+ #[inline]
+ pub const fn is_empty(&self) -> bool {
+ self.len == 0
+ }
+
+ /// Returns the address at `offset` bytes into the range.
+ ///
+ /// The returned address is guaranteed to lie within the range; returns [`EINVAL`] if `offset`
+ /// is not smaller than the length of the range.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::dma::Range;
+ ///
+ /// let range = Range::new(0x1000, 0x200)?;
+ ///
+ /// assert_eq!(range.address(0)?, 0x1000);
+ /// assert_eq!(range.address(0x1ff)?, 0x11ff);
+ /// assert!(range.address(0x200).is_err());
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ pub const fn address(&self, offset: DmaAddress) -> Result<DmaAddress> {
+ if offset >= self.len {
+ return Err(EINVAL);
+ }
+
+ // By the type invariant, `start + offset < start + len` does not overflow `DmaAddress`.
+ Ok(self.start + offset)
+ }
+
+ /// Returns the sub-range of `len` bytes, starting `offset` bytes into the range.
+ ///
+ /// The returned range is guaranteed to lie within the range; returns [`EINVAL`] if
+ /// `offset + len` overflows [`DmaAddress`] or exceeds the length of the range.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::dma::Range;
+ ///
+ /// let range = Range::new(0x1000, 0x200)?;
+ ///
+ /// let sub = range.subrange(0x100, 0x80)?;
+ /// assert_eq!(sub.start(), 0x1100);
+ /// assert_eq!(sub.end(), 0x1180);
+ ///
+ /// assert!(range.subrange(0x100, 0x101).is_err());
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ pub const fn subrange(&self, offset: DmaAddress, len: DmaAddress) -> Result<Self> {
+ let Some(end) = offset.checked_add(len) else {
+ return Err(EINVAL);
+ };
+
+ if end > self.len {
+ return Err(EINVAL);
+ }
+
+ // INVARIANT: `start + offset + len <= start + self.len`, which by the type invariant of
+ // `self` does not overflow `DmaAddress`.
+ Ok(Self {
+ start: self.start + offset,
+ len,
+ })
+ }
+}
+
/// Trait to be implemented by DMA capable bus devices.
///
/// The [`dma::Device`](Device) trait should be implemented by bus specific device representations,
@@ -626,6 +762,25 @@ pub fn dma_handle(&self) -> DmaAddress {
self.dma_handle
}
+ /// Returns the [`Range`] of DMA addresses covering this allocation.
+ ///
+ /// Unlike [`Self::dma_handle`], which hands out the base address as a bare integer, the
+ /// returned [`Range`] couples the base address with the size of the allocation, such that
+ /// any offset arithmetic performed on it is checked.
+ #[inline]
+ pub fn dma_range(&self) -> Range {
+ // INVARIANT: By the type invariants of `Self`, `dma_handle` is the DMA address base of an
+ // allocated region of `self.size()` bytes; the DMA API guarantees that a mapped region
+ // never wraps the DMA address space, hence `dma_handle + size` does not overflow
+ // `DmaAddress`.
+ Range {
+ start: self.dma_handle,
+ // CAST: `usize` always fits in `DmaAddress`, which is at least 32 bits wide and
+ // always 64 bits wide on 64-bit architectures.
+ len: self.size() as DmaAddress,
+ }
+ }
+
/// Returns a reference to the data in the region.
///
/// # Safety
@@ -1101,6 +1256,25 @@ pub fn dma_handle(&self) -> DmaAddress {
self.dma_handle
}
+ /// Returns the [`Range`] of DMA addresses covering this allocation.
+ ///
+ /// Unlike [`Self::dma_handle`], which hands out the base address as a bare integer, the
+ /// returned [`Range`] couples the base address with the size of the allocation, such that
+ /// any offset arithmetic performed on it is checked.
+ #[inline]
+ pub fn dma_range(&self) -> Range {
+ // INVARIANT: By the type invariants of `Self`, `dma_handle` is the DMA address base of an
+ // allocated region of `self.size` bytes; the DMA API guarantees that a mapped region
+ // never wraps the DMA address space, hence `dma_handle + size` does not overflow
+ // `DmaAddress`.
+ Range {
+ start: self.dma_handle,
+ // CAST: `usize` always fits in `DmaAddress`, which is at least 32 bits wide and
+ // always 64 bits wide on 64-bit architectures.
+ len: self.size as DmaAddress,
+ }
+ }
+
/// Returns the size in bytes of this allocation.
#[inline]
pub fn size(&self) -> usize {
---
base-commit: dc01dfb37b34beeefcfe1c3055364d41a4070c7e
change-id: 20260805-dma-7c5330baadb6
Best regards,
--
Vasileios Almpanis <vasilisalmpanis@gmail.com>On 2026-08-06 8:46 am, Vasileios Almpanis wrote:
> The base dma address of `Coherent` and `CoherentHandle` is a bare
> `DmaAddress` integer so any arithmetic, a driver does on it is unchecked
> and can potentially go past the end of the allocation or overflow.
>
> Add a `dma::Range` type that couples a base `DmaAddress` with a length
> and only hands out addresses and sub-ranges within `[start, start + len)`
> with all arithmetics checked against both the length and the overflow of
> of the underlying `dma_addr_t`. Let `Coherent` and `CoherentHandle`
> provide the `Range` covering their allocation.
>
> Suggested-by: Danilo Krummrich <dakr@kernel.org>
> Link: https://github.com/Rust-for-Linux/linux/issues/1248
> Signed-off-by: Vasileios Almpanis <vasilisalmpanis@gmail.com>
> ---
> This is one of my first rust-for-linux patches, so any suggestions are
> extremely welcome. Some words about the decisions taken:
>
> - I chose lengths offsets to be `DmaAddress` instead of usize since the
> bus space can be 64-bit on 32-bit CPUS.
The base address may be 64-bit, but the underlying dma_alloc_*/dma_map_*
APIs all express lengths in size_t, so we shouldn't need to accommodate
anything larger in Rust either. Sizes-as-address-types always seem a bit
weird and clunky (lookin' at you, resource_size_t...), so probably
better avoided if not absolutely necessary, IMO.
Thanks,
Robin.
> - The constructor returns EOVERFLOW for `dma_addr_t` overflow, while
> out-of-bounds requests return EINVAL; happy to use a single error
> code if preferred.
>
> - `dma_range()` is added to both `Coherent` and `CoherentHandle` so the
> type has users from the start. I could split it into a follow-up if
> that is preferred.
>
> Tested with `make rustdoc`, `make rustfmtcheck`, `CLIPPY=1`, and the
> KUnit doctests `rust_doctests_kernel`.
> ---
> rust/kernel/dma.rs | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 174 insertions(+)
>
> diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
> index 200def84fb69e006bca0b1c578bac9f1dc8da708..e65e99ae4d915ac2e385df8b72fc518c07e4c82d 100644
> --- a/rust/kernel/dma.rs
> +++ b/rust/kernel/dma.rs
> @@ -41,6 +41,142 @@
> /// Note that this may be `u64` even on 32-bit architectures.
> pub type DmaAddress = bindings::dma_addr_t;
>
> +/// A range of DMA addresses.
> +///
> +/// Couples a base [`DmaAddress`] with the length in bytes of the region it belongs to,
> +/// representing the half-open range `[start, start + len)` of DMA addresses.
> +///
> +/// Unlike a bare [`DmaAddress`], a [`Range`] only hands out addresses and sub-ranges that are
> +/// guaranteed to lie within `[start, start + len)`; all arithmetic is checked against both the
> +/// length of the range and overflow of the underlying [`DmaAddress`].
> +///
> +/// # Invariants
> +///
> +/// `start + len` does not overflow [`DmaAddress`].
> +#[derive(Clone, Copy, Debug, PartialEq, Eq)]
> +pub struct Range {
> + start: DmaAddress,
> + len: DmaAddress,
> +}
> +
> +impl Range {
> + /// Creates a new [`Range`] of `len` bytes, starting at `start`.
> + ///
> + /// Returns [`EOVERFLOW`] if `start + len` overflows [`DmaAddress`].
> + ///
> + /// # Examples
> + ///
> + /// ```
> + /// use kernel::dma::{DmaAddress, Range};
> + ///
> + /// let range = Range::new(0x1000, 0x200)?;
> + /// assert_eq!(range.start(), 0x1000);
> + /// assert_eq!(range.end(), 0x1200);
> + /// assert_eq!(range.len(), 0x200);
> + ///
> + /// assert!(Range::new(DmaAddress::MAX, 1).is_err());
> + /// # Ok::<(), Error>(())
> + /// ```
> + #[inline]
> + pub const fn new(start: DmaAddress, len: DmaAddress) -> Result<Self> {
> + if start.checked_add(len).is_none() {
> + return Err(EOVERFLOW);
> + }
> +
> + // INVARIANT: We just checked that `start + len` does not overflow `DmaAddress`.
> + Ok(Self { start, len })
> + }
> +
> + /// Returns the first address of the range.
> + #[inline]
> + pub const fn start(&self) -> DmaAddress {
> + self.start
> + }
> +
> + /// Returns the first address after the end of the range.
> + #[inline]
> + pub const fn end(&self) -> DmaAddress {
> + // By the type invariant, `start + len` does not overflow `DmaAddress`.
> + self.start + self.len
> + }
> +
> + /// Returns the length of the range in bytes.
> + #[inline]
> + pub const fn len(&self) -> DmaAddress {
> + self.len
> + }
> +
> + /// Returns `true` if the range is empty.
> + #[inline]
> + pub const fn is_empty(&self) -> bool {
> + self.len == 0
> + }
> +
> + /// Returns the address at `offset` bytes into the range.
> + ///
> + /// The returned address is guaranteed to lie within the range; returns [`EINVAL`] if `offset`
> + /// is not smaller than the length of the range.
> + ///
> + /// # Examples
> + ///
> + /// ```
> + /// use kernel::dma::Range;
> + ///
> + /// let range = Range::new(0x1000, 0x200)?;
> + ///
> + /// assert_eq!(range.address(0)?, 0x1000);
> + /// assert_eq!(range.address(0x1ff)?, 0x11ff);
> + /// assert!(range.address(0x200).is_err());
> + /// # Ok::<(), Error>(())
> + /// ```
> + #[inline]
> + pub const fn address(&self, offset: DmaAddress) -> Result<DmaAddress> {
> + if offset >= self.len {
> + return Err(EINVAL);
> + }
> +
> + // By the type invariant, `start + offset < start + len` does not overflow `DmaAddress`.
> + Ok(self.start + offset)
> + }
> +
> + /// Returns the sub-range of `len` bytes, starting `offset` bytes into the range.
> + ///
> + /// The returned range is guaranteed to lie within the range; returns [`EINVAL`] if
> + /// `offset + len` overflows [`DmaAddress`] or exceeds the length of the range.
> + ///
> + /// # Examples
> + ///
> + /// ```
> + /// use kernel::dma::Range;
> + ///
> + /// let range = Range::new(0x1000, 0x200)?;
> + ///
> + /// let sub = range.subrange(0x100, 0x80)?;
> + /// assert_eq!(sub.start(), 0x1100);
> + /// assert_eq!(sub.end(), 0x1180);
> + ///
> + /// assert!(range.subrange(0x100, 0x101).is_err());
> + /// # Ok::<(), Error>(())
> + /// ```
> + #[inline]
> + pub const fn subrange(&self, offset: DmaAddress, len: DmaAddress) -> Result<Self> {
> + let Some(end) = offset.checked_add(len) else {
> + return Err(EINVAL);
> + };
> +
> + if end > self.len {
> + return Err(EINVAL);
> + }
> +
> + // INVARIANT: `start + offset + len <= start + self.len`, which by the type invariant of
> + // `self` does not overflow `DmaAddress`.
> + Ok(Self {
> + start: self.start + offset,
> + len,
> + })
> + }
> +}
> +
> /// Trait to be implemented by DMA capable bus devices.
> ///
> /// The [`dma::Device`](Device) trait should be implemented by bus specific device representations,
> @@ -626,6 +762,25 @@ pub fn dma_handle(&self) -> DmaAddress {
> self.dma_handle
> }
>
> + /// Returns the [`Range`] of DMA addresses covering this allocation.
> + ///
> + /// Unlike [`Self::dma_handle`], which hands out the base address as a bare integer, the
> + /// returned [`Range`] couples the base address with the size of the allocation, such that
> + /// any offset arithmetic performed on it is checked.
> + #[inline]
> + pub fn dma_range(&self) -> Range {
> + // INVARIANT: By the type invariants of `Self`, `dma_handle` is the DMA address base of an
> + // allocated region of `self.size()` bytes; the DMA API guarantees that a mapped region
> + // never wraps the DMA address space, hence `dma_handle + size` does not overflow
> + // `DmaAddress`.
> + Range {
> + start: self.dma_handle,
> + // CAST: `usize` always fits in `DmaAddress`, which is at least 32 bits wide and
> + // always 64 bits wide on 64-bit architectures.
> + len: self.size() as DmaAddress,
> + }
> + }
> +
> /// Returns a reference to the data in the region.
> ///
> /// # Safety
> @@ -1101,6 +1256,25 @@ pub fn dma_handle(&self) -> DmaAddress {
> self.dma_handle
> }
>
> + /// Returns the [`Range`] of DMA addresses covering this allocation.
> + ///
> + /// Unlike [`Self::dma_handle`], which hands out the base address as a bare integer, the
> + /// returned [`Range`] couples the base address with the size of the allocation, such that
> + /// any offset arithmetic performed on it is checked.
> + #[inline]
> + pub fn dma_range(&self) -> Range {
> + // INVARIANT: By the type invariants of `Self`, `dma_handle` is the DMA address base of an
> + // allocated region of `self.size` bytes; the DMA API guarantees that a mapped region
> + // never wraps the DMA address space, hence `dma_handle + size` does not overflow
> + // `DmaAddress`.
> + Range {
> + start: self.dma_handle,
> + // CAST: `usize` always fits in `DmaAddress`, which is at least 32 bits wide and
> + // always 64 bits wide on 64-bit architectures.
> + len: self.size as DmaAddress,
> + }
> + }
> +
> /// Returns the size in bytes of this allocation.
> #[inline]
> pub fn size(&self) -> usize {
>
> ---
> base-commit: dc01dfb37b34beeefcfe1c3055364d41a4070c7e
> change-id: 20260805-dma-7c5330baadb6
>
> Best regards,
On 8/6/26 1:23 PM, Robin Murphy wrote:
> On 2026-08-06 8:46 am, Vasileios Almpanis wrote:
>> The base dma address of `Coherent` and `CoherentHandle` is a bare
>> `DmaAddress` integer so any arithmetic, a driver does on it is unchecked
>> and can potentially go past the end of the allocation or overflow.
>>
>> Add a `dma::Range` type that couples a base `DmaAddress` with a length
>> and only hands out addresses and sub-ranges within `[start, start +
>> len)`
>> with all arithmetics checked against both the length and the overflow of
>> of the underlying `dma_addr_t`. Let `Coherent` and `CoherentHandle`
>> provide the `Range` covering their allocation.
>>
>> Suggested-by: Danilo Krummrich <dakr@kernel.org>
>> Link: https://github.com/Rust-for-Linux/linux/issues/1248
>> Signed-off-by: Vasileios Almpanis <vasilisalmpanis@gmail.com>
>> ---
>> This is one of my first rust-for-linux patches, so any suggestions are
>> extremely welcome. Some words about the decisions taken:
>>
>> - I chose lengths offsets to be `DmaAddress` instead of usize since the
>> bus space can be 64-bit on 32-bit CPUS.
>
> The base address may be 64-bit, but the underlying
> dma_alloc_*/dma_map_* APIs all express lengths in size_t, so we
> shouldn't need to accommodate anything larger in Rust either.
> Sizes-as-address-types always seem a bit weird and clunky (lookin' at
> you, resource_size_t...), so probably better avoided if not absolutely
> necessary, IMO.
>
> Thanks,
> Robin.
You are right, lengths come from size_t taking APIs anyway, so usize is
the right type. Will change len and offset together with some things
sashiko found in v2
>
>> - The constructor returns EOVERFLOW for `dma_addr_t` overflow, while
>> out-of-bounds requests return EINVAL; happy to use a single error
>> code if preferred.
>>
>> - `dma_range()` is added to both `Coherent` and `CoherentHandle` so the
>> type has users from the start. I could split it into a follow-up if
>> that is preferred.
>>
>> Tested with `make rustdoc`, `make rustfmtcheck`, `CLIPPY=1`, and the
>> KUnit doctests `rust_doctests_kernel`.
>> ---
>> rust/kernel/dma.rs | 174
>> +++++++++++++++++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 174 insertions(+)
>>
>> diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs
>> index
>> 200def84fb69e006bca0b1c578bac9f1dc8da708..e65e99ae4d915ac2e385df8b72fc518c07e4c82d
>> 100644
>> --- a/rust/kernel/dma.rs
>> +++ b/rust/kernel/dma.rs
>> @@ -41,6 +41,142 @@
>> /// Note that this may be `u64` even on 32-bit architectures.
>> pub type DmaAddress = bindings::dma_addr_t;
>> +/// A range of DMA addresses.
>> +///
>> +/// Couples a base [`DmaAddress`] with the length in bytes of the
>> region it belongs to,
>> +/// representing the half-open range `[start, start + len)` of DMA
>> addresses.
>> +///
>> +/// Unlike a bare [`DmaAddress`], a [`Range`] only hands out
>> addresses and sub-ranges that are
>> +/// guaranteed to lie within `[start, start + len)`; all arithmetic
>> is checked against both the
>> +/// length of the range and overflow of the underlying [`DmaAddress`].
>> +///
>> +/// # Invariants
>> +///
>> +/// `start + len` does not overflow [`DmaAddress`].
>> +#[derive(Clone, Copy, Debug, PartialEq, Eq)]
>> +pub struct Range {
>> + start: DmaAddress,
>> + len: DmaAddress,
>> +}
>> +
>> +impl Range {
>> + /// Creates a new [`Range`] of `len` bytes, starting at `start`.
>> + ///
>> + /// Returns [`EOVERFLOW`] if `start + len` overflows
>> [`DmaAddress`].
>> + ///
>> + /// # Examples
>> + ///
>> + /// ```
>> + /// use kernel::dma::{DmaAddress, Range};
>> + ///
>> + /// let range = Range::new(0x1000, 0x200)?;
>> + /// assert_eq!(range.start(), 0x1000);
>> + /// assert_eq!(range.end(), 0x1200);
>> + /// assert_eq!(range.len(), 0x200);
>> + ///
>> + /// assert!(Range::new(DmaAddress::MAX, 1).is_err());
>> + /// # Ok::<(), Error>(())
>> + /// ```
>> + #[inline]
>> + pub const fn new(start: DmaAddress, len: DmaAddress) ->
>> Result<Self> {
>> + if start.checked_add(len).is_none() {
>> + return Err(EOVERFLOW);
>> + }
>> +
>> + // INVARIANT: We just checked that `start + len` does not
>> overflow `DmaAddress`.
>> + Ok(Self { start, len })
>> + }
>> +
>> + /// Returns the first address of the range.
>> + #[inline]
>> + pub const fn start(&self) -> DmaAddress {
>> + self.start
>> + }
>> +
>> + /// Returns the first address after the end of the range.
>> + #[inline]
>> + pub const fn end(&self) -> DmaAddress {
>> + // By the type invariant, `start + len` does not overflow
>> `DmaAddress`.
>> + self.start + self.len
>> + }
>> +
>> + /// Returns the length of the range in bytes.
>> + #[inline]
>> + pub const fn len(&self) -> DmaAddress {
>> + self.len
>> + }
>> +
>> + /// Returns `true` if the range is empty.
>> + #[inline]
>> + pub const fn is_empty(&self) -> bool {
>> + self.len == 0
>> + }
>> +
>> + /// Returns the address at `offset` bytes into the range.
>> + ///
>> + /// The returned address is guaranteed to lie within the range;
>> returns [`EINVAL`] if `offset`
>> + /// is not smaller than the length of the range.
>> + ///
>> + /// # Examples
>> + ///
>> + /// ```
>> + /// use kernel::dma::Range;
>> + ///
>> + /// let range = Range::new(0x1000, 0x200)?;
>> + ///
>> + /// assert_eq!(range.address(0)?, 0x1000);
>> + /// assert_eq!(range.address(0x1ff)?, 0x11ff);
>> + /// assert!(range.address(0x200).is_err());
>> + /// # Ok::<(), Error>(())
>> + /// ```
>> + #[inline]
>> + pub const fn address(&self, offset: DmaAddress) ->
>> Result<DmaAddress> {
>> + if offset >= self.len {
>> + return Err(EINVAL);
>> + }
>> +
>> + // By the type invariant, `start + offset < start + len`
>> does not overflow `DmaAddress`.
>> + Ok(self.start + offset)
>> + }
>> +
>> + /// Returns the sub-range of `len` bytes, starting `offset`
>> bytes into the range.
>> + ///
>> + /// The returned range is guaranteed to lie within the range;
>> returns [`EINVAL`] if
>> + /// `offset + len` overflows [`DmaAddress`] or exceeds the
>> length of the range.
>> + ///
>> + /// # Examples
>> + ///
>> + /// ```
>> + /// use kernel::dma::Range;
>> + ///
>> + /// let range = Range::new(0x1000, 0x200)?;
>> + ///
>> + /// let sub = range.subrange(0x100, 0x80)?;
>> + /// assert_eq!(sub.start(), 0x1100);
>> + /// assert_eq!(sub.end(), 0x1180);
>> + ///
>> + /// assert!(range.subrange(0x100, 0x101).is_err());
>> + /// # Ok::<(), Error>(())
>> + /// ```
>> + #[inline]
>> + pub const fn subrange(&self, offset: DmaAddress, len:
>> DmaAddress) -> Result<Self> {
>> + let Some(end) = offset.checked_add(len) else {
>> + return Err(EINVAL);
>> + };
>> +
>> + if end > self.len {
>> + return Err(EINVAL);
>> + }
>> +
>> + // INVARIANT: `start + offset + len <= start + self.len`,
>> which by the type invariant of
>> + // `self` does not overflow `DmaAddress`.
>> + Ok(Self {
>> + start: self.start + offset,
>> + len,
>> + })
>> + }
>> +}
>> +
>> /// Trait to be implemented by DMA capable bus devices.
>> ///
>> /// The [`dma::Device`](Device) trait should be implemented by bus
>> specific device representations,
>> @@ -626,6 +762,25 @@ pub fn dma_handle(&self) -> DmaAddress {
>> self.dma_handle
>> }
>> + /// Returns the [`Range`] of DMA addresses covering this
>> allocation.
>> + ///
>> + /// Unlike [`Self::dma_handle`], which hands out the base
>> address as a bare integer, the
>> + /// returned [`Range`] couples the base address with the size of
>> the allocation, such that
>> + /// any offset arithmetic performed on it is checked.
>> + #[inline]
>> + pub fn dma_range(&self) -> Range {
>> + // INVARIANT: By the type invariants of `Self`, `dma_handle`
>> is the DMA address base of an
>> + // allocated region of `self.size()` bytes; the DMA API
>> guarantees that a mapped region
>> + // never wraps the DMA address space, hence `dma_handle +
>> size` does not overflow
>> + // `DmaAddress`.
>> + Range {
>> + start: self.dma_handle,
>> + // CAST: `usize` always fits in `DmaAddress`, which is
>> at least 32 bits wide and
>> + // always 64 bits wide on 64-bit architectures.
>> + len: self.size() as DmaAddress,
>> + }
>> + }
>> +
>> /// Returns a reference to the data in the region.
>> ///
>> /// # Safety
>> @@ -1101,6 +1256,25 @@ pub fn dma_handle(&self) -> DmaAddress {
>> self.dma_handle
>> }
>> + /// Returns the [`Range`] of DMA addresses covering this
>> allocation.
>> + ///
>> + /// Unlike [`Self::dma_handle`], which hands out the base
>> address as a bare integer, the
>> + /// returned [`Range`] couples the base address with the size of
>> the allocation, such that
>> + /// any offset arithmetic performed on it is checked.
>> + #[inline]
>> + pub fn dma_range(&self) -> Range {
>> + // INVARIANT: By the type invariants of `Self`, `dma_handle`
>> is the DMA address base of an
>> + // allocated region of `self.size` bytes; the DMA API
>> guarantees that a mapped region
>> + // never wraps the DMA address space, hence `dma_handle +
>> size` does not overflow
>> + // `DmaAddress`.
>> + Range {
>> + start: self.dma_handle,
>> + // CAST: `usize` always fits in `DmaAddress`, which is
>> at least 32 bits wide and
>> + // always 64 bits wide on 64-bit architectures.
>> + len: self.size as DmaAddress,
>> + }
>> + }
>> +
>> /// Returns the size in bytes of this allocation.
>> #[inline]
>> pub fn size(&self) -> usize {
>>
>> ---
>> base-commit: dc01dfb37b34beeefcfe1c3055364d41a4070c7e
>> change-id: 20260805-dma-7c5330baadb6
>>
>> Best regards,
>
© 2016 - 2026 Red Hat, Inc.