Skip to contentSkip to conversation

Rust infrastructure for sg_table and scatterlist

PATCH Superseded Danilo Krummrich 4 participants 26 messages Aug 15, 2025 – Aug 20, 2025

Subsystems (2)

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Danilo Krummrich

author maintainer
#0 lore raw

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]/

Danilo Krummrich (4):
rust: dma: implement DataDirection
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 +-
 rust/bindings/bindings_helper.h |   1 +
 rust/helpers/helpers.c          |   1 +
 rust/helpers/scatterlist.c      |  24 ++
 rust/kernel/dma.rs              |  41 +++
 rust/kernel/lib.rs              |   1 +
 rust/kernel/scatterlist.rs      | 433 ++++++++++++++++++++++++++++++++
 samples/rust/rust_dma.rs        |  35 ++-
 8 files changed, 530 insertions(+), 10 deletions(-)
 create mode 100644 rust/helpers/scatterlist.c
 create mode 100644 rust/kernel/scatterlist.rs

base-commit: a66548bf306b60441ed2ea6b034a0cd69f464e74

Signature · 1 line
2.50.1
author maintainer
#1 lore raw

PATCH 1/4 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              | 41 +++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
rust/bindings/bindings_helper.h +1 -0
index 0e140e07758b..c2cc52ee9945 100644
@@ -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 +41 -0

47 lines not on this page · raw message

