Rust infrastructure for sg_table and scatterlist
Subsystems (5)
Danilo Krummrich
maintainerv2 cover Rust infrastructure for sg_table and scatterlist
This patch series provides abstractions for struct sg_table and struct scatterlist.
Abdiel and me agreed for me to take over his previous iterations on this topic. I decided to send my patches as a new series rather than as a subsequent version of Abdiel's previous iterations, since the changes I made turned out to be much closer to a full rewrite.
The most notable differences in design are:
- SGTable utilizes BorrowedPage, AsPageIter and VmallocPageIter from my patch
series in [1].
- SGTable is a transparent wrapper over either struct Owned<P> (where P is the provider of the backing pages) or struct Borrowed, which by itself is a transparent wrapper over Opaque<bindings::sg_table>, i.e. either SGTable<Owned<P>> or just SGTable (which is equivalent to SGTable<Borrowed>.
- SGTable<Owned<P>>: Represents a table whose resources are fully managed by Rust. It takes ownership of a page provider P, allocates the underlying struct sg_table, maps it for DMA, and handles all cleanup automatically upon drop. The DMA mapping's lifetime is tied to the associated device using Devres, ensuring it is correctly unmapped before the device is unbound.
- SGTable<Borrowed> (or just SGTable): A zero-cost representation of an externally managed struct sg_table. It is created from a raw pointer using SGTable::as_ref() and provides a lifetime-bound reference (&'a SGTable) for operations like iteration.
- As a consequence, a borrowed SG table can be created with SGTable::as_ref(), which returns a &'a SGTable, just like similar existing abstractions.
An owned SGTable is created with SGTable::new(), which returns an impl PinInit<SGTable<Owned<P>>, Error>, such that it can be initialized directly within existing private data memory allocations while providing the required pin guarantees.
- SGTable<Owned<P>> uses an inner type Devres<DmaMapSgt> to ensure that the DMA mapping can't out-live device unbind.
- SGTable<Owned<P>> uses pin-init for initialization.
This patch series depends on [1] (branch containing the patches in [2]). A branch containing this series (including dependencies) can be found in [3]; Abdiel's latest series can be found in [4].
[1] https://lore.kernel.org/rust-for-linux/[email protected]/
[2] https://git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=page-iter
[3] https://git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=scatterlist
[4] https://lore.kernel.org/lkml/[email protected]/
Changes in v2:
- Switch to an enum impl for DmaDirection utilizing compile time boundary checks.
- Add missing Send/ Sync impls.
- Rename as_ref() to from_raw().
- Add a bunch of inline annotations.
- Add a patch to introduce a typedef for dma_addr_t.
- Let dma_len() return ResourceSize.
- Add addional invariant to DmaMapSgt.
- In RawSGTable::new(), pass pages as mutable slice reference.
- Avoid casts when deriving max_segment in Owned::new().
Danilo Krummrich (5):
rust: dma: implement DataDirection
rust: dma: add type alias for bindings::dma_addr_t
rust: scatterlist: Add type-state abstraction for sg_table
samples: rust: dma: add sample code for SGTable
MAINTAINERS: rust: dma: add scatterlist files
MAINTAINERS | 4 +- drivers/gpu/nova-core/falcon.rs | 4 +- rust/bindings/bindings_helper.h | 1 + rust/helpers/helpers.c | 1 + rust/helpers/scatterlist.c | 24 ++ rust/kernel/dma.rs | 86 +++++- rust/kernel/lib.rs | 1 + rust/kernel/scatterlist.rs | 475 ++++++++++++++++++++++++++++++++ samples/rust/rust_dma.rs | 35 ++- 9 files changed, 615 insertions(+), 16 deletions(-) create mode 100644 rust/helpers/scatterlist.c create mode 100644 rust/kernel/scatterlist.rs
base-commit: 27941214d368f3c17ed26a72662fc453bcc81b9d
Signature · 1 line
2.50.1
Danilo Krummrich
maintainerPATCH v2 1/5 rust: dma: implement DataDirection
Add the DataDirection struct, a newtype wrapper around the C enum dma_data_direction.
This provides a type-safe Rust interface for specifying the direction of DMA transfers.
--- rust/bindings/bindings_helper.h | 1 + rust/kernel/dma.rs | 68 +++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+)
rust/bindings/bindings_helper.h +1 -0
@@ -47,6 +47,7 @@#include <linux/cpumask.h> #include <linux/cred.h> #include <linux/device/faux.h> +#include <linux/dma-direction.h> #include <linux/dma-mapping.h> #include <linux/errname.h> #include <linux/ethtool.h>
rust/kernel/dma.rs +68 -0
74 lines not on this page · raw message
Signature · 1 line
2.50.1
Re: [PATCH v2 1/5] rust: dma: implement DataDirection
Quoted 7 lines · Danilo Krummrich
Add the
DataDirectionstruct, a newtype wrapper around the Cenum dma_data_direction.This provides a type-safe Rust interface for specifying the direction of DMA transfers.
Signed-off-by Danilo Krummrich <[email protected]>
Re: [PATCH v2 1/5] rust: dma: implement DataDirection
In reply to Danilo KrummrichQuoted 7 lines · Danilo Krummrich
Add the
DataDirectionstruct, a newtype wrapper around the Cenum dma_data_direction.This provides a type-safe Rust interface for specifying the direction of DMA transfers.
Signed-off-by Danilo Krummrich <[email protected]>
One very very minor comment below.
Quoted 33 lines
--- rust/bindings/bindings_helper.h | 1 + rust/kernel/dma.rs | 68 +++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+)rust/bindings/bindings_helper.h +1
-0@@ -47,6 +47,7 @@#include <linux/cpumask.h> #include <linux/cred.h> #include <linux/device/faux.h> +#include <linux/dma-direction.h> #include <linux/dma-mapping.h> #include <linux/errname.h> #include <linux/ethtool.h> rust/kernel/dma.rs +8
-0@@ -244,6 +244,74 @@ pub mod attrs {pub const DMA_ATTR_PRIVILEGED :Attrs =Attrs (bindings::DMA_ATTR_PRIVILEGED ); } +/// DMA data direction. +/// +/// Corresponds to the C [`enum dma_data_direction`]. +/// +/// [`enum dma_data_direction`]: srctree/include/linux/dma-direction.h +#[derive( Copy , Clone , PartialEq , Eq , Debug )] +#[repr( u32 )] +pub enum DataDirection {
rust/kernel/dma.rs pub mod attrs { · line 264
Quoted 10 lines
rust/kernel/dma.rs +10
-0+/// The DMA mapping is for bidirectional data transfer. +/// +/// This is used when the buffer can be both read from and written to by the device. +/// The cache for the corresponding memory region is both flushed and invalidated. + Bidirectional = Self::const_cast(bindings::dma_data_direction_DMA_BIDIRECTIONAL), + +/// The DMA mapping is for data transfer from memory to the device (write). +/// +/// The CPU has prepared data in the buffer, and the device will read it. +/// The cache for the corresponding memory region is flushed.
Is flushed when? :) The comment for FromDevice specifies the timing for cache invalidation, so it would be nice to have the same here imho.
Danilo Krummrich
maintainerPATCH v2 2/5 rust: dma: add type alias for bindings::dma_addr_t
In reply to Danilo KrummrichAdd a type alias for bindings::dma_addr_t (DmaAddress), such that we do not have to access bindings directly.
--- drivers/gpu/nova-core/falcon.rs | 4 ++-- rust/kernel/dma.rs | 18 ++++++++++++++---- 2 files changed, 16 insertions(+), 6 deletions(-)
drivers/gpu/nova-core/falcon.rs +2 -2
@@ -4,8 +4,8 @@use core::ops::Deref ;use hal::FalconHal ; -use kernel::bindings;use kernel::device; +use kernel::dma::DmaAddress ;use kernel::prelude::*;use kernel::time::Delta ;use kernel::types::ARef ;
@@ -443,7 +443,7 @@ fn dma_wr<F: FalconFirmware<Target = E>>( fw.dma_handle_with_offset(load_offsets.src_start as usize)?, ), }; -if dma_start % bindings::dma_addr_t::from (DMA_LEN ) >0 { +if dma_start %DmaAddress ::from (DMA_LEN ) >0 {dev_err! ( self.dev,"DMA transfer start addresses must be a multiple of {}" ,
rust/kernel/dma.rs +14 -4
@@ -13,6 +13,16 @@ types::ARef, }; +/// DMA address type. +/// +/// Represents a bus address used for Direct Memory Access (DMA) operations. +/// +/// This is an alias of the kernel's `dma_addr_t`, which may be `u32` or `u64` depending on +/// `CONFIG_ARCH_DMA_ADDR_T_64BIT`. +/// +/// Note that this may be `u64` even on 32-bit architectures. +pub type DmaAddress = bindings::dma_addr_t ; +/// Trait to be implemented by DMA capable bus devices. /// /// The [`dma::Device`](Device) trait should be implemented by bus specific device representations,
@@ -343,7 +353,7 @@ fn from(direction: DataDirection) -> Self {// entire `CoherentAllocation` including the allocated memory itself. pub struct CoherentAllocation <T :AsBytes +FromBytes > { dev:ARef <device::Device >, - dma_handle: bindings::dma_addr_t , + dma_handle:DmaAddress , count:usize , cpu_addr: *mut T , dma_attrs:Attrs ,
@@ -444,7 +454,7 @@ pub fn start_ptr_mut(&mut self) -> *mut T {/// Returns a DMA handle which may be given to the device as the DMA address base of /// the region. -pub fn dma_handle (&self) -> bindings::dma_addr_t { +pub fn dma_handle (&self) ->DmaAddress { self.dma_handle }
@@ -452,13 +462,13 @@ pub fn dma_handle(&self) -> bindings::dma_addr_t {/// device as the DMA address base of the region. /// /// Returns `EINVAL` if `offset` is not within the bounds of the allocation. -pub fn dma_handle_with_offset (&self, offset:usize ) ->Result <bindings::dma_addr_t > { +pub fn dma_handle_with_offset (&self, offset:usize ) ->Result <DmaAddress > {if offset >= self.count {Err (EINVAL ) }else {// INVARIANT: The type invariant of `Self` guarantees that `size_of::<T> * count` fits // into a `usize`, and `offset` is inferior to `count`. -Ok (self.dma_handle + (offset * core::mem::size_of ::<T >())as bindings::dma_addr_t ) +Ok (self.dma_handle + (offset * core::mem::size_of ::<T >())as DmaAddress ) } }
Signature · 1 line
2.50.1
Re: [PATCH v2 2/5] rust: dma: add type alias for bindings::dma_addr_t
Quoted 5 lines · Danilo Krummrich
Add a type alias for
bindings::dma_addr_t(DmaAddress), such that we do not have to access bindings directly.Suggested-by Alice Ryhl <[email protected]>Signed-off-by Danilo Krummrich <[email protected]>
Re: [PATCH v2 2/5] rust: dma: add type alias for bindings::dma_addr_t
In reply to Danilo KrummrichQuoted 5 lines · Danilo Krummrich
Add a type alias for
bindings::dma_addr_t(DmaAddress), such that we do not have to access bindings directly.Suggested-by Alice Ryhl <[email protected]>Signed-off-by Danilo Krummrich <[email protected]>
Danilo Krummrich
maintainerPATCH v2 3/5 rust: scatterlist: Add type-state abstraction for sg_table
In reply to Danilo KrummrichAdd a safe Rust abstraction for the kernel's scatter-gather list facilities (struct scatterlist and struct sg_table).
This commit introduces SGTable<T>, a wrapper that uses a type-state pattern to provide compile-time guarantees about ownership and lifetime.
The abstraction provides two primary states:
- SGTable<Owned<P>>: Represents a table whose resources are fully managed by Rust. It takes ownership of a page provider P, allocates the underlying struct sg_table, maps it for DMA, and handles all cleanup automatically upon drop. The DMA mapping's lifetime is tied to the associated device using Devres, ensuring it is correctly unmapped before the device is unbound.
- SGTable<Borrowed> (or just SGTable): A zero-cost representation of an externally managed struct sg_table. It is created from a raw pointer using SGTable::as_ref() and provides a lifetime-bound reference (&'a SGTable) for operations like iteration.
The API exposes a safe iterator that yields &SGEntry references, allowing drivers to easily access the DMA address and length of each segment in the list.
--- rust/helpers/helpers.c | 1 + rust/helpers/scatterlist.c | 24 ++ rust/kernel/lib.rs | 1 + rust/kernel/scatterlist.rs | 475 +++++++++++++++++++++++++++++++++++++ 4 files changed, 501 insertions(+) create mode 100644 rust/helpers/scatterlist.c create mode 100644 rust/kernel/scatterlist.rs
rust/helpers/helpers.c +1 -0
@@ -39,6 +39,7 @@#include "rcu.c" #include "refcount.c" #include "regulator.c" +#include "scatterlist.c" #include "security.c" #include "signal.c" #include "slab.c"
rust/helpers/scatterlist.c new file +24 -0
@@ -0,0 +1,24 @@ +// SPDX-License-Identifier: GPL-2.0 + +#include <linux/dma-direction.h> + +dma_addr_t rust_helper_sg_dma_address (struct scatterlist *sg) +{ +return sg_dma_address (sg); +} + +unsigned int rust_helper_sg_dma_len (struct scatterlist *sg) +{ +return sg_dma_len (sg); +} + +struct scatterlist *rust_helper_sg_next (struct scatterlist *sg) +{ +return sg_next (sg); +} + +void rust_helper_dma_unmap_sgtable (struct device *dev,struct sg_table *sgt, +enum dma_data_direction dir,unsigned long attrs) +{ +return dma_unmap_sgtable (dev, sgt, dir, attrs); +}
rust/kernel/lib.rs +1 -0
@@ -113,6 +113,7 @@pub mod rbtree;pub mod regulator;pub mod revocable; +pub mod scatterlist;pub mod security;pub mod seq_file;pub mod sizes;
rust/kernel/scatterlist.rs new file +475 -0
475 lines not on this page · raw message
Signature · 1 line
2.50.1
Daniel Almeida
reviewerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Hmm, I see that you’ve just posted a new version. I had v1 open the whole morning so I missed that. Can you check my nits there?
— Daniel
Alice Ryhl
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
In reply to Danilo KrummrichQuoted 326 lines · Danilo Krummrich
Add a safe Rust abstraction for the kernel's scatter-gather list facilities (
struct scatterlistandstruct sg_table).This commit introduces
SGTable<T>, a wrapper that uses a type-state pattern to provide compile-time guarantees about ownership and lifetime.The abstraction provides two primary states:
-SGTable<Owned<P>>: Represents a table whose resources are fully managed by Rust. It takes ownership of a page providerP, allocates the underlyingstruct sg_table, maps it for DMA, and handles all cleanup automatically upon drop. The DMA mapping's lifetime is tied to the associated device usingDevres, ensuring it is correctly unmapped before the device is unbound.
-SGTable<Borrowed>(or justSGTable): A zero-cost representation of an externally managedstruct sg_table. It is created from a raw pointer usingSGTable::as_ref()and provides a lifetime-bound reference (&'a SGTable) for operations like iteration.The API exposes a safe iterator that yields
&SGEntryreferences, allowing drivers to easily access the DMA address and length of each segment in the list.Co-developed-by Abdiel Janulgue <[email protected]>Signed-off-by Abdiel Janulgue <[email protected]>Signed-off-by Danilo Krummrich <[email protected]>--- rust/helpers/helpers.c | 1 + rust/helpers/scatterlist.c | 24 ++ rust/kernel/lib.rs | 1 + rust/kernel/scatterlist.rs | 475 +++++++++++++++++++++++++++++++++++++ 4 files changed, 501 insertions(+) create mode 100644 rust/helpers/scatterlist.c create mode 100644 rust/kernel/scatterlist.rsrust/helpers/helpers.c +1
-0@@ -39,6 +39,7 @@#include "rcu.c" #include "refcount.c" #include "regulator.c" +#include "scatterlist.c" #include "security.c" #include "signal.c" #include "slab.c" rust/helpers/scatterlist.c new file +24
-0@@ -0,0 +1,24 @@ +// SPDX-License-Identifier: GPL-2.0 + +#include <linux/dma-direction.h> + +dma_addr_t rust_helper_sg_dma_address (struct scatterlist *sg) +{ +return sg_dma_address (sg); +} + +unsigned int rust_helper_sg_dma_len (struct scatterlist *sg) +{ +return sg_dma_len (sg); +} + +struct scatterlist *rust_helper_sg_next (struct scatterlist *sg) +{ +return sg_next (sg); +} + +void rust_helper_dma_unmap_sgtable (struct device *dev,struct sg_table *sgt, +enum dma_data_direction dir,unsigned long attrs) +{ +return dma_unmap_sgtable (dev, sgt, dir, attrs); +}rust/kernel/lib.rs +1
-0@@ -113,6 +113,7 @@pub mod rbtree;pub mod regulator;pub mod revocable; +pub mod scatterlist;pub mod security;pub mod seq_file;pub mod sizes;rust/kernel/scatterlist.rs new file +232
-0@@ -0,0 +1,475 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Abstractions for scatter-gather lists. +//! +//! C header: [`include/linux/scatterlist.h`](srctree/include/linux/scatterlist.h) +//! +//! Scatter-gather (SG) I/O is a memory access technique that allows devices to perform DMA +//! operations on data buffers that are not physically contiguous in memory. It works by creating a +//! "scatter-gather list", an array where each entry specifies the address and length of a +//! physically contiguous memory segment. +//! +//! The device's DMA controller can then read this list and process the segments sequentially as +//! part of one logical I/O request. This avoids the need for a single, large, physically contiguous +//! memory buffer, which can be difficult or impossible to allocate. +//! +//! This module provides safe Rust abstractions over the kernel's `struct scatterlist` and +//! `struct sg_table` types. +//! +//! The main entry point is the [`SGTable`] type, which represents a complete scatter-gather table. +//! It can be either: +//! +//! - An owned table ([`SGTable<Owned<P>>`]), created from a Rust memory buffer (e.g., [`VVec`]). +//! This type manages the allocation of the `struct sg_table`, the DMA mapping of the buffer, and +//! the automatic cleanup of all resources. +//! - A borrowed reference (&[`SGTable`]), which provides safe, read-only access to a table that was +//! allocated by other (e.g., C) code. +//! +//! Individual entries in the table are represented by [`SGEntry`], which can be accessed by +//! iterating over an [`SGTable`]. + +use crate ::{ + alloc, + alloc::allocator::VmallocPageIter , + bindings, + device::{Bound ,Device }, + devres::Devres , + dma, error, + io::resource::ResourceSize , + page, + prelude::*, + types::{ARef ,Opaque }, +}; +use core::{ops::Deref , ptr::NonNull }; + +/// A single entry in a scatter-gather list. +/// +/// An `SGEntry` represents a single, physically contiguous segment of memory that has been mapped +/// for DMA. +/// +/// Instances of this struct are obtained by iterating over an [`SGTable`]. Drivers do not create +/// or own [`SGEntry`] objects directly. +#[repr(transparent)] +pub struct SGEntry (Opaque <bindings::scatterlist >); + +// SAFETY: `SGEntry` can be send to any task. +unsafe impl Send for SGEntry {} + +// SAFETY: `SGEntry` can be accessed concurrently. +unsafe impl Sync for SGEntry {} + +impl SGEntry { +/// Convert a raw `struct scatterlist *` to a `&'a SGEntry`. +/// +/// # Safety +/// +/// Callers must ensure that the `struct scatterlist` pointed to by `ptr` is valid for the +/// lifetime `'a`. +#[inline] +unsafe fn from_raw <'a>(ptr: *mut bindings::scatterlist ) -> &'aSelf { +// SAFETY: The safety requirements of this function guarantee that `ptr` is a valid pointer +// to a `struct scatterlist` for the duration of `'a`. +unsafe { &*ptr.cast () } + } + +/// Obtain the raw `struct scatterlist *`. +#[inline] +fn as_raw (&self) -> *mut bindings::scatterlist { + self.0 .get () + } + +/// Returns the DMA address of this SG entry. +/// +/// This is the address that the device should use to access the memory segment. +#[inline] +pub fn dma_address (&self) -> dma::DmaAddress { +// SAFETY: `self.as_raw()` is a valid pointer to a `struct scatterlist`. +unsafe { bindings::sg_dma_address (self.as_raw ()) } + } + +/// Returns the length of this SG entry in bytes. +#[inline] +pub fn dma_len (&self) ->ResourceSize { +#[allow(clippy::useless_conversion)] +// SAFETY: `self.as_raw()` is a valid pointer to a `struct scatterlist`. +unsafe { bindings::sg_dma_len (self.as_raw ()) }.into () + } +} + +/// The borrowed type state of an [`SGTable`], representing a borrowed or externally managed table. +#[repr(transparent)] +pub struct Borrowed (Opaque <bindings::sg_table >); + +// SAFETY: `Borrowed` can be send to any task. +unsafe impl Send for Borrowed {} + +// SAFETY: `Borrowed` can be accessed concurrently. +unsafe impl Sync for Borrowed {} + +/// A scatter-gather table. +/// +/// This struct is a wrapper around the kernel's `struct sg_table`. It manages a list of DMA-mapped +/// memory segments that can be passed to a device for I/O operations. +/// +/// The generic parameter `T` is used as a type state to distinguish between owned and borrowed +/// tables. +/// +/// - [`SGTable<Owned>`]: An owned table created and managed entirely by Rust code. It handles +/// allocation, DMA mapping, and cleanup of all associated resources. See [`SGTable::new`]. +/// - [`SGTable<Borrowed>`} (or simply [`SGTable`]): Represents a table whose lifetime is managed +/// externally. It can be used safely via a borrowed reference `&'a SGTable`, where `'a` is the +/// external lifetime. +/// +/// All [`SGTable`] variants can be iterated over the individual [`SGEntry`]s. +#[repr(transparent)] +#[pin_data] +pub struct SGTable <T : private::Sealed =Borrowed > { +#[pin] + inner:T , +} + +impl SGTable { +/// Creates a borrowed `&'a SGTable` from a raw `struct sg_table` pointer. +/// +/// This allows safe access to an `sg_table` that is managed elsewhere (for example, in C code). +/// +/// # Safety +/// +/// Callers must ensure that: +/// +/// - the `struct sg_table` pointed to by `ptr` is valid for the entire lifetime of `'a`, +/// - the data behind `ptr` is not modified concurrently for the duration of `'a`. +#[inline] +pub unsafe fn from_raw <'a>(ptr: *mut bindings::sg_table ) -> &'aSelf { +// SAFETY: The safety requirements of this function guarantee that `ptr` is a valid pointer +// to a `struct sg_table` for the duration of `'a`. +unsafe { &*ptr.cast () } + } + +#[inline] +fn as_raw (&self) -> *mut bindings::sg_table { + self.inner.0 .get () + } + +fn as_iter (&self) ->SGTableIter <'_> { +// SAFETY: `self.as_raw()` is a valid pointer to a `struct sg_table`. +let ptr =unsafe { (*self.as_raw ()).sgl }; + +// SAFETY: `ptr` is guaranteed to be a valid pointer to a `struct scatterlist`. +let pos =Some (unsafe {SGEntry ::from_raw (ptr) }); + +SGTableIter { pos } + } +} + +/// # Invariants +/// +/// - `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`]. +/// - `sgt` is always DMA mapped. +struct DmaMapSgt { + sgt:NonNull <bindings::sg_table >, + dev:ARef <Device >, + dir: dma::DataDirection , +} + +// SAFETY: `DmaMapSgt` can be send to any task. +unsafe impl Send for DmaMapSgt {} + +// SAFETY: `DmaMapSgt` can be accessed concurrently. +unsafe impl Sync for DmaMapSgt {} + +impl DmaMapSgt { +/// # Safety +/// +/// - `sgt` must be a valid pointer to a `struct sg_table` for the entire lifetime of the +/// returned [`DmaMapSgt`]. +/// - The caller must guarantee that `sgt` remains DMA mapped for the entire lifetime of +/// [`DmaMapSgt`]. +unsafe fn new ( + sgt:NonNull <bindings::sg_table >, + dev: &Device <Bound >, + dir: dma::DataDirection , + ) ->Result <Self > { +// SAFETY: +// - `dev.as_raw()` is a valid pointer to a `struct device`, which is guaranteed to be +// bound to a driver for the duration of this call. +// - `sgt` is a valid pointer to a `struct sg_table`. + error::to_result (unsafe { + bindings::dma_map_sgtable (dev.as_raw (), sgt.as_ptr (), dir.into (),0 ) + })?; + +// INVARIANT: By the safety requirements of this function it is guaranteed that `sgt` is +// valid for the entire lifetime of this object instance. +Ok (Self { + sgt, + dev: dev.into (), + dir, + }) + } +} + +impl Drop for DmaMapSgt { +#[inline] +fn drop (&mut self) { +// SAFETY: +// - `self.dev.as_raw()` is a pointer to a valid `struct device`. +// - `self.dev` is the same device the mapping has been created for in `Self::new()`. +// - `self.sgt.as_ptr()` is a valid pointer to a `struct sg_table` by the type invariants +// of `Self`. +// - `self.dir` is the same `dma::DataDirection` the mapping has been created with in +// `Self::new()`. +unsafe { + bindings::dma_unmap_sgtable (self.dev.as_raw (), self.sgt.as_ptr (), self.dir.into (),0 ) + }; + } +} + +#[repr(transparent)] +#[pin_data( PinnedDrop )] +struct RawSGTable { +#[pin] + sgt:Opaque <bindings::sg_table >, +}
rust/kernel/scatterlist.rs line 242
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+ +// SAFETY: `RawSGTable` can be send to any task. +unsafe impl Send for RawSGTable {} + +// SAFETY: `RawSGTable` can be accessed concurrently. +unsafe impl Sync for RawSGTable {} + +impl RawSGTable { +fn new ( + pages: &mut [*mut bindings::page],
This mutable reference is suspicious, IMO. Does it modify the list? You don't read the values after calling sg_alloc_table_from_pages_segment().
Quoted 32 lines
rust/kernel/scatterlist.rs new file +32
-0+ size: usize, + max_segment: u32, + flags: alloc::Flags, + ) -> impl PinInit<Self, Error> + '_ { +try_pin_init! (Self { + sgt <-Opaque ::try_ffi_init (|slot: *mut bindings::sg_table | { +// `sg_alloc_table_from_pages_segment()` expects at least one page, otherwise it +// produces a NPE. +if pages.is_empty () { +return Err (EINVAL ); + } + +// SAFETY: +// - `slot` is a valid pointer to uninitialized memory. +// - As by the check above, `pages` is not empty. + error::to_result (unsafe { + bindings::sg_alloc_table_from_pages_segment ( + slot, + pages.as_mut_ptr (), + pages.len ().try_into ()?, +0 , + size, + max_segment, + flags.as_raw (), + ) + }) + }), + }) + } + +#[inline] +fn as_raw (&self) -> *mut bindings::sg_table {
rust/kernel/scatterlist.rs line 284
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+ self.sgt.get () + } +} + +#[pinned_drop] +impl PinnedDrop for RawSGTable { +#[inline] +fn drop (self:Pin <&mut Self >) { +// SAFETY: `sgt` is a valid and initialized `struct sg_table`. +unsafe { bindings::sg_free_table (self.sgt.get ()) };
It's weird that this is called free when the sg_table isn't freed by this call.
Quoted 32 lines
rust/kernel/scatterlist.rs new file +32
-0+ } +} + +/// The [`Owned`] type state of an [`SGTable`]. +/// +/// A [`SGTable<Owned>`] signifies that the [`SGTable`] owns all associated resources: +/// +/// - The backing memory pages. +/// - The `struct sg_table` allocation (`sgt`). +/// - The DMA mapping, managed through a [`Devres`]-managed `DmaMapSgt`. +/// +/// Users interact with this type through the [`SGTable`] handle and do not need to manage +/// [`Owned`] directly. +#[pin_data] +pub struct Owned <P > { +// Note: The drop order is relevant; we first have to unmap the `struct sg_table`, then free the +// `struct sg_table` and finally free the backing pages. +#[pin] + dma:Devres <DmaMapSgt >, +#[pin] + sgt:RawSGTable , + _pages:P , +} + +// SAFETY: `Owned` can be send to any task if `P` can be send to any task. +unsafe impl <P :Send >Send for Owned <P > {} + +// SAFETY: `Owned` can be accessed concurrently if `P` can be accessed concurrently. +unsafe impl <P :Sync >Sync for Owned <P > {} + +impl <P >Owned <P > +where
rust/kernel/scatterlist.rs line 326
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+ for<'a> P: page::AsPageIter<Iter<'a> = VmallocPageIter<'a>> + 'static, +{ + fn new( + dev: &Device<Bound>, + mut pages: P, + dir: dma::DataDirection, + flags: alloc::Flags, + ) -> Result<impl PinInit<Self, Error> + '_> { + let page_iter = pages.page_iter(); + let size = page_iter.size();
Variable naming here is confusing. There's another variable called size in an inner scope, and then afterwards in RawSGTable you use *this* size variable again.
Quoted 151 lines
rust/kernel/scatterlist.rs new file +148
-0+let mut page_vec:KVec <*mut bindings::page > = +KVec ::with_capacity (page_iter.page_count (), flags)?; + +for pagein page_iter { + page_vec.push (page.as_ptr (), flags)?; + } + +// `dma_max_mapping_size` returns `size_t`, but `sg_alloc_table_from_pages_segment()` takes +// an `unsigned int`. +let max_segment = { +// SAFETY: `dev.as_raw()` is a valid pointer to a `struct device`. +let size =unsafe { bindings::dma_max_mapping_size (dev.as_raw ()) }; +if size ==0 { + u32::MAX + }else { + u32::try_from (size).unwrap_or (u32::MAX ) + } + }; + +Ok (try_pin_init! (&this inSelf { + sgt <-RawSGTable ::new (&mut page_vec, size, max_segment, flags), + dma <- { +// SAFETY: `this` is a valid pointer to uninitialized memory. +let sgt =unsafe { &raw mut (*this.as_ptr ()).sgt }.cast (); + +// SAFETY: `sgt` is guaranteed to be non-null. +let sgt =unsafe {NonNull ::new_unchecked (sgt) }; + +// SAFETY: +// - It is guaranteed that the object returned by `DmaMapSgt::new` won't out-live +// `sgt`. +// - `sgt` is never DMA unmapped manually. +Devres ::new (dev,unsafe {DmaMapSgt ::new (sgt, dev, dir) }) + }, + _pages: pages, + })) + } +} + +impl <P >SGTable <Owned <P >> +where +for <'a>P : page::AsPageIter <Iter <'a> =VmallocPageIter <'a>> + 'static, +{ +/// Allocates a new scatter-gather table from the given pages and maps it for DMA. +/// +/// This constructor creates a new [`SGTable<Owned>`] that takes ownership of `P`. +/// It allocates a `struct sg_table`, populates it with entries corresponding to the physical +/// pages of `P`, and maps the table for DMA with the specified [`Device`] and +/// [`dma::DataDirection`]. +/// +/// The DMA mapping is managed through [`Devres`], ensuring that the DMA mapping is unmapped +/// once the associated [`Device`] is unbound, or when the [`SGTable<Owned>`] is dropped. +/// +/// # Parameters +/// +/// * `dev`: The [`Device`] that will be performing the DMA. +/// * `pages`: The entity providing the backing pages. It must implement [`page::AsPageIter`]. +/// The ownership of this entity is moved into the new [`SGTable<Owned>`]. +/// * `dir`: The [`dma::DataDirection`] of the DMA transfer. +/// * `flags`: Allocation flags for internal allocations (e.g., [`GFP_KERNEL`]). +/// +/// # Examples +/// +/// ``` +/// use kernel::{ +/// device::{Bound, Device}, +/// dma, page, +/// prelude::*, +/// scatterlist::*, +/// }; +/// +/// fn test(dev: &Device<Bound>) -> Result { +/// let size = 4 * page::PAGE_SIZE; +/// let pages = VVec::<u8>::with_capacity(size, GFP_KERNEL)?; +/// +/// let sgt = KBox::pin_init(SGTable::new( +/// dev, +/// pages, +/// dma::DataDirection::ToDevice, +/// GFP_KERNEL, +/// ), GFP_KERNEL)?; +/// +/// Ok(()) +/// } +/// ``` +pub fn new ( + dev: &Device <Bound >, + pages:P , + dir: dma::DataDirection , + flags: alloc::Flags , + ) ->impl PinInit <Self ,Error > + '_ { +try_pin_init! (Self { + inner <-Owned ::new (dev, pages, dir, flags)? + }) + } +} + +impl <P >Deref for SGTable <Owned <P >> { +type Target =SGTable ; + +#[inline] +fn deref (&self) -> &Self ::Target { +// SAFETY: `self.inner.sgt.as_raw()` is a valid pointer to a `struct sg_table` for the +// entire lifetime of `self`. +unsafe {SGTable ::from_raw (self.inner.sgt.as_raw ()) } + } +} + +mod private { +pub trait Sealed {} + +impl Sealed for super ::Borrowed {} +impl <P >Sealed for super ::Owned <P > {} +} + +impl <'a>IntoIterator for &'aSGTable { +type Item = &'aSGEntry ; +type IntoIter =SGTableIter <'a>; + +#[inline] +fn into_iter (self) ->Self ::IntoIter { + self.as_iter () + } +} + +/// An [`Iterator`] over the [`SGEntry`] items of an [`SGTable`]. +pub struct SGTableIter <'a> { + pos:Option <&'aSGEntry >, +} + +impl <'a>Iterator for SGTableIter <'a> { +type Item = &'aSGEntry ; + +fn next (&mut self) ->Option <Self ::Item > { +let entry = self.pos?; + +// SAFETY: `entry.as_raw()` is a valid pointer to a `struct scatterlist`. +let next =unsafe { bindings::sg_next (entry.as_raw ()) }; + + self.pos = (!next.is_null ()).then (|| { +// SAFETY: If `next` is not NULL, `sg_next()` guarantees to return a valid pointer to +// the next `struct scatterlist`. +unsafe {SGEntry ::from_raw (next) } + }); + +Some (entry) + } +}Signature · 1 line
2.50.1
Danilo Krummrich
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 9 lines · Alice Ryhl
rust/kernel/scatterlist.rs line 284
Quoted 6 lines
rust/kernel/scatterlist.rs new file +6
-0+#[pinned_drop] +impl PinnedDrop for RawSGTable { +#[inline] +fn drop (self:Pin <&mut Self >) { +// SAFETY: `sgt` is a valid and initialized `struct sg_table`. +unsafe { bindings::sg_free_table (self.sgt.get ()) };It's weird that this is called free when the
sg_tableisn't freed by this call.
It frees the entries contained in the sg_table.
Quoted 38 lines
Quoted 38 lines
rust/kernel/scatterlist.rs new file +38
-0+ } +} + +/// The [`Owned`] type state of an [`SGTable`]. +/// +/// A [`SGTable<Owned>`] signifies that the [`SGTable`] owns all associated resources: +/// +/// - The backing memory pages. +/// - The `struct sg_table` allocation (`sgt`). +/// - The DMA mapping, managed through a [`Devres`]-managed `DmaMapSgt`. +/// +/// Users interact with this type through the [`SGTable`] handle and do not need to manage +/// [`Owned`] directly. +#[pin_data] +pub struct Owned <P > { +// Note: The drop order is relevant; we first have to unmap the `struct sg_table`, then free the +// `struct sg_table` and finally free the backing pages. +#[pin] + dma:Devres <DmaMapSgt >, +#[pin] + sgt:RawSGTable , + _pages:P , +} + +// SAFETY: `Owned` can be send to any task if `P` can be send to any task. +unsafe impl <P :Send >Send for Owned <P > {} + +// SAFETY: `Owned` can be accessed concurrently if `P` can be accessed concurrently. +unsafe impl <P :Sync >Sync for Owned <P > {} + +impl <P >Owned <P > +where +for <'a>P : page::AsPageIter <Iter <'a> =VmallocPageIter <'a>> + 'static, +{ +fn new ( + dev: &Device <Bound >, +mut pages:P , + dir: dma::DataDirection,
Quoted 8 lines
rust/kernel/scatterlist.rs line 326
Quoted 4 lines
rust/kernel/scatterlist.rs new file +4
-0+ flags: alloc::Flags, + ) -> Result<impl PinInit<Self, Error> + '_> { +let page_iter = pages.page_iter (); +let size = page_iter.size ();Variable naming here is confusing. There's another variable called size in an inner scope, and then afterwards in RawSGTable you use *this* size variable again.
I can change the size in the assignment block of max_segment to max_size, or do you have other suggestions?
Alice Ryhl
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 18 lines · Danilo Krummrich
Quoted 8 lines · Alice Ryhl
Quoted 8 lines
rust/kernel/scatterlist.rs new file +8
-0+impl <P >Owned <P > +where +for <'a>P : page::AsPageIter <Iter <'a> =VmallocPageIter <'a>> + 'static, +{ +fn new ( + dev: &Device <Bound >, +mut pages:P , + dir: dma::DataDirection,Quoted 8 lines
rust/kernel/scatterlist.rs line 326
Quoted 4 lines
rust/kernel/scatterlist.rs new file +4
-0+ flags: alloc::Flags, + ) -> Result<impl PinInit<Self, Error> + '_> { +let page_iter = pages.page_iter (); +let size = page_iter.size ();Variable naming here is confusing. There's another variable called size in an inner scope, and then afterwards in RawSGTable you use *this* size variable again.
Quoted 2 lines
I can change the size in the assignment block of
max_segmenttomax_size, or do you have other suggestions?
How about just this?
let max_segment = {
// SAFETY: `dev.as_raw()` is a valid pointer to a `struct device`.
let max_segment = unsafe { bindings::dma_max_mapping_size(dev.as_raw()) };
if max_segment == 0 {
u32::MAX
} else {
u32::try_from(max_segment).unwrap_or(u32::MAX)
}
};Alice
Danilo Krummrich
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 24 lines · Alice Ryhl
Quoted 18 lines · Danilo Krummrich
Quoted 8 lines · Alice Ryhl
Quoted 8 lines
rust/kernel/scatterlist.rs new file +8
-0+impl <P >Owned <P > +where +for <'a>P : page::AsPageIter <Iter <'a> =VmallocPageIter <'a>> + 'static, +{ +fn new ( + dev: &Device <Bound >, +mut pages:P , + dir: dma::DataDirection,Quoted 8 lines
rust/kernel/scatterlist.rs line 326
Quoted 4 lines
rust/kernel/scatterlist.rs new file +4
-0+ flags: alloc::Flags, + ) -> Result<impl PinInit<Self, Error> + '_> { +let page_iter = pages.page_iter (); +let size = page_iter.size ();Variable naming here is confusing. There's another variable called size in an inner scope, and then afterwards in RawSGTable you use *this* size variable again.
Quoted 2 lines
I can change the size in the assignment block of
max_segmenttomax_size, or do you have other suggestions?How about just this?
Quoted 9 lines
let max_segment = {
// SAFETY: `dev.as_raw()` is a valid pointer to a `struct device`.
let max_segment = unsafe { bindings::dma_max_mapping_size(dev.as_raw()) };
if max_segment == 0 {
u32::MAX
} else {
u32::try_from(max_segment).unwrap_or(u32::MAX)
}
};Looks good, thanks!
Alexandre Courbot
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 35 lines · Danilo Krummrich
Quoted 24 lines · Alice Ryhl
Quoted 18 lines · Danilo Krummrich
Quoted 8 lines · Alice Ryhl
Quoted 8 lines
rust/kernel/scatterlist.rs new file +8
-0+impl <P >Owned <P > +where +for <'a>P : page::AsPageIter <Iter <'a> =VmallocPageIter <'a>> + 'static, +{ +fn new ( + dev: &Device <Bound >, +mut pages:P , + dir: dma::DataDirection,Quoted 8 lines
rust/kernel/scatterlist.rs line 326
Quoted 4 lines
rust/kernel/scatterlist.rs new file +4
-0+ flags: alloc::Flags, + ) -> Result<impl PinInit<Self, Error> + '_> { +let page_iter = pages.page_iter (); +let size = page_iter.size ();Variable naming here is confusing. There's another variable called size in an inner scope, and then afterwards in RawSGTable you use *this* size variable again.
Quoted 2 lines
I can change the size in the assignment block of
max_segmenttomax_size, or do you have other suggestions?How about just this?
Quoted 9 lines
let max_segment = { // SAFETY: `dev.as_raw()` is a valid pointer to a `struct device`. let max_segment = unsafe { bindings::dma_max_mapping_size(dev.as_raw()) }; if max_segment == 0 { u32::MAX } else { u32::try_from(max_segment).unwrap_or(u32::MAX) } };
Quoted 1 line
Looks good, thanks!
Would this also work? It's a bit shorter.
// SAFETY: dev.as_raw() is a valid pointer to a struct device.
let max_segment = match unsafe { bindings::dma_max_mapping_size(dev.as_raw()) } {
0 => u32::MAX,
max_segment => u32::try_from(max_segment).unwrap_or(u32::MAX),
};Alexandre Courbot
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
In reply to Danilo KrummrichQuoted 26 lines · Danilo Krummrich
Add a safe Rust abstraction for the kernel's scatter-gather list facilities (
struct scatterlistandstruct sg_table).This commit introduces
SGTable<T>, a wrapper that uses a type-state pattern to provide compile-time guarantees about ownership and lifetime.The abstraction provides two primary states:
-SGTable<Owned<P>>: Represents a table whose resources are fully managed by Rust. It takes ownership of a page providerP, allocates the underlyingstruct sg_table, maps it for DMA, and handles all cleanup automatically upon drop. The DMA mapping's lifetime is tied to the associated device usingDevres, ensuring it is correctly unmapped before the device is unbound.
-SGTable<Borrowed>(or justSGTable): A zero-cost representation of an externally managedstruct sg_table. It is created from a raw pointer usingSGTable::as_ref()and provides a lifetime-bound reference (&'a SGTable) for operations like iteration.The API exposes a safe iterator that yields
&SGEntryreferences, allowing drivers to easily access the DMA address and length of each segment in the list.Co-developed-by Abdiel Janulgue <[email protected]>Signed-off-by Abdiel Janulgue <[email protected]>Signed-off-by Danilo Krummrich <[email protected]>---
<snip>
rust/kernel/scatterlist.rs line 70
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+impl SGEntry { +/// Convert a raw `struct scatterlist *` to a `&'a SGEntry`. +/// +/// # Safety +/// +/// Callers must ensure that the `struct scatterlist` pointed to by `ptr` is valid for the +/// lifetime `'a`. +#[inline] +unsafe fn from_raw <'a>(ptr: *mut bindings::scatterlist ) -> &'aSelf { +// SAFETY: The safety requirements of this function guarantee that `ptr` is a valid pointer
nit: "guarantees".
<snip>
rust/kernel/scatterlist.rs line 134
Quoted 4 lines
rust/kernel/scatterlist.rs new file +4
-0+impl SGTable { +/// Creates a borrowed `&'a SGTable` from a raw `struct sg_table` pointer. +/// +/// This allows safe access to an `sg_table` that is managed elsewhere (for example, in C code).
nit: "to a".
Quoted 23 lines
rust/kernel/scatterlist.rs new file +23
-0+/// +/// # Safety +/// +/// Callers must ensure that: +/// +/// - the `struct sg_table` pointed to by `ptr` is valid for the entire lifetime of `'a`, +/// - the data behind `ptr` is not modified concurrently for the duration of `'a`. +#[inline] +pub unsafe fn from_raw <'a>(ptr: *mut bindings::sg_table ) -> &'aSelf { +// SAFETY: The safety requirements of this function guarantee that `ptr` is a valid pointer +// to a `struct sg_table` for the duration of `'a`. +unsafe { &*ptr.cast () } + } + +#[inline] +fn as_raw (&self) -> *mut bindings::sg_table { + self.inner.0 .get () + } + +fn as_iter (&self) ->SGTableIter <'_> { +// SAFETY: `self.as_raw()` is a valid pointer to a `struct sg_table`. +let ptr =unsafe { (*self.as_raw ()).sgl }; +
rust/kernel/scatterlist.rs line 167
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+// SAFETY: `ptr` is guaranteed to be a valid pointer to a `struct scatterlist`. +let pos =Some (unsafe {SGEntry ::from_raw (ptr) }); + +SGTableIter { pos } + } +} + +/// # Invariants +/// +/// - `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`].
nit: "of the".
rust/kernel/scatterlist.rs line 169
Quoted 2 lines
rust/kernel/scatterlist.rs new file +2
-0+/// - `sgt` is always DMA mapped. +struct DmaMapSgt {
Minor point: I'd call this structure DmaMappedSgt to highlight the fact that it is actively mapped. Or alternatively document it and its members so that fact is clear.
<snip>
rust/kernel/scatterlist.rs line 451
Quoted 9 lines
rust/kernel/scatterlist.rs new file +9
-0+impl <'a>IntoIterator for &'aSGTable { +type Item = &'aSGEntry ; +type IntoIter =SGTableIter <'a>; + +#[inline] +fn into_iter (self) ->Self ::IntoIter { + self.as_iter () + } +}
While using this for Nova, I found it a bit unnatural having to call into_iter on references intead of just having an iter method. into_iter sounds like the passed object is consumed, while it is actually its (copied) reference that is. Why not have a regular iter method on SGTable? Actually we do have one, but it is called as_iter and is private for some reason. :)
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+ +/// An [`Iterator`] over the [`SGEntry`] items of an [`SGTable`]. +pub struct SGTableIter <'a> { + pos:Option <&'aSGEntry >, +} + +impl <'a>Iterator for SGTableIter <'a> { +type Item = &'aSGEntry ; + +fn next (&mut self) ->Option <Self ::Item > {
rust/kernel/scatterlist.rs line 471
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+let entry = self.pos?; + +// SAFETY: `entry.as_raw()` is a valid pointer to a `struct scatterlist`. +let next =unsafe { bindings::sg_next (entry.as_raw ()) }; + + self.pos = (!next.is_null ()).then (|| { +// SAFETY: If `next` is not NULL, `sg_next()` guarantees to return a valid pointer to +// the next `struct scatterlist`. +unsafe {SGEntry ::from_raw (next) } + });
This might be missing a stop condition.
For reasons I am not completely clear about, the number of mapped segments on the device side can be smaller than the number of scatterlists provided by the sg_table. This is highlighted by the documentation for dma_map_sg_attrs [1] ("Returns the number of mapped entries (which can be less than nents) on success") and sg_dma_address
[2] ("You should only work with the number of sg entries dma_map_sg returns, or alternatively stop on the first sg_dma_len(sg) which is 0.")
dma_map_sgtable stores the result of dma_map_sg_attrs into its nents member, and makes use of it in its iterator macros. See how the "regular" iterator and the "DMA" ones differ in their stop condition:
/*
* Loop over each sg element in the given sg_table object. */
#define for_each_sgtable_sg(sgt, sg, i) \ for_each_sg((sgt)->sgl, sg, (sgt)->orig_nents, i)
and
/*
* Loop over each sg element in the given *DMA mapped* sg_table object.
* Please use sg_dma_address(sg) and sg_dma_len(sg) to extract DMA addresses
* of the each element.
*/
#define for_each_sgtable_dma_sg(sgt, sg, i) \ for_each_sg((sgt)->sgl, sg, (sgt)->nents, i)
The DMA variant being the only one valid for accessing the DMA address and DMA length (the C does not enforce this however).
So only calling sg_next until we reach the end of the list carries the risk that we iterate on more items than we should, with the extra ones having their length at 0 (which is likely to be a no-op, but is still incorrect or at the very least inefficient). We can avoid this by either storing the value of nents in the iterator, or, (which might be simpler) follow the advice given by the documentation of sg_dma_address and also stop if the DMA length of the next one is zero.
[1] https://elixir.bootlin.com/linux/v6.16/source/kernel/dma/mapping.c#L233
[2] https://elixir.bootlin.com/linux/v6.16/source/include/linux/scatterlist.h#L31
Danilo Krummrich
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 12 lines · Alexandre Courbot
rust/kernel/scatterlist.rs line 70
Quoted 10 lines · Danilo Krummrich
rust/kernel/scatterlist.rs new file +10
-0+impl SGEntry { +/// Convert a raw `struct scatterlist *` to a `&'a SGEntry`. +/// +/// # Safety +/// +/// Callers must ensure that the `struct scatterlist` pointed to by `ptr` is valid for the +/// lifetime `'a`. +#[inline] +unsafe fn from_raw <'a>(ptr: *mut bindings::scatterlist ) -> &'aSelf { +// SAFETY: The safety requirements of this function guarantee that `ptr` is a valid pointer
Quoted 1 line
nit: "guarantees".
"guarantee" seems correct to me; it's "requirements" not "requirement".
(I think we commonly use the plural, i.e. "requirements" even if we end up listing a single requirement only.)
Quoted 7 lines
<snip>
rust/kernel/scatterlist.rs line 134
Quoted 4 lines
rust/kernel/scatterlist.rs new file +4
-0+impl SGTable { +/// Creates a borrowed `&'a SGTable` from a raw `struct sg_table` pointer. +/// +/// This allows safe access to an `sg_table` that is managed elsewhere (for example, in C code). nit: "to a".
I'm not a native speaker, but I think "an" is correct, since "sg_table" is pronounced with a vowel sound, /ɛs/, at the beginning.
Quoted 27 lines
Quoted 27 lines
rust/kernel/scatterlist.rs new file +27
-0+/// +/// # Safety +/// +/// Callers must ensure that: +/// +/// - the `struct sg_table` pointed to by `ptr` is valid for the entire lifetime of `'a`, +/// - the data behind `ptr` is not modified concurrently for the duration of `'a`. +#[inline] +pub unsafe fn from_raw <'a>(ptr: *mut bindings::sg_table ) -> &'aSelf { +// SAFETY: The safety requirements of this function guarantee that `ptr` is a valid pointer +// to a `struct sg_table` for the duration of `'a`. +unsafe { &*ptr.cast () } + } + +#[inline] +fn as_raw (&self) -> *mut bindings::sg_table { + self.inner.0 .get () + } + +fn as_iter (&self) ->SGTableIter <'_> { +// SAFETY: `self.as_raw()` is a valid pointer to a `struct sg_table`. +let ptr =unsafe { (*self.as_raw ()).sgl }; + +// SAFETY: `ptr` is guaranteed to be a valid pointer to a `struct scatterlist`. +let pos =Some (unsafe {SGEntry ::from_raw (ptr) }); + + SGTableIter { pos }SGEntry
Quoted 8 lines
rust/kernel/scatterlist.rs line 167
Quoted 6 lines
rust/kernel/scatterlist.rs new file +6
-0+ } +} + +/// # Invariants +/// +/// - `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`]. nit: "of the".
This one I don't know for sure, maybe a native speaker can help.
I chose "for", since I think it indicates duration and "of" rather belonging, but I honestly don't know. :)
Quoted 8 lines
rust/kernel/scatterlist.rs line 169
Quoted 2 lines
rust/kernel/scatterlist.rs new file +2
-0+/// - `sgt` is always DMA mapped. +struct DmaMapSgt {Minor point: I'd call this structure
DmaMappedSgtto highlight the fact that it is actively mapped. Or alternatively document it and its members so that fact is clear.<snip>
Quoted 16 lines
rust/kernel/scatterlist.rs line 451
Quoted 9 lines
rust/kernel/scatterlist.rs new file +9
-0+impl <'a>IntoIterator for &'aSGTable { +type Item = &'aSGEntry ; +type IntoIter =SGTableIter <'a>; + +#[inline] +fn into_iter (self) ->Self ::IntoIter { + self.as_iter () + } +}While using this for Nova, I found it a bit unnatural having to call
into_iteron references intead of just having anitermethod.into_itersounds like the passed object is consumed, while it is actually its (copied) reference that is. Why not have a regularitermethod onSGTable? Actually we do have one, but it is calledas_iterand is private for some reason. :)
I think it makes sense to rename to SGTable::iter() and make it public.
I'm also fine removing the IntoIterator implementation, it seems pretty unlikely that we'll have another type that provides an Iterator with SGEntry items we need a generic interface for.
Quoted 22 lines
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+ +/// An [`Iterator`] over the [`SGEntry`] items of an [`SGTable`]. +pub struct SGTableIter <'a> { + pos:Option <&'aSGEntry >, +} + +impl <'a>Iterator for SGTableIter <'a> { +type Item = &'aSGEntry ; + +fn next (&mut self) ->Option <Self ::Item > {rust/kernel/scatterlist.rs line 471
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+let entry = self.pos?; + +// SAFETY: `entry.as_raw()` is a valid pointer to a `struct scatterlist`. +let next =unsafe { bindings::sg_next (entry.as_raw ()) }; + + self.pos = (!next.is_null ()).then (|| { +// SAFETY: If `next` is not NULL, `sg_next()` guarantees to return a valid pointer to +// the next `struct scatterlist`. +unsafe {SGEntry ::from_raw (next) } + });This might be missing a stop condition.
[...]
Quoted 3 lines
follow the advice given by the documentation of
sg_dma_addressand also stop if the DMA length of the next one is zero.
Doh! I was even aware of this before sending the initial version and simply forgot to add this stop condition after having been interrupted.
Thanks a lot for catching this!
Alexandre Courbot
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 13 lines · Danilo Krummrich
Quoted 12 lines · Alexandre Courbot
Quoted 10 lines · Danilo Krummrich
rust/kernel/scatterlist.rs new file +10
-0+impl SGEntry { +/// Convert a raw `struct scatterlist *` to a `&'a SGEntry`. +/// +/// # Safety +/// +/// Callers must ensure that the `struct scatterlist` pointed to by `ptr` is valid for the +/// lifetime `'a`. +#[inline] +unsafe fn from_raw <'a>(ptr: *mut bindings::scatterlist ) -> &'aSelf { +// SAFETY: The safety requirements of this function guarantee that `ptr` is a valid pointer
Quoted 6 lines
Quoted 1 line
nit: "guarantees".
"guarantee" seems correct to me; it's "requirements" not "requirement".
(I think we commonly use the plural, i.e. "requirements" even if we end up listing a single requirement only.)
Ah, you are correct! I missed the plural on "requirements".
Quoted 11 lines
Quoted 8 lines
<snip>
rust/kernel/scatterlist.rs line 134
Quoted 4 lines
rust/kernel/scatterlist.rs new file +4
-0+impl SGTable { +/// Creates a borrowed `&'a SGTable` from a raw `struct sg_table` pointer. +/// +/// This allows safe access to an `sg_table` that is managed elsewhere (for example, in C code). nit: "to a".
I'm not a native speaker, but I think "an" is correct, since "
sg_table" is pronounced with a vowel sound, /ɛs/, at the beginning.
TIL. :)
Quoted 37 lines
Quoted 28 lines
Quoted 28 lines
rust/kernel/scatterlist.rs new file +27
-0+/// +/// # Safety +/// +/// Callers must ensure that: +/// +/// - the `struct sg_table` pointed to by `ptr` is valid for the entire lifetime of `'a`, +/// - the data behind `ptr` is not modified concurrently for the duration of `'a`. +#[inline] +pub unsafe fn from_raw <'a>(ptr: *mut bindings::sg_table ) -> &'aSelf { +// SAFETY: The safety requirements of this function guarantee that `ptr` is a valid pointer +// to a `struct sg_table` for the duration of `'a`. +unsafe { &*ptr.cast () } + } + +#[inline] +fn as_raw (&self) -> *mut bindings::sg_table { + self.inner.0 .get () + } + +fn as_iter (&self) ->SGTableIter <'_> { +// SAFETY: `self.as_raw()` is a valid pointer to a `struct sg_table`. +let ptr =unsafe { (*self.as_raw ()).sgl }; + +// SAFETY: `ptr` is guaranteed to be a valid pointer to a `struct scatterlist`. +let pos =Some (unsafe {SGEntry ::from_raw (ptr) }); + + SGTableIter { pos }SGEntryQuoted 8 lines
rust/kernel/scatterlist.rs line 167
Quoted 6 lines
rust/kernel/scatterlist.rs new file +6
-0+ } +} + +/// # Invariants +/// +/// - `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`]. nit: "of the".
Quoted 4 lines
This one I don't know for sure, maybe a native speaker can help.
I chose "for", since I think it indicates duration and "of" rather belonging, but I honestly don't know. :)
I didn't give enough context. I meant "of the [DmaMapSgt]" (as in, it cannot be any DmaMapSgt; it has to be this particular one).
Quoted 26 lines
Quoted 9 lines
rust/kernel/scatterlist.rs line 169
Quoted 3 lines
rust/kernel/scatterlist.rs new file +2
-0+/// - `sgt` is always DMA mapped. +struct DmaMapSgt {Minor point: I'd call this structure
DmaMappedSgtto highlight the fact that it is actively mapped. Or alternatively document it and its members so that fact is clear.<snip>
Quoted 16 lines
rust/kernel/scatterlist.rs line 451
Quoted 9 lines
rust/kernel/scatterlist.rs new file +9
-0+impl <'a>IntoIterator for &'aSGTable { +type Item = &'aSGEntry ; +type IntoIter =SGTableIter <'a>; + +#[inline] +fn into_iter (self) ->Self ::IntoIter { + self.as_iter () + } +}While using this for Nova, I found it a bit unnatural having to call
into_iteron references intead of just having anitermethod.into_itersounds like the passed object is consumed, while it is actually its (copied) reference that is. Why not have a regularitermethod onSGTable? Actually we do have one, but it is calledas_iterand is private for some reason. :)
Quoted 5 lines
I think it makes sense to rename to
SGTable::iter()and make it public.I'm also fine removing the IntoIterator implementation, it seems pretty unlikely that we'll have another type that provides an Iterator with SGEntry items we need a generic interface for.
I assumed there was some Rust pattern to this IntoIterator implementation on a reference, but I cannot see its usefulness when an iter method also works on a reference anyway. So yeah if there is no reason against it I think this would be more intuitive.
Quoted 26 lines
Quoted 23 lines
Quoted 11 lines
rust/kernel/scatterlist.rs new file +10
-0+ +/// An [`Iterator`] over the [`SGEntry`] items of an [`SGTable`]. +pub struct SGTableIter <'a> { + pos:Option <&'aSGEntry >, +} + +impl <'a>Iterator for SGTableIter <'a> { +type Item = &'aSGEntry ; + +fn next (&mut self) ->Option <Self ::Item > {rust/kernel/scatterlist.rs line 471
Quoted 10 lines
rust/kernel/scatterlist.rs new file +10
-0+let entry = self.pos?; + +// SAFETY: `entry.as_raw()` is a valid pointer to a `struct scatterlist`. +let next =unsafe { bindings::sg_next (entry.as_raw ()) }; + + self.pos = (!next.is_null ()).then (|| { +// SAFETY: If `next` is not NULL, `sg_next()` guarantees to return a valid pointer to +// the next `struct scatterlist`. +unsafe {SGEntry ::from_raw (next) } + });This might be missing a stop condition.
[...]
Quoted 8 lines
Quoted 3 lines
follow the advice given by the documentation of
sg_dma_addressand also stop if the DMA length of the next one is zero.Doh! I was even aware of this before sending the initial version and simply forgot to add this stop condition after having been interrupted.
Thanks a lot for catching this!
A detail whose knowledge is typically acquired through considerable suffering. :)
Re: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
In reply to Alexandre CourbotQuoted 11 lines · Alexandre Courbot
For reasons I am not completely clear about, the number of mapped segments on the device side can be smaller than the number of scatterlists provided by the
sg_table. This is highlighted by the documentation fordma_map_sg_attrs[1] ("Returns the number of mapped entries (which can be less than nents) on success") andsg_dma_address
[2] ("You should only work with the number of sg entriesdma_map_sgreturns, or alternatively stop on the firstsg_dma_len(sg)which is 0.")So only calling
sg_nextuntil we reach the end of the list carries the risk that we iterate on more items than we should, with the extra ones having their length at 0
Correct, this is misusing the API, and I don't know if the lengths are even guarenteed to be zero. To iterate the DMA list you must use the length of the DMA list returned by dma_map_sg() and nothing else as the stop condition.
To repeat again, the scatterlist data structure is "optimized" and contains two completely different lists - the CPU list and the DMA list. The DMA list is always <= the size of the CPU list.
For all purposes they are completely seperate things and we have a unique set of iterators and accessors for the CPU vs DMA data.
Jason
Danilo Krummrich
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 2 lines · Jason Gunthorpe
Correct, this is misusing the API, and I don't know if the lengths are even guarenteed to be zero.
Hopefully it is. Otherwise, it's not only the documentation if sg_dma_address() being wrong, but also a few drivers and maybe iommu_dma_unmap_sg(). However, since it's a specific implementation of the API, it might be correct relying on the sg_dma_len() == 0 check.
In any case, I think we can just use the nents field of struct sg_table, just like for_each_sgtable_dma_sg() does.
Alexandre Courbot
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
In reply to Danilo KrummrichOops, forgot to mention a couple more things:
Quoted 5 lines · Danilo Krummrich
Add a safe Rust abstraction for the kernel's scatter-gather list facilities (
struct scatterlistandstruct sg_table).This commit introduces
SGTable<T>, a wrapper that uses a type-state pattern to provide compile-time guarantees about ownership and lifetime.
Is this actually a typestate? From my understanding, the typestate pattern implies transitions from one state to the other (such as Unmapped -> Mapped), but in this version there are no such transitions (the previous ones had, though). We are just using a generic parameter, so mentioning typestate sounds a bit misleading to me.
Another random thought, in the owned case, do we want to provide an accessor to the provider of the backing pages? Or do we expect the caller to take dispositions to keep such a reference if they need to access the backing buffer post-mapping?
Danilo Krummrich
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 6 lines · Alexandre Courbot
Oops, forgot to mention a couple more things:
Quoted 3 lines · Danilo Krummrich
Add a safe Rust abstraction for the kernel's scatter-gather list facilities (
struct scatterlistandstruct sg_table).
Quoted 8 lines
Quoted 2 lines
This commit introduces
SGTable<T>, a wrapper that uses a type-state pattern to provide compile-time guarantees about ownership and lifetime.Is this actually a typestate? From my understanding, the typestate pattern implies transitions from one state to the other (such as Unmapped -> Mapped), but in this version there are no such transitions (the previous ones had, though). We are just using a generic parameter, so mentioning typestate sounds a bit misleading to me.
I'd argue that it's still kind of a typestate. You can derive &SGTable (i.e. &SGTable<Borrowed>) from SGTabe<Owned>. So, technically there is an uni-directional transition I guess.
Quoted 4 lines
Another random thought, in the owned case, do we want to provide an accessor to the provider of the backing pages? Or do we expect the caller to take dispositions to keep such a reference if they need to access the backing buffer post-mapping?
That's not going to work that easily. Once the backing pages are DMA mapped, the backing buffer can be accessed safely an more.
See also the safety requirements of dma::CoherentAllocation::as_slice() and dma::CoherentAllocation::as_slice_mut().
If we want to support that, we have to provide a new type for this and maybe want to define a common trait for DMA mapped memory accessors, etc.
Not the scope for this series, I believe. :)
Alexandre Courbot
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 16 lines · Danilo Krummrich
Quoted 6 lines · Alexandre Courbot
Oops, forgot to mention a couple more things:
Quoted 3 lines · Danilo Krummrich
Add a safe Rust abstraction for the kernel's scatter-gather list facilities (
struct scatterlistandstruct sg_table).Quoted 8 lines
Quoted 2 lines
This commit introduces
SGTable<T>, a wrapper that uses a type-state pattern to provide compile-time guarantees about ownership and lifetime.Is this actually a typestate? From my understanding, the typestate pattern implies transitions from one state to the other (such as Unmapped -> Mapped), but in this version there are no such transitions (the previous ones had, though). We are just using a generic parameter, so mentioning typestate sounds a bit misleading to me.
Quoted 3 lines
I'd argue that it's still kind of a typestate. You can derive &SGTable (i.e. &SGTable<Borrowed>) from SGTabe<Owned>. So, technically there is an uni-directional transition I guess.
That's technically correct, but is also not the intent of the design, at least compared to something like Unmapped <-> Mapped. Not a big problem if you prefer to keep the current naming though.
Quoted 11 lines
Quoted 5 lines
Another random thought, in the owned case, do we want to provide an accessor to the provider of the backing pages? Or do we expect the caller to take dispositions to keep such a reference if they need to access the backing buffer post-mapping?
That's not going to work that easily. Once the backing pages are DMA mapped, the backing buffer can be accessed safely an more.
See also the safety requirements of
dma::CoherentAllocation::as_slice()anddma::CoherentAllocation::as_slice_mut().
Yup. So couldn't similar accessors (marked unsafe of course) be convenient?
Quoted 5 lines
If we want to support that, we have to provide a new type for this and maybe want to define a common trait for DMA mapped memory accessors, etc.
Not the scope for this series, I believe. :)
I've had a few thoughts in that direction as well, but completely agree we should debate about this *after* this series is merged. :)
Danilo Krummrich
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 17 lines · Alexandre Courbot
Quoted 16 lines · Danilo Krummrich
Quoted 14 lines · Alexandre Courbot
Oops, forgot to mention a couple more things:
Quoted 5 lines · Danilo Krummrich
Add a safe Rust abstraction for the kernel's scatter-gather list facilities (
struct scatterlistandstruct sg_table).This commit introduces
SGTable<T>, a wrapper that uses a type-state pattern to provide compile-time guarantees about ownership and lifetime.Is this actually a typestate? From my understanding, the typestate pattern implies transitions from one state to the other (such as Unmapped -> Mapped), but in this version there are no such transitions (the previous ones had, though). We are just using a generic parameter, so mentioning typestate sounds a bit misleading to me.
Quoted 7 lines
Quoted 3 lines
I'd argue that it's still kind of a typestate. You can derive &SGTable (i.e. &SGTable<Borrowed>) from SGTabe<Owned>. So, technically there is an uni-directional transition I guess.
That's technically correct, but is also not the intent of the design, at least compared to something like Unmapped <-> Mapped. Not a big problem if you prefer to keep the current naming though.
I don't mind to name / call it differently, any suggestion?
Quoted 6 lines
Quoted 6 lines
Quoted 5 lines
Another random thought, in the owned case, do we want to provide an accessor to the provider of the backing pages? Or do we expect the caller to take dispositions to keep such a reference if they need to access the backing buffer post-mapping?
Quoted 8 lines
Quoted 5 lines
That's not going to work that easily. Once the backing pages are DMA mapped, the backing buffer can be accessed safely an more.
See also the safety requirements of
dma::CoherentAllocation::as_slice()anddma::CoherentAllocation::as_slice_mut().Yup. So couldn't similar accessors (marked unsafe of course) be convenient?
Absolutely! But I think we want them represented by a common trait that can be used by SGTable and dma::CoherentAllocation.
Quoted 8 lines
Quoted 5 lines
If we want to support that, we have to provide a new type for this and maybe want to define a common trait for DMA mapped memory accessors, etc.
Not the scope for this series, I believe. :)
I've had a few thoughts in that direction as well, but completely agree we should debate about this *after* this series is merged. :)
Yeah, let's add this feature subsequently.
Alexandre Courbot
maintainerRe: [PATCH v2 3/5] rust: scatterlist: Add type-state abstraction for sg_table
Quoted 22 lines · Danilo Krummrich
Quoted 21 lines · Alexandre Courbot
Quoted 19 lines · Danilo Krummrich
Quoted 6 lines · Alexandre Courbot
Oops, forgot to mention a couple more things:
Quoted 3 lines · Danilo Krummrich
Add a safe Rust abstraction for the kernel's scatter-gather list facilities (
struct scatterlistandstruct sg_table).Quoted 8 lines
Quoted 2 lines
This commit introduces
SGTable<T>, a wrapper that uses a type-state pattern to provide compile-time guarantees about ownership and lifetime.Is this actually a typestate? From my understanding, the typestate pattern implies transitions from one state to the other (such as Unmapped -> Mapped), but in this version there are no such transitions (the previous ones had, though). We are just using a generic parameter, so mentioning typestate sounds a bit misleading to me.
I'd argue that it's still kind of a typestate. You can derive &SGTable (i.e. &SGTable<Borrowed>) from SGTabe<Owned>. So, technically there is an uni-directional transition I guess.
Quoted 5 lines
Quoted 3 lines
That's technically correct, but is also not the intent of the design, at least compared to something like Unmapped <-> Mapped. Not a big problem if you prefer to keep the current naming though.
I don't mind to name / call it differently, any suggestion?
Simply using "generic parameter" would lift the possiblity for misinterpretation IMHO.
Danilo Krummrich
maintainerPATCH v2 4/5 samples: rust: dma: add sample code for SGTable
In reply to Danilo KrummrichAdd sample code for allocating and mapping a scatter-gather table (SGTable).
--- samples/rust/rust_dma.rs | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-)
samples/rust/rust_dma.rs +26 -9
@@ -7,15 +7,19 @@use kernel::{ bindings, device::Core , - dma::{CoherentAllocation ,Device ,DmaMask }, - pci, + dma::{CoherentAllocation ,DataDirection ,Device ,DmaMask }, + page, pci, prelude::*, + scatterlist::{Owned ,SGTable }, types::ARef , }; +#[pin_data( PinnedDrop )] struct DmaSampleDriver { pdev:ARef <pci::Device >, ca:CoherentAllocation <MyStruct >, +#[pin] + sgt:SGTable <Owned <VVec <u8 >>>, } const TEST_VALUES: [(u32, u32); 5] = [
@@ -70,21 +74,30 @@ fn probe(pdev: &pci::Device<Core>, _info: &Self::IdInfo) -> Result<Pin<KBox<Self kernel::dma_write!(ca[i] =MyStruct ::new (value.0 , value.1 ))?; } -let drvdata =KBox ::new ( -Self { +let size =4 * page::PAGE_SIZE ; +let pages =VVec ::with_capacity (size,GFP_KERNEL )?; + +let sgt =SGTable ::new (pdev.as_ref (), pages,DataDirection ::ToDevice ,GFP_KERNEL ); + +let drvdata =KBox ::pin_init ( +try_pin_init! (Self { pdev: pdev.into (), ca, - }, + sgt <- sgt, + }),GFP_KERNEL , )?; -Ok (drvdata.into ()) +Ok (drvdata) } } -impl Drop for DmaSampleDriver { -fn drop (&mut self) { -dev_info! (self.pdev.as_ref (),"Unload DMA test driver.\n" ); +#[pinned_drop] +impl PinnedDrop for DmaSampleDriver { +fn drop (self:Pin <&mut Self >) { +let dev = self.pdev.as_ref (); + +dev_info! (dev,"Unload DMA test driver.\n" );for (i, value)in TEST_VALUES .into_iter ().enumerate () {let val0 = kernel::dma_read!(self.ca[i].h);
@@ -99,6 +112,10 @@ fn drop(&mut self) {assert_eq! (val1, value.1 ); } } + +for (i, entry)in self.sgt.into_iter ().enumerate () { +dev_info! (dev,"Entry[{}]: DMA address: {:#x}" , i, entry.dma_address ()); + } } }
Signature · 1 line
2.50.1
Danilo Krummrich
maintainerPATCH v2 5/5 MAINTAINERS: rust: dma: add scatterlist files
In reply to Danilo KrummrichRename the "DMA MAPPING HELPERS DEVICE DRIVER API [RUST]" maintainers entry to "DMA MAPPING & SCATTERLIST API [RUST]" and add the corresponding scatterlist files.
--- MAINTAINERS | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
MAINTAINERS +3 -1
@@ -7238,7 +7238,7 @@ F: include/linux/dma-mapping.h F: include/linux/swiotlb.h F: kernel/dma/ -DMA MAPPING HELPERS DEVICE DRIVER API [RUST] +DMA MAPPING & SCATTERLIST API [RUST] M: Abdiel Janulgue <[email protected]> M: Danilo Krummrich <[email protected]> R: Daniel Almeida <[email protected]>
@@ -7249,7 +7249,9 @@ S: Supported W: https://rust-for-linux.com T: git https://github.com/Rust-for-Linux/linux.git alloc-next F: rust/helpers/dma.c +F: rust/helpers/scatterlist.c F: rust/kernel/dma.rs +F: rust/kernel/scatterlist.rs F: samples/rust/rust_dma.rs DMA-BUF HEAPS FRAMEWORK
Signature · 1 line
2.50.1
Alice Ryhl
maintainerQuoted 5 lines · Danilo Krummrich
Changes in v2:
- Switch to an enum impl for DmaDirection utilizing compile time boundary checks.
- Add missing Send/ Sync impls.
- Renameas_ref()tofrom_raw().
Thanks, but it's still as_ref() in the cover letter.
Alice
Quoted 45 lines · Danilo Krummrich
This patch series provides abstractions for struct
sg_tableand struct scatterlist.Abdiel and me agreed for me to take over his previous iterations on this topic. I decided to send my patches as a new series rather than as a subsequent version of Abdiel's previous iterations, since the changes I made turned out to be much closer to a full rewrite.
The most notable differences in design are:
- SGTable utilizes BorrowedPage, AsPageIter and VmallocPageIter from my patch
series in [1].- SGTable is a transparent wrapper over either struct Owned<P> (where P is the provider of the backing pages) or struct Borrowed, which by itself is a transparent wrapper over Opaque<bindings::sg_table>, i.e. either SGTable<Owned<P>> or just SGTable (which is equivalent to SGTable<Borrowed>.
-
SGTable<Owned<P>>: Represents a table whose resources are fully managed by Rust. It takes ownership of a page providerP, allocates the underlyingstruct sg_table, maps it for DMA, and handles all cleanup automatically upon drop. The DMA mapping's lifetime is tied to the associated device usingDevres, ensuring it is correctly unmapped before the device is unbound.-
SGTable<Borrowed>(or justSGTable): A zero-cost representation of an externally managedstruct sg_table. It is created from a raw pointer usingSGTable::as_ref()and provides a lifetime-bound reference (&'a SGTable) for operations like iteration.- As a consequence, a borrowed SG table can be created with
SGTable::as_ref(), which returns a &'a SGTable, just like similar existing abstractions.An owned SGTable is created with
SGTable::new(), which returns an impl PinInit<SGTable<Owned<P>>, Error>, such that it can be initialized directly within existing private data memory allocations while providing the required pin guarantees.- SGTable<Owned<P>> uses an inner type Devres<DmaMapSgt> to ensure that the DMA mapping can't out-live device unbind.
- SGTable<Owned<P>> uses pin-init for initialization.
Quoted 8 lines
This patch series depends on [1] (branch containing the patches in [2]). A branch containing this series (including dependencies) can be found in [3]; Abdiel's latest series can be found in [4].
[1] https://lore.kernel.org/rust-for-linux/[email protected]/
[2] https://git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=page-iter
[3] https://git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=scatterlist
[4] https://lore.kernel.org/lkml/[email protected]/
I am going to do a full review of this revision over the weekend, but I have already successfully used it in nova-core to boot the GSP. Thus,