From nobody Sun Feb 8 12:31:26 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8ABF6C77B7A for ; Sat, 10 Jun 2023 10:49:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234190AbjFJKta (ORCPT ); Sat, 10 Jun 2023 06:49:30 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48784 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229750AbjFJKt3 (ORCPT ); Sat, 10 Jun 2023 06:49:29 -0400 Received: from out0-208.mail.aliyun.com (out0-208.mail.aliyun.com [140.205.0.208]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 61A2E35BC; Sat, 10 Jun 2023 03:49:26 -0700 (PDT) X-Alimail-AntiSpam: AC=PASS;BC=-1|-1;BR=01201311R691e4;CH=green;DM=||false|;DS=||;FP=0|-1|-1|-1|0|-1|-1|-1;HT=ay29a033018047203;MF=changxian.cqs@antgroup.com;NM=1;PH=DS;RN=15;SR=0;TI=SMTPD_---.TQGLBZH_1686394162; Received: from localhost(mailfrom:changxian.cqs@antgroup.com fp:SMTPD_---.TQGLBZH_1686394162) by smtp.aliyun-inc.com; Sat, 10 Jun 2023 18:49:23 +0800 From: "Qingsong Chen" To: linux-kernel@vger.kernel.org Cc: "=?UTF-8?B?55Sw5rSq5Lqu?=" , "Qingsong Chen" , "Miguel Ojeda" , "Alex Gaynor" , "Wedson Almeida Filho" , "Boqun Feng" , "Gary Guo" , "=?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?=" , "Benno Lossin" , "Martin Rodriguez Reboredo" , "Alice Ryhl" , "Asahi Lina" , "Niklas Mohrin" , Subject: [PATCH v3 1/3] rust: kernel: add ScatterList abstraction Date: Sat, 10 Jun 2023 18:49:07 +0800 Message-Id: <20230610104909.3202958-2-changxian.cqs@antgroup.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230610104909.3202958-1-changxian.cqs@antgroup.com> References: <20230610104909.3202958-1-changxian.cqs@antgroup.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" Add a wrapper for `struct scatterlist`. Signed-off-by: Qingsong Chen Reviewed-by: Martin Rodriguez Reboredo --- rust/bindings/bindings_helper.h | 1 + rust/helpers.c | 14 ++ rust/kernel/lib.rs | 1 + rust/kernel/scatterlist.rs | 293 ++++++++++++++++++++++++++++++++ 4 files changed, 309 insertions(+) create mode 100644 rust/kernel/scatterlist.rs diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helpe= r.h index 50e7a76d5455..9cfa1ef92a04 100644 --- a/rust/bindings/bindings_helper.h +++ b/rust/bindings/bindings_helper.h @@ -10,6 +10,7 @@ #include #include #include +#include =20 /* `bindgen` gets confused at certain things. */ const gfp_t BINDINGS_GFP_KERNEL =3D GFP_KERNEL; diff --git a/rust/helpers.c b/rust/helpers.c index 81e80261d597..4eb48f6c926e 100644 --- a/rust/helpers.c +++ b/rust/helpers.c @@ -26,6 +26,7 @@ #include #include #include +#include =20 __noreturn void rust_helper_BUG(void) { @@ -128,6 +129,19 @@ void rust_helper_put_task_struct(struct task_struct *t) } EXPORT_SYMBOL_GPL(rust_helper_put_task_struct); =20 +void rust_helper_sg_set_buf(struct scatterlist *sgl, const void *buf, + unsigned int buflen) +{ + sg_set_buf(sgl, buf, buflen); +} +EXPORT_SYMBOL_GPL(rust_helper_sg_set_buf); + +void *rust_helper_sg_virt(struct scatterlist *sgl) +{ + return sg_virt(sgl); +} +EXPORT_SYMBOL_GPL(rust_helper_sg_virt); + /* * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` ty= pe * as the Rust `usize` type, so we can use it in contexts where Rust diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index 676995d4e460..d8dbcde4ad5c 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -40,6 +40,7 @@ pub mod init; pub mod ioctl; pub mod prelude; pub mod print; +pub mod scatterlist; mod static_assert; #[doc(hidden)] pub mod std_vendor; diff --git a/rust/kernel/scatterlist.rs b/rust/kernel/scatterlist.rs new file mode 100644 index 000000000000..7fb8f3326ff3 --- /dev/null +++ b/rust/kernel/scatterlist.rs @@ -0,0 +1,293 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Scatterlist. +//! +//! C header: [`include/linux/scatterlist.h`](../../../../include/linux/sc= atterlist.h) + +use crate::prelude::*; +use crate::types::Opaque; +use core::marker::PhantomData; +use core::ptr::{addr_of, NonNull}; + +/// Wrap the kernel's `struct scatterlist`. +/// +/// According to the design of kernel's `struct sg_table`, the `page_link` +/// field of one `scatterlist` may contain a pointer to another. That is, +/// there could exist external pointers to it, making it necessary to pin +/// this struct. +/// +/// # Invariants +/// +/// All instances should be valid, either created by the `new` constructor +/// (see [`pin_init`]), or transmuted from raw pointers (which could be us= ed +/// to reference a valid entry of `sg_table`). +/// +/// # Examples +/// +/// The following are some use cases of [`ScatterList`]. +/// +/// ```rust +/// use core::pin::pin; +/// # use kernel::error::Result; +/// # use kernel::scatterlist::ScatterList; +/// +/// // Prepare memory buffers. +/// let buf0: Pin<&mut [u8]> =3D pin!([0u8; 512]); +/// let buf1: Pin<&mut [u8]> =3D pin!([1u8; 512]); +/// +/// // Allocate an instance on stack. +/// kernel::stack_pin_init!(let foo =3D ScatterList::new(&buf0)); +/// let mut foo: Pin<&mut ScatterList<'_>> =3D foo; +/// assert_eq!(foo.length(), 512); +/// +/// // Allocate an instance by Box::pin_init. +/// let bar: Pin>> =3D Box::pin_init(ScatterList::new(= &buf1))?; +/// assert_eq!(bar.length(), 512); +/// +/// // Assert other attributes of an instance. +/// assert_eq!(foo.is_dma_bus_address(), false); +/// assert_eq!(foo.is_chain(), false); +/// assert_eq!(foo.is_last(), true); +/// assert_eq!(foo.count(), 1); +/// +/// // Get an immutable reference to memory buffer. +/// assert_eq!(foo.get_buf(), [0u8; 512]); +/// +/// // Reset the memory buffer. +/// foo.set_buf(&buf1); +/// assert_eq!(foo.get_buf(), [1u8; 512]); +/// +/// // Get a mutable reference to memory buffer. +/// foo.get_mut_buf().fill(2); +/// assert_eq!(foo.get_buf(), [2u8; 512]); +/// ``` +#[pin_data] +pub struct ScatterList<'a> { + #[pin] + opaque: Opaque, + _p: PhantomData<&'a mut bindings::scatterlist>, +} + +impl<'a> ScatterList<'a> { + /// Construct a new initializer. + pub fn new(buf: &'a Pin<&mut [u8]>) -> impl PinInit> { + // SAFETY: `slot` is valid while the closure is called, the memory + // buffer is pinned and valid. + unsafe { + init::pin_init_from_closure(move |slot: *mut Self| { + // `slot` contains uninit memory, avoid creating a referen= ce. + let opaque =3D addr_of!((*slot).opaque); + let sgl =3D Opaque::raw_get(opaque); + + bindings::sg_set_buf(sgl, buf.as_ptr() as _, buf.len() as = _); + (*sgl).page_link |=3D bindings::SG_END as u64; + (*sgl).page_link &=3D !(bindings::SG_CHAIN as u64); + Ok(()) + }) + } + } + + /// Obtain a pinned reference to an immutable scatterlist from a raw p= ointer. + /// + /// # Safety + /// + /// The `ptr` is null, or pointed to a valid `scatterlist`. + unsafe fn as_ref(ptr: *mut bindings::scatterlist) -> Option> { + // SAFETY: `sgl` is non-null and valid. + NonNull::new(ptr).map(|sgl| Pin::new(unsafe { &*(sgl.as_ptr() as *= const ScatterList<'_>) })) + } + + /// Obtain a pinned reference to a mutable scatterlist from a raw poin= ter. + /// + /// # Safety + /// + /// The `ptr` is null, or pointed to a valid `scatterlist`. + unsafe fn as_mut(ptr: *mut bindings::scatterlist) -> Option> { + // SAFETY: `sgl` is non-null and valid. + NonNull::new(ptr) + .map(|sgl| Pin::new(unsafe { &mut *(sgl.as_ptr() as *mut Scatt= erList<'_>) })) + } +} + +impl ScatterList<'_> { + /// Return the offset of memory buffer into the page. + pub fn offset(&self) -> usize { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { (*self.opaque.get()).offset as _ } + } + + /// Return the length of memory buffer. + pub fn length(&self) -> usize { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { (*self.opaque.get()).length as _ } + } + + /// Return the mapped DMA address. + /// + /// # Safety + /// + /// It is only valid after this scatterlist has been mapped to some bus + /// address and then called `set_dma` method to setup it. + pub fn dma_address(&self) -> usize { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { (*self.opaque.get()).dma_address as _ } + } + + /// Return the mapped DMA length. + /// + /// # Safety + /// + /// It is only valid after this scatterlist has been mapped to some bus + /// address and then called `set_dma` method to setup it. + pub fn dma_length(&self) -> usize { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + #[cfg(CONFIG_NEED_SG_DMA_LENGTH)] + unsafe { + (*self.opaque.get()).dma_length as _ + } + #[cfg(not(CONFIG_NEED_SG_DMA_LENGTH))] + unsafe { + (*self.opaque.get()).length as _ + } + } + + /// Setup the DMA address and length. + pub fn set_dma(&mut self, addr: usize, len: usize) { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + #[cfg(CONFIG_NEED_SG_DMA_LENGTH)] + unsafe { + (*self.opaque.get()).dma_address =3D addr as _; + (*self.opaque.get()).dma_length =3D len as _; + } + #[cfg(not(CONFIG_NEED_SG_DMA_LENGTH))] + unsafe { + (*self.opaque.get()).dma_address =3D addr as _; + (*self.opaque.get()).length =3D len as _; + } + self.dma_mark_bus_address(); + } + + /// Return `true` if it is mapped with a DMA address. + pub fn is_dma_bus_address(&self) -> bool { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + #[cfg(CONFIG_PCI_P2PDMA)] + unsafe { + ((*self.opaque.get()).dma_flags & bindings::SG_DMA_BUS_ADDRESS= ) !=3D 0 + } + #[cfg(not(CONFIG_PCI_P2PDMA))] + false + } + + /// Mark it as mapped to a DMA address. + pub fn dma_mark_bus_address(&mut self) { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + #[cfg(CONFIG_PCI_P2PDMA)] + unsafe { + (*self.opaque.get()).dma_flags |=3D bindings::SG_DMA_BUS_ADDRE= SS; + } + } + + /// Mark it as `not` mapped to a DMA address. + pub fn dma_unmark_bus_address(&mut self) { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + #[cfg(CONFIG_PCI_P2PDMA)] + unsafe { + (*self.opaque.get()).dma_flags &=3D !bindings::SG_DMA_BUS_ADDR= ESS; + } + } + + /// Return `true` if it is a chainable entry. + pub fn is_chain(&self) -> bool { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { + ((*self.opaque.get()).page_link + & (bindings::SG_PAGE_LINK_MASK as u64) + & (bindings::SG_CHAIN as u64)) + !=3D 0 + } + } + + /// Transfer this scatterlist as a chainable entry, linked to `sgl`. + pub fn chain_sgl(&mut self, sgl: Pin<&mut ScatterList<'_>>) { + let addr =3D sgl.opaque.get() as u64; + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { + (*self.opaque.get()).offset =3D 0; + (*self.opaque.get()).length =3D 0; + (*self.opaque.get()).page_link =3D addr | (bindings::SG_CHAIN = as u64); + } + self.unmark_end(); + } + + /// Return `true` if it is the last normal entry in scatterlist. + pub fn is_last(&self) -> bool { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { + ((*self.opaque.get()).page_link + & (bindings::SG_PAGE_LINK_MASK as u64) + & (bindings::SG_END as u64)) + !=3D 0 + } + } + + /// Mark it as the last normal entry in scatterlist. + pub fn mark_end(&mut self) { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { + (*self.opaque.get()).page_link |=3D bindings::SG_END as u64; + (*self.opaque.get()).page_link &=3D !(bindings::SG_CHAIN as u6= 4); + } + } + + /// Mark it as `not` the last normal entry in scatterlist. + pub fn unmark_end(&mut self) { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { + (*self.opaque.get()).page_link &=3D !(bindings::SG_END as u64); + } + } + + /// Get an immutable reference to memory buffer. + pub fn get_buf(&self) -> &[u8] { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + let addr =3D unsafe { bindings::sg_virt(self.opaque.get()) }; + let len =3D self.length(); + // SAFETY: `addr` is returned by `sg_virt`, so it is valid. And th= e memory + // buffer is set by `new` constructor or `set_buf` method, so it's= pinned + // and valid. + unsafe { core::slice::from_raw_parts(addr as _, len) } + } + + /// Get a mutable reference to memory buffer. + pub fn get_mut_buf(&mut self) -> &mut [u8] { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + let addr =3D unsafe { bindings::sg_virt(self.opaque.get()) }; + let len =3D self.length(); + // SAFETY: `addr` is returned by `sg_virt`, so it is valid. And th= e memory + // buffer is set by `new` constructor or `set_buf` method, so it's= pinned + // and valid. + unsafe { core::slice::from_raw_parts_mut(addr as _, len) } + } + + /// Set the memory buffer. + pub fn set_buf(&mut self, buf: &Pin<&mut [u8]>) { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + // And `buf` is pinned and valid. + unsafe { + bindings::sg_set_buf( + self.opaque.get(), + buf.as_ptr() as *const core::ffi::c_void, + buf.len() as core::ffi::c_uint, + ); + } + } + + /// Return the total count of normal entries in scatterlist. + /// + /// It allows to know how many entries are in scatterlist, taking into + /// account chaining as well. + pub fn count(&self) -> usize { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { bindings::sg_nents(self.opaque.get()) as _ } + } +} --=20 2.40.1 From nobody Sun Feb 8 12:31:26 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 147EDC77B7A for ; Sat, 10 Jun 2023 10:49:44 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234292AbjFJKtl (ORCPT ); Sat, 10 Jun 2023 06:49:41 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48930 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234222AbjFJKtf (ORCPT ); Sat, 10 Jun 2023 06:49:35 -0400 Received: from out0-206.mail.aliyun.com (out0-206.mail.aliyun.com [140.205.0.206]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 72B8E35BC; Sat, 10 Jun 2023 03:49:31 -0700 (PDT) X-Alimail-AntiSpam: AC=PASS;BC=-1|-1;BR=01201311R131e4;CH=green;DM=||false|;DS=||;FP=0|-1|-1|-1|0|-1|-1|-1;HT=ay29a033018047209;MF=changxian.cqs@antgroup.com;NM=1;PH=DS;RN=11;SR=0;TI=SMTPD_---.TQGLBah_1686394167; Received: from localhost(mailfrom:changxian.cqs@antgroup.com fp:SMTPD_---.TQGLBah_1686394167) by smtp.aliyun-inc.com; Sat, 10 Jun 2023 18:49:28 +0800 From: "Qingsong Chen" To: linux-kernel@vger.kernel.org Cc: "=?UTF-8?B?55Sw5rSq5Lqu?=" , "Qingsong Chen" , "Miguel Ojeda" , "Alex Gaynor" , "Wedson Almeida Filho" , "Boqun Feng" , "Gary Guo" , "=?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?=" , "Benno Lossin" , Subject: [PATCH v3 2/3] rust: kernel: implement iterators for ScatterList Date: Sat, 10 Jun 2023 18:49:08 +0800 Message-Id: <20230610104909.3202958-3-changxian.cqs@antgroup.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230610104909.3202958-1-changxian.cqs@antgroup.com> References: <20230610104909.3202958-1-changxian.cqs@antgroup.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" ScatterList could be transmuted from raw pointers of a valid `sg_table`. Then we can use those iterators to access the following normal entries. Signed-off-by: Qingsong Chen Reviewed-by: Martin Rodriguez Reboredo --- rust/kernel/scatterlist.rs | 58 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/rust/kernel/scatterlist.rs b/rust/kernel/scatterlist.rs index 7fb8f3326ff3..41e268b93c9e 100644 --- a/rust/kernel/scatterlist.rs +++ b/rust/kernel/scatterlist.rs @@ -290,4 +290,62 @@ impl ScatterList<'_> { // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. unsafe { bindings::sg_nents(self.opaque.get()) as _ } } + + /// Get an iterator for immutable references. + pub fn iter(&self) -> Iter<'_> { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { Iter(ScatterList::as_ref(self.opaque.get())) } + } + + /// Get an iterator for mutable references. + pub fn iter_mut(&mut self) -> IterMut<'_> { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { IterMut(ScatterList::as_mut(self.opaque.get())) } + } +} + +/// An iterator that yields [`Pin<&ScatterList>`]. +/// +/// Only iterate normal scatterlist entries, chainable entry will be skipp= ed. +pub struct Iter<'a>(Option>>); + +impl<'a> Iterator for Iter<'a> { + type Item =3D Pin<&'a ScatterList<'a>>; + + fn next(&mut self) -> Option { + let ptr =3D match &self.0 { + None =3D> return None, + Some(sgl) =3D> sgl.opaque.get(), + }; + // SAFETY: `ptr` is from `self.opaque`, it is valid by the type in= variant. + // And `next` is null, or the next valid scatterlist entry. + unsafe { + let next =3D bindings::sg_next(ptr); + self.0 =3D ScatterList::as_ref(next); + ScatterList::as_ref(ptr) + } + } +} + +/// An iterator that yields [`Pin<&mut ScatterList>`]. +/// +/// Only iterate normal scatterlist entries, chainable entry will be skipp= ed. +pub struct IterMut<'a>(Option>>); + +impl<'a> Iterator for IterMut<'a> { + type Item =3D Pin<&'a mut ScatterList<'a>>; + + fn next(&mut self) -> Option { + let ptr =3D match &self.0 { + None =3D> return None, + Some(sgl) =3D> sgl.opaque.get(), + }; + // SAFETY: `ptr` is from `self.opaque`, it is valid by the type in= variant. + // And `next` is null, or the next valid scatterlist entry. + unsafe { + let next =3D bindings::sg_next(ptr); + self.0 =3D ScatterList::as_mut(next); + ScatterList::as_mut(ptr) + } + } } --=20 2.40.1 From nobody Sun Feb 8 12:31:26 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id B3438C7EE29 for ; Sat, 10 Jun 2023 10:50:03 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234439AbjFJKuB (ORCPT ); Sat, 10 Jun 2023 06:50:01 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49204 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234340AbjFJKtr (ORCPT ); Sat, 10 Jun 2023 06:49:47 -0400 Received: from out0-202.mail.aliyun.com (out0-202.mail.aliyun.com [140.205.0.202]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D975B3C26; Sat, 10 Jun 2023 03:49:37 -0700 (PDT) X-Alimail-AntiSpam: AC=PASS;BC=-1|-1;BR=01201311R201e4;CH=green;DM=||false|;DS=||;FP=0|-1|-1|-1|0|-1|-1|-1;HT=ay29a033018047192;MF=changxian.cqs@antgroup.com;NM=1;PH=DS;RN=11;SR=0;TI=SMTPD_---.TQFQXhD_1686394172; Received: from localhost(mailfrom:changxian.cqs@antgroup.com fp:SMTPD_---.TQFQXhD_1686394172) by smtp.aliyun-inc.com; Sat, 10 Jun 2023 18:49:33 +0800 From: "Qingsong Chen" To: linux-kernel@vger.kernel.org Cc: "=?UTF-8?B?55Sw5rSq5Lqu?=" , "Qingsong Chen" , "Miguel Ojeda" , "Alex Gaynor" , "Wedson Almeida Filho" , "Boqun Feng" , "Gary Guo" , "=?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?=" , "Benno Lossin" , Subject: [PATCH v3 3/3] rust: kernel: add SgTable abstraction Date: Sat, 10 Jun 2023 18:49:09 +0800 Message-Id: <20230610104909.3202958-4-changxian.cqs@antgroup.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230610104909.3202958-1-changxian.cqs@antgroup.com> References: <20230610104909.3202958-1-changxian.cqs@antgroup.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" SgTable is similar to `struct sg_table`, consisted of scatterlist entries, and could be chained with each other. Signed-off-by: Qingsong Chen Reviewed-by: Martin Rodriguez Reboredo --- rust/kernel/scatterlist.rs | 198 +++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) diff --git a/rust/kernel/scatterlist.rs b/rust/kernel/scatterlist.rs index 41e268b93c9e..870904d53e81 100644 --- a/rust/kernel/scatterlist.rs +++ b/rust/kernel/scatterlist.rs @@ -349,3 +349,201 @@ impl<'a> Iterator for IterMut<'a> { } } } + +/// A [`ScatterList`] table of fixed `N` entries. +/// +/// According to the design of kernel's `struct sg_table`, the `page_link` +/// field of one `scatterlist` may contain a pointer to another. That is, +/// there could exist external pointers to it, making it necessary to pin +/// this struct. +/// +/// If the table is chainable, the last entry will be reserved for chainin= g. +/// The recommended way to create such instances is with the [`pin_init`]. +/// +/// # Examples +/// +/// The following are some use cases of [`SgTable`]. +/// +/// ```rust +/// use core::pin::pin;; +/// # use kernel::error::Result; +/// # use kernel::scatterlist::{ScatterList, SgTable}; +/// +/// // Prepare memory buffers. +/// let buf0: Pin<&mut [u8]> =3D pin!([0u8; 512]); +/// let buf1: Pin<&mut [u8]> =3D pin!([1u8; 512]); +/// let mut entries: Vec> =3D Vec::>::new(); +/// entries.try_push(buf0)?; +/// entries.try_push(buf1)?; +/// +/// // Allocate an instance on stack. +/// kernel::stack_try_pin_init!(let foo =3D? SgTable::new(entries.as_slice= (), false)); +/// let mut foo: Pin<&mut SgTable<'_, 2>> =3D foo; +/// assert_eq!(foo.count(), 2); +/// +/// // Allocate a chainable instance by Box::pin_init. +/// let mut bar: Pin>> =3D Box::pin_init(SgTable::new(e= ntries.as_slice(), true))?; +/// assert_eq!(bar.count(), 2); +/// +/// // Chain two `SgTable` together. +/// bar.chain_sgt(foo.as_mut())?; +/// assert_eq!(bar.count(), 4); +/// +/// // Get an immutable reference to the entry in the table. +/// let sgl1: Pin<&ScatterList<'_>> =3D bar.get(1).ok_or(EINVAL)?; +/// assert_eq!(sgl1.count(), 3); +/// assert_eq!(sgl1.get_buf(), [1u8; 512]); +/// +/// // Get a mutable reference to the entry in the table. +/// let sgl2: Pin<&mut ScatterList<'_>> =3D bar.get_mut(2).ok_or(EINVAL)?; +/// assert_eq!(sgl2.count(), 2); +/// assert_eq!(sgl2.get_buf(), [0u8; 512]); +/// +/// // Try to get a non-exist entry from the table. +/// let sgl4 =3D bar.get(4); +/// assert_eq!(sgl4.is_none(), true); +/// +/// // Split the first table from chained scatterlist. +/// bar.split()?; +/// assert_eq!(bar.count(), 2); +/// ``` +#[pin_data] +pub struct SgTable<'a, const N: usize> { + #[pin] + entries: [ScatterList<'a>; N], +} + +impl<'a, const N: usize> SgTable<'a, N> { + /// Construct a new initializer. + /// + /// # Errors + /// + /// The length of `entries` should exactly be the available size of [`= SgTable`], + /// or else an error is returned. + /// + /// If the table is `chainable`, the available size is `N - 1`, becaus= e one entry + /// should be reserved for chaining. + pub fn new( + entries: &'a [Pin<&mut [u8]>], + chainable: bool, + ) -> impl PinInit, Error> { + build_assert!(N > 0); + // SAFETY: `slot` is valid while the closure is called, the `entri= es` are + // pinned and valid. + unsafe { + init::pin_init_from_closure(move |slot: *mut Self| { + let mut nr_entry =3D N; + if chainable { + nr_entry -=3D 1; + } + if nr_entry =3D=3D 0 || entries.len() !=3D nr_entry { + return Err(EINVAL); + } + + for i in 0..nr_entry { + // `slot` contains uninit memory, avoid creating a ref= erence. + let opaque =3D addr_of!((*slot).entries[i].opaque); + let sgl =3D Opaque::raw_get(opaque); + + bindings::sg_set_buf(sgl, entries[i].as_ptr() as _, en= tries[i].len() as _); + if i + 1 =3D=3D nr_entry { + (*sgl).page_link |=3D bindings::SG_END as u64; + (*sgl).page_link &=3D !(bindings::SG_CHAIN as u64); + } + } + Ok(()) + }) + } + } + + /// Chain two [`SgTable`] together. + /// + /// Transfer the last entry of this table as a chainable pointer to the + /// first entry of `sgt` SgTable. + /// + /// # Errors + /// + /// Return an error if this table is not chainable or has been chained. + pub fn chain_sgt(&mut self, sgt: Pin<&mut SgTable<'_, = M>>) -> Result { + if self.count() !=3D N - 1 { + return Err(EINVAL); + } + self.entries[N - 2].unmark_end(); + + // SAFETY: `sgt.entries` are initialized by the `new` constructor, + // so it's valid. + let next =3D unsafe { ScatterList::as_mut(sgt.entries[0].opaque.ge= t()).unwrap() }; + self.entries[N - 1].chain_sgl(next); + Ok(()) + } + + /// Chain [`SgTable`] and [`ScatterList`] together. + /// + /// Transfer the last entry of this table as a chainable pointer to `s= gl` + /// scatterlist. + /// + /// # Errors + /// + /// Return an error if this table is not chainable or has been chained. + pub fn chain_sgl(&mut self, sgl: Pin<&mut ScatterList<'_>>) -> Result { + if self.count() !=3D N - 1 { + return Err(EINVAL); + } + self.entries[N - 2].unmark_end(); + self.entries[N - 1].chain_sgl(sgl); + Ok(()) + } + + /// Split the first table from chained scatterlist. + /// + /// # Errors + /// + /// Return an error if this table is not chainable or has not been cha= ined. + pub fn split(&mut self) -> Result { + if !self.entries[N - 1].is_chain() { + return Err(EINVAL); + } + self.entries[N - 2].mark_end(); + Ok(()) + } + + /// Return the total count of normal entries in the table. + /// + /// It allows to know how many entries are in the table, taking into a= ccount + /// chaining as well. + pub fn count(&self) -> usize { + // SAFETY: `self.entries` are initialized by the `new` constructor, + // so it's valid. + unsafe { bindings::sg_nents(self.entries[0].opaque.get()) as _ } + } + + /// Get an immutable reference to `n`th entry in the table. + /// + /// Like most indexing operations, the count starts from zero. Return = None + /// if `n` is greater than or equal to the total count of entries. + pub fn get(&self, n: usize) -> Option>> { + self.iter().nth(n) + } + + /// Get a mutable reference to `n`th entry in the table. + /// + /// Like most indexing operations, the count starts from zero. Return = None + /// if `n` is greater than or equal to the number of total entries. + pub fn get_mut(&mut self, n: usize) -> Option= >> { + self.iter_mut().nth(n) + } + + /// Get an iterator for immutable entries. + pub fn iter(&self) -> Iter<'_> { + // SAFETY: `self.entries` are initialized by the `new` constructor, + // so it's valid. + unsafe { Iter(ScatterList::as_ref(self.entries[0].opaque.get())) } + } + + /// Get an iterator for mutable entries. + pub fn iter_mut(&mut self) -> IterMut<'_> { + // SAFETY: `self.entries` are initialized by the `new` constructor, + // so it's valid. + unsafe { IterMut(ScatterList::as_mut(self.entries[0].opaque.get())= ) } + } +} --=20 2.40.1