Signature · 1 line
2.50.1
reviewer
#2 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 8 lines · Danilo Krummrich

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/kernel/dma.rs pub mod attrs { · line 253

Quoted 7 lines
rust/kernel/dma.rs +7 -0
+/// 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)]
+pub struct DataDirection(bindings::dma_data_direction);

Perhaps this should be a real Rust enum so that you can do an exhaustive match?

Quoted 32 lines
rust/kernel/dma.rs +32 -0
+impl DataDirection {
+    /// 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.
+    pub const BIDIRECTIONAL: DataDirection =
+        DataDirection(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.
+    pub const TO_DEVICE: DataDirection = DataDirection(bindings::dma_data_direction_DMA_TO_DEVICE);
+
+    /// The DMA mapping is for data transfer from the device to memory (read).
+    ///
+    /// The device will write data into the buffer for the CPU to read.
+    /// The cache for the corresponding memory region is invalidated before CPU access.
+    pub const FROM_DEVICE: DataDirection =
+        DataDirection(bindings::dma_data_direction_DMA_FROM_DEVICE);
+
+    /// The DMA mapping is not for data transfer.
+    ///
+    /// This is primarily for debugging purposes. With this direction, the DMA mapping API
+    /// will not perform any cache coherency operations.
+    pub const NONE: DataDirection = DataDirection(bindings::dma_data_direction_DMA_NONE);
+
+    /// Returns the raw representation of [`enum dma_data_direction`].
+    pub fn as_raw(self) -> bindings::dma_data_direction {
+        self.0
+    }
+}
author maintainer
#3 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 9 lines · Alice Ryhl
Quoted 7 lines · Danilo Krummrich

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.

Quoted 10 lines

rust/kernel/dma.rs pub mod attrs { · line 253

Quoted 7 lines
rust/kernel/dma.rs +7 -0
+/// 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)]
+pub struct DataDirection(bindings::dma_data_direction);

Perhaps this should be a real Rust enum so that you can do an exhaustive match?

	/// 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(i32)]

Does bindgen ever pick another type than i32 for C enums? If so, it'd be a downside that we'd have to mess with the type either in the repr or by casting the variants.

	pub enum DataDirection {
	    /// 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 = 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.
	    ToDevice = bindings::dma_data_direction_DMA_TO_DEVICE,
	
	    /// The DMA mapping is for data transfer from the device to memory (read).
	    ///
	    /// The device will write data into the buffer for the CPU to read.
	    /// The cache for the corresponding memory region is invalidated before CPU access.
	    FromDevice = bindings::dma_data_direction_DMA_FROM_DEVICE,
	
	    /// The DMA mapping is not for data transfer.
	    ///
	    /// This is primarily for debugging purposes. With this direction, the DMA mapping API
	    /// will not perform any cache coherency operations.
	    None = bindings::dma_data_direction_DMA_NONE,
	}
	
	impl From<DataDirection> for bindings::dma_data_direction {
	    /// Returns the raw representation of [`enum dma_data_direction`].
	    fn from(direction: DataDirection) -> Self {
	        direction as Self
	    }
	}
#4 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 4 lines · Danilo Krummrich

Does bindgen ever pick another type than i32 for C enums? If so, it'd be a downside that we'd have to mess with the type either in the repr or by casting the variants.

Yes, it can easily pick u32 -- the variants are always int in C, but the actual enum can be a type compatible with int, unsigned or char; and bindgen generates each variant with a type alias to the underlying type of the enum, not int.

So e.g. for

    enum uint_enum { uint_enum_a, uint_enum_b };
    enum int_enum { int_enum_a = -1, int_enum_b };

    _Static_assert(_Generic(uint_enum_a, int: 1, default: 0), "");
    _Static_assert(_Generic(uint_enum_b, int: 1, default: 0), "");
    _Static_assert(_Generic(int_enum_a, int: 1, default: 0), "");
    _Static_assert(_Generic(int_enum_b, int: 1, default: 0), "");

    _Static_assert(_Generic((enum uint_enum)0, unsigned: 1, default: 0), "");
    _Static_assert(_Generic((enum int_enum)0, int: 1, default: 0), "");

you get:

    pub const uint_enum_uint_enum_a: uint_enum = 0;
    pub const uint_enum_uint_enum_b: uint_enum = 1;
    pub type uint_enum = ffi::c_uint;

    pub const int_enum_int_enum_a: int_enum = -1;
    pub const int_enum_int_enum_b: int_enum = 0;
    pub type int_enum = ffi::c_int;

Then there is this issue I reported to be careful about, which can change it back to i32 if there is a forward reference:

    https://github.com/rust-lang/rust-bindgen/issues/3179

I hope that helps.

Cheers,
Miguel

#5 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 2 lines · Miguel Ojeda

Yes, it can easily pick u32 -- the variants are always int in C,

And, for completeness, if the kernel eventually uses C23 enums (I don't see any, from a quick grep), i.e. with an underlying type, then in C the variants will actually have that type, not int:

    enum c23_enum : short { c23_enum_a, c23_enum_b };

    _Static_assert(_Generic(c23_enum_a, short: 1, default: 0), "");
    _Static_assert(_Generic(c23_enum_b, short: 1, default: 0), "");

    _Static_assert(_Generic((enum c23_enum)0, short: 1, default: 0), "");

And bindgen will have the underlying type too, so everything matches in that case:

    pub const c23_enum_c23_enum_a: c23_enum = 0;
    pub const c23_enum_c23_enum_b: c23_enum = 1;
    pub type c23_enum = ffi::c_short;

So, in a way, what bindgen tries to do (for the normal ones) is behave a bit like these new ones.

But I always wondered if it is good or not differing there.

Cheers,
Miguel

reviewer
#7 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

In reply to Danilo Krummrich
Quoted 57 lines · Danilo Krummrich
Quoted 9 lines · Alice Ryhl
Quoted 7 lines · Danilo Krummrich

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.

Quoted 10 lines

rust/kernel/dma.rs pub mod attrs { · line 253

Quoted 7 lines
rust/kernel/dma.rs +7 -0
+/// 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)]
+pub struct DataDirection(bindings::dma_data_direction);

Perhaps this should be a real Rust enum so that you can do an exhaustive match?

	/// 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(i32)]

Does bindgen ever pick another type than i32 for C enums? If so, it'd be a downside that we'd have to mess with the type either in the repr or by casting the variants.

	pub enum DataDirection {
	    /// 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 = 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.
	    ToDevice = bindings::dma_data_direction_DMA_TO_DEVICE,
	
	    /// The DMA mapping is for data transfer from the device to memory (read).
	    ///
	    /// The device will write data into the buffer for the CPU to read.
	    /// The cache for the corresponding memory region is invalidated before CPU access.
	    FromDevice = bindings::dma_data_direction_DMA_FROM_DEVICE,
	
	    /// The DMA mapping is not for data transfer.
	    ///
	    /// This is primarily for debugging purposes. With this direction, the DMA mapping API
	    /// will not perform any cache coherency operations.
	    None = bindings::dma_data_direction_DMA_NONE,
Quoted 8 lines
	}
	
	impl From<DataDirection> for bindings::dma_data_direction {
	    /// Returns the raw representation of [`enum dma_data_direction`].
	    fn from(direction: DataDirection) -> Self {
	        direction as Self
	    }
	}

My suggestion is to cast on the Rust-side.

#[repr(whateveryouwant)]
enum DataDirection {
Bidirectional = bindings::dma_data_direction_DMA_BIDIRECTIONAL as _,
}

author maintainer
#8 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 67 lines · Alice Ryhl
Quoted 57 lines · Danilo Krummrich
Quoted 9 lines · Alice Ryhl
Quoted 7 lines · Danilo Krummrich

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.

Quoted 10 lines

rust/kernel/dma.rs pub mod attrs { · line 253

Quoted 7 lines
rust/kernel/dma.rs +7 -0
+/// 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)]
+pub struct DataDirection(bindings::dma_data_direction);

Perhaps this should be a real Rust enum so that you can do an exhaustive match?

	/// 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(i32)]

Does bindgen ever pick another type than i32 for C enums? If so, it'd be a downside that we'd have to mess with the type either in the repr or by casting the variants.

	pub enum DataDirection {
	    /// 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 = 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.
	    ToDevice = bindings::dma_data_direction_DMA_TO_DEVICE,
	
	    /// The DMA mapping is for data transfer from the device to memory (read).
	    ///
	    /// The device will write data into the buffer for the CPU to read.
	    /// The cache for the corresponding memory region is invalidated before CPU access.
	    FromDevice = bindings::dma_data_direction_DMA_FROM_DEVICE,
	
	    /// The DMA mapping is not for data transfer.
	    ///
	    /// This is primarily for debugging purposes. With this direction, the DMA mapping API
	    /// will not perform any cache coherency operations.
	    None = bindings::dma_data_direction_DMA_NONE,
Quoted 8 lines
	}
	
	impl From<DataDirection> for bindings::dma_data_direction {
	    /// Returns the raw representation of [`enum dma_data_direction`].
	    fn from(direction: DataDirection) -> Self {
	        direction as Self
	    }
	}
Quoted 3 lines

My suggestion is to cast on the Rust-side.

#[repr(whateveryouwant)]

What's your suggestion for whateveryouwant?

And I mean this in general, not only for this case of dma::DataDirection. If we pick u32 than things break if a negative enum variant is added on the C side. If we pick i32, it can happen that we overflow.

Quoted 2 lines

enum DataDirection {
Bidirectional = bindings::dma_data_direction_DMA_BIDIRECTIONAL as _,

We have a clippy lint that warns about as _ casts, but I guess you meant as whateveryouwant. However, if bindgen picks whateveryouwant too, we also get a warning.

Ultimately, we'd need to suppress a warning.

Quoted 1 line

}

reviewer
#9 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 79 lines · Danilo Krummrich
Quoted 67 lines · Alice Ryhl
Quoted 57 lines · Danilo Krummrich
Quoted 9 lines · Alice Ryhl
Quoted 7 lines · Danilo Krummrich

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.

Quoted 10 lines

rust/kernel/dma.rs pub mod attrs { · line 253

Quoted 7 lines
rust/kernel/dma.rs +7 -0
+/// 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)]
+pub struct DataDirection(bindings::dma_data_direction);

Perhaps this should be a real Rust enum so that you can do an exhaustive match?

     /// 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(i32)]

Does bindgen ever pick another type than i32 for C enums? If so, it'd be a downside that we'd have to mess with the type either in the repr or by casting the variants.

     pub enum DataDirection {
         /// 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 = 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.
         ToDevice = bindings::dma_data_direction_DMA_TO_DEVICE,

         /// The DMA mapping is for data transfer from the device to memory (read).
         ///
         /// The device will write data into the buffer for the CPU to read.
         /// The cache for the corresponding memory region is invalidated before CPU access.
         FromDevice = bindings::dma_data_direction_DMA_FROM_DEVICE,

         /// The DMA mapping is not for data transfer.
         ///
         /// This is primarily for debugging purposes. With this direction, the DMA mapping API
         /// will not perform any cache coherency operations.
         None = bindings::dma_data_direction_DMA_NONE,
Quoted 8 lines
     }

     impl From<DataDirection> for bindings::dma_data_direction {
         /// Returns the raw representation of [`enum dma_data_direction`].
         fn from(direction: DataDirection) -> Self {
             direction as Self
         }
     }
Quoted 3 lines

My suggestion is to cast on the Rust-side.

#[repr(whateveryouwant)]

What's your suggestion for whateveryouwant?

And I mean this in general, not only for this case of dma::DataDirection. If we pick u32 than things break if a negative enum variant is added on the C side. If we pick i32, it can happen that we overflow.

Quoted 8 lines
Quoted 2 lines

enum DataDirection {
Bidirectional = bindings::dma_data_direction_DMA_BIDIRECTIONAL as _,

We have a clippy lint that warns about as _ casts, but I guess you meant as whateveryouwant. However, if bindgen picks whateveryouwant too, we also get a warning.

Ultimately, we'd need to suppress a warning.

In general, I think we want some sort of helper function to cast between arbitrary integer types in const-evaluation that panics if the cast is out of bounds. Both here and many other places.

Alice

author maintainer
#10 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 3 lines · Alice Ryhl

In general, I think we want some sort of helper function to cast between arbitrary integer types in const-evaluation that panics if the cast is out of bounds. Both here and many other places.

What exactly do you have in mind?

reviewer
#11 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 7 lines · Danilo Krummrich
Quoted 3 lines · Alice Ryhl

In general, I think we want some sort of helper function to cast between arbitrary integer types in const-evaluation that panics if the cast is out of bounds. Both here and many other places.

What exactly do you have in mind?

        pub enum DataDirection {
            /// 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 =
const_cast(bindings::dma_data_direction_DMA_BIDIRECTIONAL),

with no warnings and build-failure if out-of-bounds.

Alice

author maintainer
#12 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 1 line · Alice Ryhl

with no warnings and build-failure if out-of-bounds.

+/// 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 {

+    /// 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.
+    ToDevice = Self::const_cast(bindings::dma_data_direction_DMA_TO_DEVICE),
+
+    /// The DMA mapping is for data transfer from the device to memory (read).
+    ///
+    /// The device will write data into the buffer for the CPU to read.
+    /// The cache for the corresponding memory region is invalidated before CPU access.
+    FromDevice = Self::const_cast(bindings::dma_data_direction_DMA_FROM_DEVICE),
+
+    /// The DMA mapping is not for data transfer.
+    ///
+    /// This is primarily for debugging purposes. With this direction, the DMA mapping API
+    /// will not perform any cache coherency operations.
+    None = Self::const_cast(bindings::dma_data_direction_DMA_NONE),
+}
+
+impl DataDirection {
+    /// Casts the bindgen-generated enum type to a `u32` at compile time.
+    ///
+    /// This function will cause a compile-time error if the underlying value of the
+    /// C enum is out of bounds for `u32`.
+    const fn const_cast(val: bindings::dma_data_direction) -> u32 {
+        // CAST: The C standard allows compilers to choose different integer types for enums.
+        // To safely check the value, we cast it to a wide signed integer type (`i128`)
+        // which can hold any standard C integer enum type without truncation.
+        let wide_val = val as i128;
+
+        // Check if the value is outside the valid range for the target type `u32`.
+        // CAST: `u32::MAX` is cast to `i128` to match the type of `wide_val` for the comparison.
+        if wide_val < 0 || wide_val > u32::MAX as i128 {

+ // Trigger a compile-time error in a const context.
+ panic!("C enum value is out of bounds for the target type u32.");
+ }
+

+        // CAST: This cast is valid because the check above guarantees that `wide_val`
+        // is within the representable range of `u32`.
+        wide_val as u32

+ }
+}
+
+impl From<DataDirection> for bindings::dma_data_direction {
+ /// Returns the raw representation of [enum dma_data_direction].
+ fn from(direction: DataDirection) -> Self {

+        // CAST: `direction as u32` gets the underlying representation of our `#[repr(u32)]` enum.
+        // The subsequent cast to `Self` (the bindgen type) assumes the C enum is compatible
+        // with the enum variants of `DataDirection`, which is a valid assumption given our
+        // compile-time checks.
+        direction as u32 as Self

+ }
+}

#13 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 36 lines · Danilo Krummrich
Quoted 1 line · Alice Ryhl

with no warnings and build-failure if out-of-bounds.

(quoted diff) +29 -0
+/// 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 {
+    /// 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.
+    ToDevice = Self::const_cast(bindings::dma_data_direction_DMA_TO_DEVICE),
+
+    /// The DMA mapping is for data transfer from the device to memory (read).
+    ///
+    /// The device will write data into the buffer for the CPU to read.
+    /// The cache for the corresponding memory region is invalidated before CPU access.
+    FromDevice = Self::const_cast(bindings::dma_data_direction_DMA_FROM_DEVICE),
+
+    /// The DMA mapping is not for data transfer.
+    ///
+    /// This is primarily for debugging purposes. With this direction, the DMA mapping API

Review

Quoted 10 lines
(quoted diff) +10 -0
+    /// will not perform any cache coherency operations.
+    None = Self::const_cast(bindings::dma_data_direction_DMA_NONE),
+}
+
+impl DataDirection {
+    /// Casts the bindgen-generated enum type to a `u32` at compile time.
+    ///
+    /// This function will cause a compile-time error if the underlying value of the
+    /// C enum is out of bounds for `u32`.
+    const fn const_cast(val: bindings::dma_data_direction) -> u32 {

This should be its own generic helper for similar enums, IMHO

Quoted 28 lines
(quoted diff) +28 -0
+        // CAST: The C standard allows compilers to choose different integer types for enums.
+        // To safely check the value, we cast it to a wide signed integer type (`i128`)
+        // which can hold any standard C integer enum type without truncation.
+        let wide_val = val as i128;
+
+        // Check if the value is outside the valid range for the target type `u32`.
+        // CAST: `u32::MAX` is cast to `i128` to match the type of `wide_val` for the comparison.
+        if wide_val < 0 || wide_val > u32::MAX as i128 {
+            // Trigger a compile-time error in a const context.
+            panic!("C enum value is out of bounds for the target type `u32`.");
+        }
+
+        // CAST: This cast is valid because the check above guarantees that `wide_val`
+        // is within the representable range of `u32`.
+        wide_val as u32
+    }
+}
+
+impl From<DataDirection> for bindings::dma_data_direction {
+    /// Returns the raw representation of [`enum dma_data_direction`].
+    fn from(direction: DataDirection) -> Self {
+        // CAST: `direction as u32` gets the underlying representation of our `#[repr(u32)]` enum.
+        // The subsequent cast to `Self` (the bindgen type) assumes the C enum is compatible
+        // with the enum variants of `DataDirection`, which is a valid assumption given our
+        // compile-time checks.
+        direction as u32 as Self
+    }
+}
author maintainer
#14 lore raw

Re: [PATCH 1/4] rust: dma: implement DataDirection

Quoted 40 lines · Daniel Almeida
Quoted 40 lines · Danilo Krummrich
Quoted 1 line · Alice Ryhl

with no warnings and build-failure if out-of-bounds.

(quoted diff) +33 -0
+/// 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 {
+    /// 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.
+    ToDevice = Self::const_cast(bindings::dma_data_direction_DMA_TO_DEVICE),
+
+    /// The DMA mapping is for data transfer from the device to memory (read).
+    ///
+    /// The device will write data into the buffer for the CPU to read.
+    /// The cache for the corresponding memory region is invalidated before CPU access.
+    FromDevice = Self::const_cast(bindings::dma_data_direction_DMA_FROM_DEVICE),
+
+    /// The DMA mapping is not for data transfer.
+    ///
+    /// This is primarily for debugging purposes. With this direction, the DMA mapping API
+    /// will not perform any cache coherency operations.
+    None = Self::const_cast(bindings::dma_data_direction_DMA_NONE),
+}
+
Quoted 8 lines

Review

Quoted 6 lines
(quoted diff) +6 -0
+impl DataDirection {
+    /// Casts the bindgen-generated enum type to a `u32` at compile time.
+    ///
+    /// This function will cause a compile-time error if the underlying value of the
+    /// C enum is out of bounds for `u32`.
+    const fn const_cast(val: bindings::dma_data_direction) -> u32 {

This should be its own generic helper for similar enums, IMHO

In general, I agree, but it may not be exactly straight forward (considering that it still needs to work from const context).

The function relies on the fact that both the argument and return type are numeric primitives, which need to fit into an i128. We could probably define a marker trait for such types, etc.

Yet, I don't know how we could do the casts from one generic type I to another generic type O. I think we'd need to implement traits for that as well. However, this would require the unstable const_trait_impl feature.

Hence, working this out (if even possible currently) and improving existing enum abstractions should be done independent from this series.

Quoted 28 lines
Quoted 28 lines
(quoted diff) +28 -0
+        // CAST: The C standard allows compilers to choose different integer types for enums.
+        // To safely check the value, we cast it to a wide signed integer type (`i128`)
+        // which can hold any standard C integer enum type without truncation.
+        let wide_val = val as i128;
+
+        // Check if the value is outside the valid range for the target type `u32`.
+        // CAST: `u32::MAX` is cast to `i128` to match the type of `wide_val` for the comparison.
+        if wide_val < 0 || wide_val > u32::MAX as i128 {
+            // Trigger a compile-time error in a const context.
+            panic!("C enum value is out of bounds for the target type `u32`.");
+        }
+
+        // CAST: This cast is valid because the check above guarantees that `wide_val`
+        // is within the representable range of `u32`.
+        wide_val as u32
+    }
+}
+
+impl From<DataDirection> for bindings::dma_data_direction {
+    /// Returns the raw representation of [`enum dma_data_direction`].
+    fn from(direction: DataDirection) -> Self {
+        // CAST: `direction as u32` gets the underlying representation of our `#[repr(u32)]` enum.
+        // The subsequent cast to `Self` (the bindgen type) assumes the C enum is compatible
+        // with the enum variants of `DataDirection`, which is a valid assumption given our
+        // compile-time checks.
+        direction as u32 as Self
+    }
+}
author maintainer
#15 lore raw

PATCH 2/4 rust: scatterlist: Add type-state abstraction for sg_table

In reply to Danilo Krummrich

Add 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 | 433 +++++++++++++++++++++++++++++++++++++
 4 files changed, 459 insertions(+)
 create mode 100644 rust/helpers/scatterlist.c
 create mode 100644 rust/kernel/scatterlist.rs
rust/helpers/helpers.c +1 -0
index 7cf7fe95e41d..e94542bf6ea7 100644
@@ -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
new file mode 100644
index 000000000000..80c956ee09ab
@@ -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
index ed53169e795c..55acbc893736 100644
@@ -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 +433 -0

433 lines not on this page · raw message

Signature · 1 line
2.50.1
reviewer
#16 lore raw

Re: [PATCH 2/4] rust: scatterlist: Add type-state abstraction for sg_table

Quoted 135 lines · Danilo Krummrich

Add 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 | 433 +++++++++++++++++++++++++++++++++++++
 4 files changed, 459 insertions(+)
 create mode 100644 rust/helpers/scatterlist.c
 create mode 100644 rust/kernel/scatterlist.rs
rust/helpers/helpers.c +1 -0
index 7cf7fe95e41d..e94542bf6ea7 100644
@@ -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
new file mode 100644
index 000000000000..80c956ee09ab
@@ -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
index ed53169e795c..55acbc893736 100644
@@ -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 +41 -0
new file mode 100644
index 000000000000..4caaf8cfbf83
@@ -0,0 +1,433 @@
+// 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, page,
+    prelude::*,
+    types::{ARef, Opaque},
+};
+use core::{ops::Deref, ptr::NonNull};

rust/kernel/scatterlist.rs line 51

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+
+/// 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>);

Send/Sync?

rust/kernel/scatterlist.rs line 60

Quoted 8 lines
rust/kernel/scatterlist.rs new file +8 -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`.
+    unsafe fn as_ref<'a>(ptr: *mut bindings::scatterlist) -> &'a Self {

Please call this from_raw.

rust/kernel/scatterlist.rs line 67

Quoted 7 lines
rust/kernel/scatterlist.rs new file +7 -0
+        // 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 *`.
+    fn as_raw(&self) -> *mut bindings::scatterlist {

Consider adding #[inline] to all these methods.

rust/kernel/scatterlist.rs line 74

Quoted 7 lines
rust/kernel/scatterlist.rs new file +7 -0
+        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.
+    pub fn dma_address(&self) -> bindings::dma_addr_t {

We might want a typedef on the Rust side for dma_addr_t, like we already have for the phys_addr_t/resource_size_t.

rust/kernel/scatterlist.rs line 80

Quoted 6 lines
rust/kernel/scatterlist.rs new file +6 -0
+        // 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.
+    pub fn dma_len(&self) -> u32 {

Is u32 really the right length type?

rust/kernel/scatterlist.rs line 91

Quoted 11 lines
rust/kernel/scatterlist.rs new file +11 -0
+        // SAFETY: `self.as_raw()` is a valid pointer to a `struct scatterlist`.
+        unsafe { bindings::sg_dma_len(self.as_raw()) }
+    }
+}
+
+/// The borrowed type state of an [`SGTable`], representing a borrowed or externally managed table.
+#[repr(transparent)]
+pub struct Borrowed(Opaque<bindings::sg_table>);
+
+// SAFETY: An instance of `Borrowed` can be send to any task.
+unsafe impl Send for Borrowed {}

No Sync?

Quoted 22 lines
rust/kernel/scatterlist.rs new file +21 -0
+/// 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,
+}
 

rust/kernel/scatterlist.rs line 124

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -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).
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that the `struct sg_table` pointed to by `ptr` is valid for the entire
+    /// lifetime of `'a`.
+    pub unsafe fn as_ref<'a>(ptr: *mut bindings::sg_table) -> &'a Self {

Please rename to from_raw().

rust/kernel/scatterlist.rs line 130

Quoted 6 lines
rust/kernel/scatterlist.rs new file +6 -0
+        // 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() }
+    }
+
+    fn as_raw(&self) -> *mut bindings::sg_table {

Ditto about #[inline] for these.

Quoted 7 lines
rust/kernel/scatterlist.rs new file +7 -0
+        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 147

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::as_ref(ptr) });
+
+        SGTableIter { pos }
+    }
+}
+
+/// # Invariants
+///
+/// `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`].

I think we probably want an invariant for why it's safe to call dma_unmap_sgtable in Drop.

rust/kernel/scatterlist.rs line 155

Quoted 8 lines
rust/kernel/scatterlist.rs new file +8 -0
+struct DmaMapSgt {
+    sgt: NonNull<bindings::sg_table>,
+    dev: ARef<Device>,
+    dir: dma::DataDirection,
+}
+
+// SAFETY: An instance of `DmaMapSgt` can be send to any task.
+unsafe impl Send for DmaMapSgt {}

No Sync?

Quoted 39 lines
rust/kernel/scatterlist.rs new file +39 -0
+impl DmaMapSgt {
+    /// # Safety
+    ///
+    /// `sgt` must be a valid pointer to a `struct sg_table` for the entire lifetime of the
+    /// returned [`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.as_raw(), 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 {
+    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.as_raw(), 0)

rust/kernel/scatterlist.rs line 205

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+        };
+    }
+}
+
+#[repr(transparent)]
+#[pin_data(PinnedDrop)]
+struct RawSGTable {
+    #[pin]
+    sgt: Opaque<bindings::sg_table>,
+}

