From nobody Sun Feb 8 19:13:04 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 0B1C0C7EE2E for ; Fri, 2 Jun 2023 10:18:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235283AbjFBKSr (ORCPT ); Fri, 2 Jun 2023 06:18:47 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42812 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S235203AbjFBKSl (ORCPT ); Fri, 2 Jun 2023 06:18:41 -0400 Received: from out0-212.mail.aliyun.com (out0-212.mail.aliyun.com [140.205.0.212]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B1E0F18C; Fri, 2 Jun 2023 03:18:38 -0700 (PDT) X-Alimail-AntiSpam: AC=PASS;BC=-1|-1;BR=01201311R211e4;CH=green;DM=||false|;DS=||;FP=0|-1|-1|-1|0|-1|-1|-1;HT=ay29a033018047212;MF=changxian.cqs@antgroup.com;NM=1;PH=DS;RN=14;SR=0;TI=SMTPD_---.TJK9n.P_1685701112; Received: from localhost(mailfrom:changxian.cqs@antgroup.com fp:SMTPD_---.TJK9n.P_1685701112) by smtp.aliyun-inc.com; Fri, 02 Jun 2023 18:18: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" , "Martin Rodriguez Reboredo" , "Alice Ryhl" , "Asahi Lina" , Subject: [PATCH v2 1/3] rust: kernel: add ScatterList abstraction Date: Fri, 02 Jun 2023 18:18:17 +0800 Message-Id: <20230602101819.2134194-2-changxian.cqs@antgroup.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230602101819.2134194-1-changxian.cqs@antgroup.com> References: <20230602101819.2134194-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 --- rust/bindings/bindings_helper.h | 1 + rust/helpers.c | 14 ++ rust/kernel/lib.rs | 1 + rust/kernel/scatterlist.rs | 280 ++++++++++++++++++++++++++++++++ 4 files changed, 296 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..1714ed05f561 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 *sg, const void *buf, + unsigned int buflen) +{ + sg_set_buf(sg, buf, buflen); +} +EXPORT_SYMBOL_GPL(rust_helper_sg_set_buf); + +void *rust_helper_sg_virt(struct scatterlist *sg) +{ + return sg_virt(sg); +} +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..8d6a34afb191 --- /dev/null +++ b/rust/kernel/scatterlist.rs @@ -0,0 +1,280 @@ +// 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::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. +/// +/// # Invirants +/// +/// 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 is 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]); +/// +/// // Allocates 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); +/// +/// // Alloccate 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 a 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 a 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).set_buf(buf); + (*slot).mark_end(); + Ok(()) + }) + } + } + + /// Obtain a pinned reference to an immutable scatterlist from a raw p= ointer. + pub 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. + pub 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. + /// + /// Allows to know how many entries are in scatterlist, taking into ac= count + /// 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 19:13:04 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 38CB1C7EE24 for ; Fri, 2 Jun 2023 10:18:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234410AbjFBKS4 (ORCPT ); Fri, 2 Jun 2023 06:18:56 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42828 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S235289AbjFBKSp (ORCPT ); Fri, 2 Jun 2023 06:18:45 -0400 Received: from out0-199.mail.aliyun.com (out0-199.mail.aliyun.com [140.205.0.199]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9BBF4198; Fri, 2 Jun 2023 03:18:43 -0700 (PDT) X-Alimail-AntiSpam: AC=PASS;BC=-1|-1;BR=01201311R931e4;CH=green;DM=||false|;DS=||;FP=0|-1|-1|-1|0|-1|-1|-1;HT=ay29a033018047213;MF=changxian.cqs@antgroup.com;NM=1;PH=DS;RN=11;SR=0;TI=SMTPD_---.TJMsjA9_1685701117; Received: from localhost(mailfrom:changxian.cqs@antgroup.com fp:SMTPD_---.TJMsjA9_1685701117) by smtp.aliyun-inc.com; Fri, 02 Jun 2023 18:18:38 +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 v2 2/3] rust: kernel: implement iterators for ScatterList Date: Fri, 02 Jun 2023 18:18:18 +0800 Message-Id: <20230602101819.2134194-3-changxian.cqs@antgroup.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230602101819.2134194-1-changxian.cqs@antgroup.com> References: <20230602101819.2134194-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 --- rust/kernel/scatterlist.rs | 50 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/rust/kernel/scatterlist.rs b/rust/kernel/scatterlist.rs index 8d6a34afb191..292fcb63a329 100644 --- a/rust/kernel/scatterlist.rs +++ b/rust/kernel/scatterlist.rs @@ -277,4 +277,54 @@ 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<'_> { + Iter(ScatterList::as_ref(self.opaque.get())) + } + + /// Get an iterator for mutable references. + pub fn iter_mut(&mut self) -> IterMut<'_> { + 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 { + if self.0.is_none() { + return None; + } + let ptr =3D self.0.as_ref().unwrap().opaque.get(); + // SAFETY: `ptr` is from `self.opaque`, it is valid by the type in= variant. + let next =3D unsafe { 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 { + if self.0.is_none() { + return None; + } + let ptr =3D self.0.as_ref().unwrap().opaque.get(); + // SAFETY: `ptr` is from `self.opaque`, it is valid by the type in= variant. + let next =3D unsafe { bindings::sg_next(ptr) }; + self.0 =3D ScatterList::as_mut(next); + ScatterList::as_mut(ptr) + } } --=20 2.40.1 From nobody Sun Feb 8 19:13:04 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 50CF4C7EE24 for ; Fri, 2 Jun 2023 10:19:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235303AbjFBKTA (ORCPT ); Fri, 2 Jun 2023 06:19:00 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43088 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S235282AbjFBKS4 (ORCPT ); Fri, 2 Jun 2023 06:18:56 -0400 Received: from out0-201.mail.aliyun.com (out0-201.mail.aliyun.com [140.205.0.201]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 37790198; Fri, 2 Jun 2023 03:18:49 -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=ay29a033018047188;MF=changxian.cqs@antgroup.com;NM=1;PH=DS;RN=11;SR=0;TI=SMTPD_---.TJMsjC0_1685701122; Received: from localhost(mailfrom:changxian.cqs@antgroup.com fp:SMTPD_---.TJMsjC0_1685701122) by smtp.aliyun-inc.com; Fri, 02 Jun 2023 18:18:43 +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 v2 3/3] rust: kernel: add SgTable abstraction Date: Fri, 02 Jun 2023 18:18:19 +0800 Message-Id: <20230602101819.2134194-4-changxian.cqs@antgroup.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230602101819.2134194-1-changxian.cqs@antgroup.com> References: <20230602101819.2134194-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 --- rust/kernel/scatterlist.rs | 172 +++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) diff --git a/rust/kernel/scatterlist.rs b/rust/kernel/scatterlist.rs index 292fcb63a329..fd30f61a9743 100644 --- a/rust/kernel/scatterlist.rs +++ b/rust/kernel/scatterlist.rs @@ -328,3 +328,175 @@ impl<'a> Iterator for IterMut<'a> { ScatterList::as_mut(ptr) } } + +/// 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 chainni= ng. +/// The recommended way to create such instances is with the [`pin_init`]. +/// +/// # Examples +/// +/// The following is 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)?; +/// +/// // Allocates 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); +/// +/// // Alloccate 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 the 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 the 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. + /// + /// The length of `entries` should exactly be the available size of [`= SgTable`]. + /// If the table is `chainable`, the available size is `N - 1`, becaus= e one entry + /// should be reserved for chainning. + 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 { + let sgl =3D &mut (*slot).entries[i]; + sgl.set_buf(&entries[i]); + if i + 1 =3D=3D nr_entry { + sgl.mark_end(); + } + } + Ok(()) + }) + } + } + + /// Chain two [`SgTable`] together. + /// + /// Transfer the last entry of this table as a chainable pointer to the + /// first entry of `sgt` SgTable. + 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(); + + let next =3D ScatterList::as_mut(sgt.entries[0].opaque.get()).ok_o= r(EINVAL)?; + 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. + 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. + 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. + /// + /// Allows to know how many entries are in sg, taking into account + /// 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 the 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 the 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<'_> { + Iter(ScatterList::as_ref(self.entries[0].opaque.get())) + } + + /// Get an iterator for mutable entries. + pub fn iter_mut(&mut self) -> IterMut<'_> { + IterMut(ScatterList::as_mut(self.entries[0].opaque.get())) + } +} --=20 2.40.1