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/20250820145434.94745-1-dakr@kernel.org/
[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/20250718103359.1026240-1-abdiel.janulgue@gmail.com/

Changes in v2:
  - Switch to an enum impl for DmaDirection utilizing compile time boundary
    checks.
  - Add missing Send/ Sync impls.
  - Rename as_ref() to from_raw().
  - Add a bunch of inline annotations.
  - Add a patch to introduce a typedef for dma_addr_t.
  - Let dma_len() return ResourceSize.
  - Add addional invariant to DmaMapSgt.
  - In RawSGTable::new(), pass pages as mutable slice reference.
  - Avoid casts when deriving max_segment in Owned::new().

Danilo Krummrich (5):
  rust: dma: implement DataDirection
  rust: dma: add type alias for bindings::dma_addr_t
  rust: scatterlist: Add type-state abstraction for sg_table
  samples: rust: dma: add sample code for SGTable
  MAINTAINERS: rust: dma: add scatterlist files

 MAINTAINERS                     |   4 +-
 drivers/gpu/nova-core/falcon.rs |   4 +-
 rust/bindings/bindings_helper.h |   1 +
 rust/helpers/helpers.c          |   1 +
 rust/helpers/scatterlist.c      |  24 ++
 rust/kernel/dma.rs              |  86 +++++-
 rust/kernel/lib.rs              |   1 +
 rust/kernel/scatterlist.rs      | 475 ++++++++++++++++++++++++++++++++
 samples/rust/rust_dma.rs        |  35 ++-
 9 files changed, 615 insertions(+), 16 deletions(-)
 create mode 100644 rust/helpers/scatterlist.c
 create mode 100644 rust/kernel/scatterlist.rs


base-commit: 27941214d368f3c17ed26a72662fc453bcc81b9d
-- 
2.50.1

On Thu Aug 21, 2025 at 1:52 AM JST, Danilo Krummrich wrote:
> 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/20250820145434.94745-1-dakr@kernel.org/
> [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/20250718103359.1026240-1-abdiel.janulgue@gmail.com/

I am going to do a full review of this revision over the weekend, but I
have already successfully used it in nova-core to boot the GSP. Thus,

Tested-by: Alexandre Courbot <acourbot@nvidia.com>

On Wed, Aug 20, 2025 at 06:52:54PM +0200, Danilo Krummrich wrote:
> Changes in v2:
>   - Switch to an enum impl for DmaDirection utilizing compile time boundary
>     checks.
>   - Add missing Send/ Sync impls.
>   - Rename as_ref() to from_raw().

Thanks, but it's still as_ref() in the cover letter.

Alice