Send/Sync?

Quoted 13 lines
rust/kernel/scatterlist.rs new file +13 -0
+impl RawSGTable {
+    fn new(
+        mut pages: KVec<*mut bindings::page>,
+        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);

rust/kernel/scatterlist.rs line 229

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+                }
+
+                // 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()?,

The pages vector is dropped immediately after this call to sg_alloc_table_from_pages_segment. Is that ok?

If it's ok, then I would change pages to &[*mut page] so that the caller can manage the allocation of the array.

(Or maybe a mutable array ...?)

Quoted 36 lines
rust/kernel/scatterlist.rs new file +36 -0
+                        0,
+                        size,
+                        max_segment,
+                        flags.as_raw(),
+                    )
+                })
+            }),
+        })
+    }
+
+    fn as_raw(&self) -> *mut bindings::sg_table {
+        self.sgt.get()
+    }
+}
+
+#[pinned_drop]
+impl PinnedDrop for RawSGTable {
+    fn drop(self: Pin<&mut Self>) {
+        // SAFETY: `sgt` is a valid and initialized `struct sg_table`.
+        unsafe { bindings::sg_free_table(self.sgt.get()) };
+    }
+}
+
+/// 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

rust/kernel/scatterlist.rs line 275

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+    // `struct sg_table` and finally free the backing pages.
+    #[pin]
+    dma: Devres<DmaMapSgt>,
+    #[pin]
+    sgt: RawSGTable,
+    _pages: P,
+}
+
+// SAFETY: An instance of `Owned` can be send to any task if `P` can be send to any task.
+unsafe impl<P: Send> Send for Owned<P> {}

