Message-ID: <20250626203247.816273-1-abdiel.janulgue@gmail.com>
Date: Thu, 26 Jun 2025 23:30:06 +0300
From: Abdiel Janulgue <abdiel.janulgue@...il.com>
To: acourbot@...dia.com,
	jgg@...pe.ca,
	lyude@...hat.com,
	dakr@...nel.org
Cc: Miguel Ojeda <ojeda@...nel.org>,
	Alex Gaynor <alex.gaynor@...il.com>,
	Boqun Feng <boqun.feng@...il.com>,
	Gary Guo <gary@...yguo.net>,
	Björn Roy Baron <bjorn3_gh@...tonmail.com>,
	Benno Lossin <benno.lossin@...ton.me>,
	Andreas Hindborg <a.hindborg@...nel.org>,
	Alice Ryhl <aliceryhl@...gle.com>,
	Trevor Gross <tmgross@...ch.edu>,
	Valentin Obst <kernel@...entinobst.de>,
	linux-kernel@...r.kernel.org (open list),
	Marek Szyprowski <m.szyprowski@...sung.com>,
	Robin Murphy <robin.murphy@....com>,
	airlied@...hat.com,
	rust-for-linux@...r.kernel.org,
	iommu@...ts.linux.dev (open list:DMA MAPPING HELPERS),
	Petr Tesarik <petr@...arici.cz>,
	Andrew Morton <akpm@...ux-foundation.org>,
	Herbert Xu <herbert@...dor.apana.org.au>,
	Sui Jingfeng <sui.jingfeng@...ux.dev>,
	Randy Dunlap <rdunlap@...radead.org>,
	Michael Kelley <mhklinux@...look.com>,
	Abdiel Janulgue <abdiel.janulgue@...il.com>
Subject: [PATCH v2 0/2] rust: add initial scatterlist abstraction

Hi

Took some time to re-work this after the initial feedback but here is
v2 of the scatterlist abstraction.

Basically what this version accomplishes is attempt to enforce proper
use of the scatterlist api for device drivers in Rust. This comes down
to a couple of things:

(1) Ensure ownership of the backing pages is moved to the sg table.

This is done via the SGTablePages trait. By allowing users to implement
this trait, we allow users flexibility in how the list of pages are
stored and organised. During construction, the sg table takes ownership
of an object implementing the SGTablePages trait to build and allocate
the sg table.

(2) Prevent invalid use of the API such as retrieving the DMA address of
entries of an sg table which is not yet mapped for DMA. Another invalid
use is setting the page entries of an sg table which is already mapped
for DMA.

Safe use is enforced using Rust's newtype pattern which allows us to
ensure that only specific variants of `SGTable` objects are allowed to
safely return an iterator. For example a `DeviceSGTable` (a sg table that
is mapped for DMA operation) is the only object allowed to safely iterate
and retrieve the DMA address for sg entries. A `DeviceSGTable` object
likewise is returned only by the safe variant of the dma_map function.
Also, the set_pages interface is now hidden from users of the API and is
only internally called when building the table.

Lastly, a glue layer provides unsafe interfaces to help in writing
Rust abstractions for other kernel subsystems is provided (currently
targeting Lyude's gem shmem work).

I'd like to acknowledge Alexandre Courbot for providing the feedback and
initial idea for the SGTablePages trait approach.

Changes since v2:
- Drop typestate pattern. Introduce SGTablePages trait to enforce ownership
  of the pages to SGTable.

Link to v1: https://lore.kernel.org/lkml/20250528221525.1705117-1-abdiel.janulgue@gmail.com/

Abdiel Janulgue (2):
  rust: add initial scatterlist bindings
  samples: rust: add sample code for scatterlist bindings

 rust/bindings/bindings_helper.h |   1 +
 rust/helpers/helpers.c          |   1 +
 rust/helpers/scatterlist.c      |  30 +++
 rust/kernel/dma.rs              |  18 ++
 rust/kernel/lib.rs              |   1 +
 rust/kernel/scatterlist.rs      | 390 ++++++++++++++++++++++++++++++++
 samples/rust/rust_dma.rs        |  29 ++-
 7 files changed, 469 insertions(+), 1 deletion(-)
 create mode 100644 rust/helpers/scatterlist.c
 create mode 100644 rust/kernel/scatterlist.rs


base-commit: 0303584766b7bdb6564c7e8f13e0b59b6ef44984
-- 
2.43.0

Powered by blists - more mailing lists