Sync?

rust/kernel/scatterlist.rs line 279

Quoted 3 lines
rust/kernel/scatterlist.rs new file +3 -0
+impl<P> Owned<P>
+where
+    for<'a> P: page::AsPageIter<Iter<'a> = VmallocPageIter<'a>> + 'static,

If you specifically require the iterator type to be VmallocPageIter, then I would hard-code that in the trait instead of specifying it here.

But I think you just want P: AsPageIter.

rust/kernel/scatterlist.rs line 286

Quoted 7 lines
rust/kernel/scatterlist.rs new file +7 -0
+{
+    fn new(
+        dev: &Device<Bound>,
+        mut pages: P,
+        dir: dma::DataDirection,
+        flags: alloc::Flags,
+    ) -> Result<impl PinInit<Self, Error> + use<'_, P>> {

We would probably want to move the logic into the initializer so that we don't have the double Result here.

Quoted 9 lines
rust/kernel/scatterlist.rs new file +9 -0
+        let page_iter = pages.page_iter();
+        let size = page_iter.size();
+
+        let mut page_vec: KVec<*mut bindings::page> =
+            KVec::with_capacity(page_iter.page_count(), flags)?;
+
+        for page in page_iter {
+            page_vec.push(page.as_ptr(), flags)?;
+        }

rust/kernel/scatterlist.rs line 305

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+
+        // `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 {
+                size.min(u32::MAX as usize) as u32

u32::try_from(size).unwrap_or(u32::MAX)

Quoted 73 lines
rust/kernel/scatterlist.rs new file +73 -0
+            }
+        };
+
+        Ok(try_pin_init!(&this in Self {
+            sgt <- RawSGTable::new(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`.
+                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::TO_DEVICE,
+    ///         GFP_KERNEL,
+    ///     ), GFP_KERNEL)?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    pub fn new(
+        dev: &Device<Bound>,
+        pages: P,
+        dir: dma::DataDirection,
+        flags: alloc::Flags,
+    ) -> impl PinInit<Self, Error> + use<'_, P> {

rust/kernel/scatterlist.rs line 388

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+        try_pin_init!(Self {
+            inner <- Owned::new(dev, pages, dir, flags)?
+        })
+    }
+}
+
+impl<P> Deref for SGTable<Owned<P>> {
+    type Target = SGTable;
+
+    fn deref(&self) -> &Self::Target {

Also #[inline].

Quoted 48 lines
rust/kernel/scatterlist.rs new file +45 -0
+        // SAFETY: `self.inner.sgt.as_raw()` is a valid pointer to a `struct sg_table` for the
+        // entire lifetime of `self`.
+        unsafe { SGTable::as_ref(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 &'a SGTable {
+    type Item = &'a SGEntry;
+    type IntoIter = SGTableIter<'a>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.as_iter()
+    }
+}
+
+/// An [`Iterator`] over the [`SGEntry`] items of an [`SGTable`].
+pub struct SGTableIter<'a> {
+    pos: Option<&'a SGEntry>,
+}
+
+impl<'a> Iterator for SGTableIter<'a> {
+    type Item = &'a SGEntry;
+
+    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::as_ref(next) }
+        });
+
+        Some(entry)
+    }
+}
Signature · 1 line
2.50.1
author maintainer
#17 lore raw

Re: [PATCH 2/4] rust: scatterlist: Add type-state abstraction for sg_table

Quoted 12 lines · Alice Ryhl

rust/kernel/scatterlist.rs line 51

Quoted 9 lines · Danilo Krummrich
rust/kernel/scatterlist.rs new file +9 -0
+/// 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>);

Send/Sync?

I think SGEntry doesn't need it, but both would be valid.

For the other types, I simply forgot to impl Sync.

Quoted 7 lines

rust/kernel/scatterlist.rs line 74

Quoted 4 lines
rust/kernel/scatterlist.rs new file +4 -0
+    /// Returns the DMA address of this SG entry.
+    ///
+    /// This is the address that the device should use to access the memory segment.
+    pub fn dma_address(&self) -> bindings::dma_addr_t {

We might want a typedef on the Rust side for dma_addr_t, like we already have for the phys_addr_t/resource_size_t.

Yes, the idea was to add that with a subsequent patch, dma.rs already leaks bindings::dma_addr_t and I didn't want to mix up this series with this cleanup.

Quoted 8 lines

rust/kernel/scatterlist.rs line 80

Quoted 6 lines
rust/kernel/scatterlist.rs new file +6 -0
+        // 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.
+    pub fn dma_len(&self) -> u32 {

Is u32 really the right length type?

The C type uses unsigned int unfortunately, and SG entries larger than u32 probably don't make sense.

Formally, bus addresses and hence this size, can exceed size_t. However, it obviously makes no sense for this to happen, so size_t would be a reasonable choice. ressource_size_t would be resonable too.

Quoted 6 lines

rust/kernel/scatterlist.rs line 147

Quoted 3 lines
rust/kernel/scatterlist.rs new file +3 -0
+/// # Invariants
+///
+/// `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`].

I think we probably want an invariant for why it's safe to call dma_unmap_sgtable in Drop.

I assume you're suggesting that the invariant should say that the SG table is always mapped? And that we should add a safety requirement to DmaMapSgt::new() that the caller must guarantee that the SG table is never unmapped other than by dropping DmaMapSgt?

If so, that sounds reasonable.

Quoted 5 lines
Quoted 5 lines
rust/kernel/scatterlist.rs new file +5 -0
+struct DmaMapSgt {
+    sgt: NonNull<bindings::sg_table>,
+    dev: ARef<Device>,
+    dir: dma::DataDirection,
+}

<snip>

Quoted 18 lines
Quoted 18 lines
rust/kernel/scatterlist.rs new file +18 -0
+impl RawSGTable {
+    fn new(
+        mut pages: KVec<*mut bindings::page>,
+        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.
Quoted 8 lines

rust/kernel/scatterlist.rs line 229

Quoted 5 lines
rust/kernel/scatterlist.rs new file +5 -0
+                error::to_result(unsafe {
+                    bindings::sg_alloc_table_from_pages_segment(
+                        slot,
+                        pages.as_mut_ptr(),
+                        pages.len().try_into()?,

The pages vector is dropped immediately after this call to sg_alloc_table_from_pages_segment. Is that ok?

Yes, it's only needed during sg_alloc_table_from_pages_segment().

Quoted 2 lines

If it's ok, then I would change pages to &[*mut page] so that the caller can manage the allocation of the array.

We can immediately drop it after sg_alloc_table_from_pages_segmen(), so why do we want the caller to take care of the lifetime?

Quoted 6 lines

rust/kernel/scatterlist.rs line 279

Quoted 3 lines
rust/kernel/scatterlist.rs new file +3 -0
+impl<P> Owned<P>
+where
+    for<'a> P: page::AsPageIter<Iter<'a> = VmallocPageIter<'a>> + 'static,

If you specifically require the iterator type to be VmallocPageIter, then I would hard-code that in the trait instead of specifying it here.

I do not follow, hard-code in which trait?

Quoted 1 line

But I think you just want P: AsPageIter.

Yeah, I thought for now it's probably good enough to require VmallocPageIter and revisit once we get more implementors of AsPageIter, but I think we can also do it right away.

I think we'd need a trait PageIterator, which implements page_count(), since we technically can't rely on Iterator::size_hint(). Though, in this case I think we can also just make AsPageIter::Iter: ExactSizeIterator?

Quoted 10 lines

rust/kernel/scatterlist.rs line 286

Quoted 7 lines
rust/kernel/scatterlist.rs new file +7 -0
+{
+    fn new(
+        dev: &Device<Bound>,
+        mut pages: P,
+        dir: dma::DataDirection,
+        flags: alloc::Flags,
+    ) -> Result<impl PinInit<Self, Error> + use<'_, P>> {

We would probably want to move the logic into the initializer so that we don't have the double Result here.

That'd be nice, but I think it's not possible.

We can't borrow from pages in the initializer closure while at the same time store pages with another initializer, can we?

Either way, it's not that big a deal I think, since this constructor is not exposed to the outside world. Which is also why it didn't bother me too much.

Quoted 42 lines
Quoted 9 lines
rust/kernel/scatterlist.rs new file +9 -0
+        let page_iter = pages.page_iter();
+        let size = page_iter.size();
+
+        let mut page_vec: KVec<*mut bindings::page> =
+            KVec::with_capacity(page_iter.page_count(), flags)?;
+
+        for page in page_iter {
+            page_vec.push(page.as_ptr(), flags)?;
+        }

rust/kernel/scatterlist.rs line 305

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+
+        // `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 {
+                size.min(u32::MAX as usize) as u32

u32::try_from(size).unwrap_or(u32::MAX)

Quoted 20 lines
rust/kernel/scatterlist.rs new file +20 -0
+            }
+        };
+
+        Ok(try_pin_init!(&this in Self {
+            sgt <- RawSGTable::new(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`.
+                Devres::new(dev, unsafe { DmaMapSgt::new(sgt, dev, dir) })
+            },
+            _pages: pages,
+        }))
+    }
+}
author maintainer
#18 lore raw

Re: [PATCH 2/4] rust: scatterlist: Add type-state abstraction for sg_table

Quoted 13 lines · Danilo Krummrich
Quoted 7 lines · Alice Ryhl

rust/kernel/scatterlist.rs line 279

Quoted 3 lines · Danilo Krummrich
rust/kernel/scatterlist.rs new file +3 -0
+impl<P> Owned<P>
+where
+    for<'a> P: page::AsPageIter<Iter<'a> = VmallocPageIter<'a>> + 'static,

If you specifically require the iterator type to be VmallocPageIter, then I would hard-code that in the trait instead of specifying it here.

I do not follow, hard-code in which trait?

Quoted 1 line

But I think you just want P: AsPageIter.

Quoted 7 lines

Yeah, I thought for now it's probably good enough to require VmallocPageIter and revisit once we get more implementors of AsPageIter, but I think we can also do it right away.

I think we'd need a trait PageIterator, which implements page_count(), since we technically can't rely on Iterator::size_hint(). Though, in this case I think we can also just make AsPageIter::Iter: ExactSizeIterator?

Forgot to mention this [1] as for why we expect VmallocPageIter (at least for now).

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

author maintainer
#19 lore raw

Re: [PATCH 2/4] rust: scatterlist: Add type-state abstraction for sg_table

Quoted 18 lines · Danilo Krummrich
Quoted 17 lines · Danilo Krummrich
Quoted 7 lines · Alice Ryhl

rust/kernel/scatterlist.rs line 279

Quoted 3 lines · Danilo Krummrich
rust/kernel/scatterlist.rs new file +3 -0
+impl<P> Owned<P>
+where
+    for<'a> P: page::AsPageIter<Iter<'a> = VmallocPageIter<'a>> + 'static,

If you specifically require the iterator type to be VmallocPageIter, then I would hard-code that in the trait instead of specifying it here.

I do not follow, hard-code in which trait?

Quoted 1 line

But I think you just want P: AsPageIter.

Yeah, I thought for now it's probably good enough to require VmallocPageIter and revisit once we get more implementors of AsPageIter, but I think we can also do it right away.

Quoted 6 lines
Quoted 3 lines

I think we'd need a trait PageIterator, which implements page_count(), since we technically can't rely on Iterator::size_hint(). Though, in this case I think we can also just make AsPageIter::Iter: ExactSizeIterator?

Forgot to mention this [1] as for why we expect VmallocPageIter (at least for now).

Actually, let me expand on this a bit:

What I mean is that for some generic page::AsPageIter we don't know anything about the semantics of the order of the pages; this is implementation specific to the actual Iterator implementation, such as VmallocPageIter.

(For instance, VmallocPageIter iterates pages in the order as they are virtually contiguous mapped by Vmalloc. VmallocPageIter documents this in the context of a guarantees section.)

Thus, before allowing any AsPageIter::Iter in SGTable::new(), I'd like to see actual implementations and subsequently figure out if it makes sense to add additional (empty) traits providing such kind of guarantees.

Quoted 1 line

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

reviewer
#20 lore raw

Re: [PATCH 2/4] rust: scatterlist: Add type-state abstraction for sg_table

In reply to Danilo Krummrich
Quoted 14 lines · Danilo Krummrich
Quoted 12 lines · Alice Ryhl

rust/kernel/scatterlist.rs line 51

Quoted 9 lines · Danilo Krummrich
rust/kernel/scatterlist.rs new file +9 -0
+/// 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>);

Send/Sync?

Quoted 3 lines

I think SGEntry doesn't need it, but both would be valid.

For the other types, I simply forgot to impl Sync.

I would add them when it's valid to do so.

Quoted 7 lines
Quoted 7 lines
Quoted 6 lines
rust/kernel/scatterlist.rs new file +6 -0
+        // 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.
+    pub fn dma_len(&self) -> u32 {
Quoted 8 lines
Quoted 1 line

Is u32 really the right length type?

The C type uses unsigned int unfortunately, and SG entries larger than u32 probably don't make sense.

Formally, bus addresses and hence this size, can exceed size_t. However, it obviously makes no sense for this to happen, so size_t would be a reasonable choice. ressource_size_t would be resonable too.

resource_size_t is what makes sense in my mind.

Quoted 7 lines
Quoted 6 lines

rust/kernel/scatterlist.rs line 147

Quoted 3 lines
rust/kernel/scatterlist.rs new file +3 -0
+/// # Invariants
+///
+/// `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`].

I think we probably want an invariant for why it's safe to call dma_unmap_sgtable in Drop.

Quoted 6 lines

I assume you're suggesting that the invariant should say that the SG table is always mapped? And that we should add a safety requirement to DmaMapSgt::new() that the caller must guarantee that the SG table is never unmapped other than by dropping DmaMapSgt?

If so, that sounds reasonable.

Something like that, yeah.

Quoted 35 lines
Quoted 5 lines
Quoted 5 lines
rust/kernel/scatterlist.rs new file +5 -0
+struct DmaMapSgt {
+    sgt: NonNull<bindings::sg_table>,
+    dev: ARef<Device>,
+    dir: dma::DataDirection,
+}

<snip>

Quoted 18 lines
Quoted 18 lines
rust/kernel/scatterlist.rs new file +18 -0
+impl RawSGTable {
+    fn new(
+        mut pages: KVec<*mut bindings::page>,
+        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.
Quoted 8 lines

rust/kernel/scatterlist.rs line 229

Quoted 5 lines
rust/kernel/scatterlist.rs new file +5 -0
+                error::to_result(unsafe {
+                    bindings::sg_alloc_table_from_pages_segment(
+                        slot,
+                        pages.as_mut_ptr(),
+                        pages.len().try_into()?,

The pages vector is dropped immediately after this call to sg_alloc_table_from_pages_segment. Is that ok?

Quoted 7 lines

Yes, it's only needed during sg_alloc_table_from_pages_segment().

Quoted 2 lines

If it's ok, then I would change pages to &[*mut page] so that the caller can manage the allocation of the array.

We can immediately drop it after sg_alloc_table_from_pages_segmen(), so why do we want the caller to take care of the lifetime?

I think the API is easier to understand that way. With a slice, it's clear that you only expect it to be alive for the duration of the method. Whereas with a vector, it looks like you're going to keep the allocation alive long-term, but that's not the case.

Quoted 8 lines
Quoted 6 lines

rust/kernel/scatterlist.rs line 279

Quoted 3 lines
rust/kernel/scatterlist.rs new file +3 -0
+impl<P> Owned<P>
+where
+    for<'a> P: page::AsPageIter<Iter<'a> = VmallocPageIter<'a>> + 'static,

If you specifically require the iterator type to be VmallocPageIter, then I would hard-code that in the trait instead of specifying it here.

I do not follow, hard-code in which trait?

By hard-code, I meant that you refer to VmallocPageIter directly in trait AsPageIter. But I don't think that's the correct solution.

Quoted 9 lines
Quoted 1 line

But I think you just want P: AsPageIter.

Yeah, I thought for now it's probably good enough to require VmallocPageIter and revisit once we get more implementors of AsPageIter, but I think we can also do it right away.

I think we'd need a trait PageIterator, which implements page_count(), since we technically can't rely on Iterator::size_hint(). Though, in this case I think we can also just make AsPageIter::Iter: ExactSizeIterator?

I mean, ExactSizeIterator is not an unsafe trait, so it's allowed to lie about the length. But it doesn't look like getting it wrong has any problematic consequences here. At most we allocate too much in the vector, or we have to reallocate it.

Quoted 11 lines
Quoted 10 lines

rust/kernel/scatterlist.rs line 286

Quoted 7 lines
rust/kernel/scatterlist.rs new file +7 -0
+{
+    fn new(
+        dev: &Device<Bound>,
+        mut pages: P,
+        dir: dma::DataDirection,
+        flags: alloc::Flags,
+    ) -> Result<impl PinInit<Self, Error> + use<'_, P>> {

We would probably want to move the logic into the initializer so that we don't have the double Result here.

Quoted 7 lines

That'd be nice, but I think it's not possible.

We can't borrow from pages in the initializer closure while at the same time store pages with another initializer, can we?

Either way, it's not that big a deal I think, since this constructor is not exposed to the outside world. Which is also why it didn't bother me too much.

Ok. Shrug.

Alice

author maintainer
#21 lore raw

Re: [PATCH 2/4] rust: scatterlist: Add type-state abstraction for sg_table

Quoted 16 lines · Alice Ryhl
Quoted 15 lines · Danilo Krummrich
Quoted 11 lines · Alice Ryhl

rust/kernel/scatterlist.rs line 286

Quoted 7 lines · Danilo Krummrich
rust/kernel/scatterlist.rs new file +7 -0
+{
+    fn new(
+        dev: &Device<Bound>,
+        mut pages: P,
+        dir: dma::DataDirection,
+        flags: alloc::Flags,
+    ) -> Result<impl PinInit<Self, Error> + use<'_, P>> {

We would probably want to move the logic into the initializer so that we don't have the double Result here.

That'd be nice, but I think it's not possible.

Quoted 7 lines
Quoted 5 lines

We can't borrow from pages in the initializer closure while at the same time store pages with another initializer, can we?

Either way, it's not that big a deal I think, since this constructor is not exposed to the outside world. Which is also why it didn't bother me too much.

Ok. Shrug.

I mean, don't get me wrong, if you see a way to avoid the double Result, I'm happy to change it.

(What I meant is, given the above, I thought it's not possible. But at the same time I did not spend too much brain cycles, since the constructor is private anyways.)

#22 lore raw

Re: [PATCH 2/4] rust: scatterlist: Add type-state abstraction for sg_table

In reply to Danilo Krummrich

Hi Danilo,

I am OK with this patch. I see that Alice has a few comments already so on my side I will just leave a few nits, but in general this looks good.

Quoted 196 lines · Danilo Krummrich

Add 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 | 433 +++++++++++++++++++++++++++++++++++++
4 files changed, 459 insertions(+)

create mode 100644 rust/helpers/scatterlist.c
create mode 100644 rust/kernel/scatterlist.rs

rust/helpers/helpers.c +1 -0
index 7cf7fe95e41d..e94542bf6ea7 100644
@@ -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
new file mode 100644
index 000000000000..80c956ee09ab
@@ -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
index ed53169e795c..55acbc893736 100644
@@ -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 +100 -0
new file mode 100644
index 000000000000..4caaf8cfbf83
@@ -0,0 +1,433 @@
+// 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, 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>);
+
+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`.
+    unsafe fn as_ref<'a>(ptr: *mut bindings::scatterlist) -> &'a Self {
+        // 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 *`.
+    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.
+    pub fn dma_address(&self) -> bindings::dma_addr_t {
+        // 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.
+    pub fn dma_len(&self) -> u32 {
+        // SAFETY: `self.as_raw()` is a valid pointer to a `struct scatterlist`.
+        unsafe { bindings::sg_dma_len(self.as_raw()) }
+    }
+}
+
+/// The borrowed type state of an [`SGTable`], representing a borrowed or externally managed table.
+#[repr(transparent)]
+pub struct Borrowed(Opaque<bindings::sg_table>);
+
+// SAFETY: An instance of `Borrowed` can be send to any task.
+unsafe impl Send 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.
+///

rust/kernel/scatterlist.rs line 110

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+///  - [`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> {

Am I the only one that think we should have an actual trait here instead of using private::Sealed directly?

Quoted 14 lines
rust/kernel/scatterlist.rs new file +14 -0
+    #[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`.
+    pub unsafe fn as_ref<'a>(ptr: *mut bindings::sg_table) -> &'a Self {

rust/kernel/scatterlist.rs line 134

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+        // 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() }
+    }
+
+    fn as_raw(&self) -> *mut bindings::sg_table {
+        self.inner.0.get()
+    }
+
+    fn as_iter(&self) -> SGTableIter<'_> {

Perhaps just "iter()” ?

Quoted 4 lines
rust/kernel/scatterlist.rs new file +4 -0
+        // 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`.

rust/kernel/scatterlist.rs line 148

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+        let pos = Some(unsafe { SGEntry::as_ref(ptr) });
+
+        SGTableIter { pos }
+    }
+}
+
+/// # Invariants
+///
+/// `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`].
+struct DmaMapSgt {

This is private, but some extra docs here wouldn’t hurt?

Quoted 128 lines
rust/kernel/scatterlist.rs new file +128 -0
+    sgt: NonNull<bindings::sg_table>,
+    dev: ARef<Device>,
+    dir: dma::DataDirection,
+}
+
+// SAFETY: An instance of `DmaMapSgt` can be send to any task.
+unsafe impl Send for DmaMapSgt {}
+
+impl DmaMapSgt {
+    /// # Safety
+    ///
+    /// `sgt` must be a valid pointer to a `struct sg_table` for the entire lifetime of the
+    /// returned [`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.as_raw(), 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 {
+    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.as_raw(), 0)
+        };
+    }
+}
+
+#[repr(transparent)]
+#[pin_data(PinnedDrop)]
+struct RawSGTable {
+    #[pin]
+    sgt: Opaque<bindings::sg_table>,
+}
+
+impl RawSGTable {
+    fn new(
+        mut pages: KVec<*mut bindings::page>,
+        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(),
+                    )
+                })
+            }),
+        })
+    }
+
+    fn as_raw(&self) -> *mut bindings::sg_table {
+        self.sgt.get()
+    }
+}
+
+#[pinned_drop]
+impl PinnedDrop for RawSGTable {
+    fn drop(self: Pin<&mut Self>) {
+        // SAFETY: `sgt` is a valid and initialized `struct sg_table`.
+        unsafe { bindings::sg_free_table(self.sgt.get()) };
+    }
+}
+
+/// 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: An instance of `Owned` can be send to any task if `P` can be send to any task.
+unsafe impl<P: Send> Send for Owned<P> {}
+

rust/kernel/scatterlist.rs line 286

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -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,
+        flags: alloc::Flags,
+    ) -> Result<impl PinInit<Self, Error> + use<'_, P>> {

I confess I have no idea what “use<‘_, P>” is.

Quoted 151 lines
rust/kernel/scatterlist.rs new file +147 -0
+        let page_iter = pages.page_iter();
+        let size = page_iter.size();
+
+        let mut page_vec: KVec<*mut bindings::page> =
+            KVec::with_capacity(page_iter.page_count(), flags)?;
+
+        for page in 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 {
+                size.min(u32::MAX as usize) as u32
+            }
+        };
+
+        Ok(try_pin_init!(&this in Self {
+            sgt <- RawSGTable::new(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`.
+                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::TO_DEVICE,
+    ///         GFP_KERNEL,
+    ///     ), GFP_KERNEL)?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    pub fn new(
+        dev: &Device<Bound>,
+        pages: P,
+        dir: dma::DataDirection,
+        flags: alloc::Flags,
+    ) -> impl PinInit<Self, Error> + use<'_, P> {
+        try_pin_init!(Self {
+            inner <- Owned::new(dev, pages, dir, flags)?
+        })
+    }
+}
+
+impl<P> Deref for SGTable<Owned<P>> {
+    type Target = SGTable;
+
+    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::as_ref(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 &'a SGTable {
+    type Item = &'a SGEntry;
+    type IntoIter = SGTableIter<'a>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.as_iter()
+    }
+}
+
+/// An [`Iterator`] over the [`SGEntry`] items of an [`SGTable`].
+pub struct SGTableIter<'a> {
+    pos: Option<&'a SGEntry>,
+}
+
+impl<'a> Iterator for SGTableIter<'a> {
+    type Item = &'a SGEntry;
+
+    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::as_ref(next) }
+        });
+
+        Some(entry)
+    }
+}
Signature · 1 line
2.50.1

— Daniel

author maintainer
#23 lore raw

Re: [PATCH 2/4] rust: scatterlist: Add type-state abstraction for sg_table

Quoted 13 lines · Daniel Almeida
Quoted 13 lines
rust/kernel/scatterlist.rs new file +13 -0
+/// 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.
Quoted 8 lines

rust/kernel/scatterlist.rs line 110

Quoted 5 lines
rust/kernel/scatterlist.rs new file +5 -0
+///
+/// All [`SGTable`] variants can be iterated over the individual [`SGEntry`]s.
+#[repr(transparent)]
+#[pin_data]
+pub struct SGTable<T: private::Sealed = Borrowed> {

Am I the only one that think we should have an actual trait here instead of using private::Sealed directly?

I don't know. :)

I think this case perfectly fits the Sealed pattern. There isn't any semantics behind that, other than "we want that only the sealed ones work".

Quoted 19 lines
Quoted 19 lines
rust/kernel/scatterlist.rs new file +18 -0
+    #[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`.
+    pub unsafe fn as_ref<'a>(ptr: *mut bindings::sg_table) -> &'a Self {
+        // 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() }
+    }
Quoted 8 lines

rust/kernel/scatterlist.rs line 134

Quoted 6 lines
rust/kernel/scatterlist.rs new file +6 -0
+
+    fn as_raw(&self) -> *mut bindings::sg_table {
+        self.inner.0.get()
+    }
+
+    fn as_iter(&self) -> SGTableIter<'_> {

Perhaps just "iter()” ?

No strong opinition, I'm fine with either.

Quoted 17 lines
Quoted 5 lines
rust/kernel/scatterlist.rs new file +4 -0
+        // 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`.

rust/kernel/scatterlist.rs line 148

Quoted 10 lines
rust/kernel/scatterlist.rs new file +10 -0
+        let pos = Some(unsafe { SGEntry::as_ref(ptr) });
+
+        SGTableIter { pos }
+    }
+}
+
+/// # Invariants
+///
+/// `sgt` is a valid pointer to a `struct sg_table` for the entire lifetime of an [`DmaMapSgt`].
+struct DmaMapSgt {

This is private, but some extra docs here wouldn’t hurt?

The type just represents the DMA mapping state of the SGT, i.e. exists corresponds to is mapped, is dropped corresponds to is unmapped.

I can probably add a few lines if it helps.

Quoted 4 lines
Quoted 4 lines
rust/kernel/scatterlist.rs new file +4 -0
+impl<P> Owned<P>
+where
+    for<'a> P: page::AsPageIter<Iter<'a> = VmallocPageIter<'a>> + 'static,
+{
Quoted 8 lines

rust/kernel/scatterlist.rs line 286

Quoted 6 lines
rust/kernel/scatterlist.rs new file +6 -0
+    fn new(
+        dev: &Device<Bound>,
+        mut pages: P,
+        dir: dma::DataDirection,
+        flags: alloc::Flags,
+    ) -> Result<impl PinInit<Self, Error> + use<'_, P>> {

I confess I have no idea what “use<‘_, P>” is.

It's a feature called #![feature(precise_capturing)], which, unfortunately, does not exist in 1.78, so I removed this syntax in v2. Luckly, we don't actually need it in this case.

author maintainer
#24 lore raw

PATCH 3/4 samples: rust: dma: add sample code for SGTable

In reply to Danilo Krummrich

Add 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
index c5e7cce68654..cc82327db0c2 100644
@@ -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::TO_DEVICE, 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
author maintainer
#25 lore raw

PATCH 4/4 MAINTAINERS: rust: dma: add scatterlist files

In reply to Danilo Krummrich

Rename 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
index fe168477caa4..65f676b2c304 100644
@@ -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