From nobody Sun Feb 8 17:13:29 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 254B2C77B73 for ; Tue, 30 May 2023 06:49:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229945AbjE3GtB (ORCPT ); Tue, 30 May 2023 02:49:01 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34284 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230261AbjE3Gs5 (ORCPT ); Tue, 30 May 2023 02:48:57 -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 4297EE8; Mon, 29 May 2023 23:48:49 -0700 (PDT) X-Alimail-AntiSpam: AC=PASS;BC=-1|-1;BR=01201311R151e4;CH=green;DM=||false|;DS=||;FP=0|-1|-1|-1|0|-1|-1|-1;HT=ay29a033018047202;MF=changxian.cqs@antgroup.com;NM=1;PH=DS;RN=15;SR=0;TI=SMTPD_---.TGKDcaV_1685429320; Received: from localhost(mailfrom:changxian.cqs@antgroup.com fp:SMTPD_---.TGKDcaV_1685429320) by smtp.aliyun-inc.com; Tue, 30 May 2023 14:48:41 +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" , "Alice Ryhl" , "Martin Rodriguez Reboredo" , "Asahi Lina" , "Niklas Mohrin" , Subject: [PATCH 1/2] rust: kernel: add scatterlist wrapper Date: Tue, 30 May 2023 14:48:20 +0800 Message-Id: <20230530064821.1222290-2-changxian.cqs@antgroup.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230530064821.1222290-1-changxian.cqs@antgroup.com> References: <20230530064821.1222290-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 abstractions for single `struct scatterlist` and chainable `struct sg_table`. Signed-off-by: Qingsong Chen --- rust/bindings/bindings_helper.h | 1 + rust/helpers.c | 14 + rust/kernel/lib.rs | 1 + rust/kernel/scatterlist.rs | 478 ++++++++++++++++++++++++++++++++ 4 files changed, 494 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..183fb4de02a9 --- /dev/null +++ b/rust/kernel/scatterlist.rs @@ -0,0 +1,478 @@ +// 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; + +/// A [`ScatterList`] table of fixed `N` entries. +/// +/// According to the SG table design (form kernel ), the `page_link` field= may contain +/// a pointer to the next sg table list, so this struct should be pinned. = If the table +/// is chainable, the last entry will be reserved for chainning. The recom= mended way to +/// create such instances is with the [`pin_init`]. +/// +/// # Examples +/// +/// The following is examples of creating [`SgTable`] instances. +/// +/// ```rust +/// use kernel::stack_try_pin_init; +/// # use kernel::error::Result; +/// # use kernel::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. +/// stack_try_pin_init!(let foo =3D? SgTable::new(entries.as_slice(), fals= e)); +/// let foo: Pin<&mut SgTable<'_, 2>> =3D foo; +/// assert_eq!(foo.count(), 2); +/// +/// // Alloccate an instance by Box::pin_init. +/// let bar: Result>>> =3D +/// Box::pin_init(SgTable::new(entries.as_slice(), true)); +/// assert_eq!(bar.unwrap().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`, otherwise,= one entry + /// will 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 th= e 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 entries in the table. + /// + /// Allows to know how many entries are in sg, taking into account cha= ining 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) + } +} + +impl<'a, const N: usize> SgTable<'a, 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())) + } +} + +/// Wrap the kernel's `struct scatterlist`. +/// +/// According to the SG table design (from kernel), the `page_link` field = may contain +/// a pointer to the next sg table list, so this struct should be pinned. +/// +/// # Invirants +/// +/// All instances are valid, either created by the `new` constructor (see = [`pin_init`]), +/// or transmuted from raw pointers by the `as_ref` or `as_mut` function (= usually used +/// to get an entry of [`SgTable`]). +/// +/// # Examples +/// +/// The following is examples of creating [`ScatterList`] instances. +/// +/// ```rust +/// use core::pin::pin; +/// # use kernel::error::Result; +/// # use kernel::scatterlist::ScatterList; +/// +/// // Prepare memory buffer. +/// let buf: Pin<&mut [u8]> =3D pin!([0u8; 512]); +/// +/// // Allocates an instance on stack. +/// kernel::stack_pin_init!(let foo =3D ScatterList::new(&buf)); +/// let foo: Pin<&mut ScatterList<'_>> =3D foo; +/// assert_eq!(foo.length(), 512); +/// assert_eq!(foo.count(), 1); +/// +/// // Alloccate an instance by Box::pin_init. +/// let bar: Result>>> =3D Box::pin_init(ScatterLi= st::new(&buf)); +/// assert_eq!(bar.as_ref().unwrap().length(), 512); +/// assert_eq!(bar.as_ref().unwrap().count(), 1); +/// ``` +#[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 [`Pin<&ScatterList>`] from raw pointer. + pub fn as_ref(entry: *mut bindings::scatterlist) -> Option> { + match entry.is_null() { + true =3D> None, + // SAFETY: `entry` is non-null and valid. + false =3D> Some(Pin::new(unsafe { &*(entry as *const ScatterLi= st<'_>) })), + } + } + + /// Obtain [`Pin<&mut ScatterList>`] from raw pointer. + pub fn as_mut(entry: *mut bindings::scatterlist) -> Option> { + match entry.is_null() { + true =3D> None, + // SAFETY: `entry` is non-null and valid. + false =3D> Some(Pin::new(unsafe { &mut *(entry as *mut Scatter= List<'_>) })), + } + } +} + +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 bu= s 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 bu= s address + /// and then called `set_dma` method to setup it. + #[cfg(CONFIG_NEED_SG_DMA_LENGTH)] + pub fn dma_length(&self) -> usize { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { (*self.opaque.get()).dma_length as _ } + } + + /// Return the mapped DMA length. + /// + /// # Safety + /// + /// It is only valid after this scatterlist has been mapped to some bu= s address + /// and then called `set_dma` method to setup it. + #[cfg(not(CONFIG_NEED_SG_DMA_LENGTH))] + pub fn dma_length(&self) -> usize { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { (*self.opaque.get()).length as _ } + } + + /// Setup the DMA address and length. + #[cfg(CONFIG_NEED_SG_DMA_LENGTH)] + pub fn set_dma(&mut self, addr: usize, len: usize) { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { + (*self.opaque.get()).dma_address =3D addr as _; + (*self.opaque.get()).dma_length =3D len as _; + } + self.dma_mark_bus_address(); + } + + /// Setup the DMA address and length. + #[cfg(not(CONFIG_NEED_SG_DMA_LENGTH))] + pub fn set_dma(&mut self, addr: usize, len: usize) { + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + 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 { + #[cfg(CONFIG_PCI_P2PDMA)] + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + 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) { + #[cfg(CONFIG_PCI_P2PDMA)] + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + 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) { + #[cfg(CONFIG_PCI_P2PDMA)] + // SAFETY: By the type invariant, we know that `self.opaque` is va= lid. + unsafe { + (*self.opaque.get()).dma_flags &=3D !bindings::SG_DMA_BUS_ADDR= ESS; + } + } + + /// Return `true` if it is pointed to another scatterlist. + 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 pointer to `sgl`. + 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) & !(bindings::SG_END as= u64); + } + } + + /// Return `true` if it is the last valid scatterlist, not include the= chainable + /// entry (see [`SgTable`]). + 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 valid entry in a list. + 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 a normal entry in a list. + 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 entries in scatterlist. + /// + /// Allows to know how many entries are in scatterlist, taking into ac= count + /// chaining as well (see [`SgTable`]). + 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 _ } + } +} + +/// An iterator that yields [`Pin<&ScatterList>`]. +/// +/// Only iterate valid scatterlist entries, chainable entry will be skippe= d. +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 valid scatterlist entries, chainable entry will be skippe= d. +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) + } +} + +impl ScatterList<'_> { + /// 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())) + } +} --=20 2.40.1 From nobody Sun Feb 8 17:13:29 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 8BA7DC77B73 for ; Tue, 30 May 2023 06:49:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229595AbjE3GtE (ORCPT ); Tue, 30 May 2023 02:49:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34308 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230292AbjE3Gs6 (ORCPT ); Tue, 30 May 2023 02:48:58 -0400 Received: from out0-198.mail.aliyun.com (out0-198.mail.aliyun.com [140.205.0.198]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A358110E; Mon, 29 May 2023 23:48:53 -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=ay29a033018047213;MF=changxian.cqs@antgroup.com;NM=1;PH=DS;RN=16;SR=0;TI=SMTPD_---.TGKDccU_1685429325; Received: from localhost(mailfrom:changxian.cqs@antgroup.com fp:SMTPD_---.TGKDccU_1685429325) by smtp.aliyun-inc.com; Tue, 30 May 2023 14:48:45 +0800 From: "Qingsong Chen" To: linux-kernel@vger.kernel.org Cc: "=?UTF-8?B?55Sw5rSq5Lqu?=" , "Qingsong Chen" , "Boqun Feng" , "Miguel Ojeda" , "Alex Gaynor" , "Wedson Almeida Filho" , "Gary Guo" , "=?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?=" , "Benno Lossin" , "Martin Rodriguez Reboredo" , "Asahi Lina" , "Sven Van Asbroeck" , "Viktor Garske" , "Finn Behrens" , Subject: [PATCH 2/2] samples: rust: add `SgTable` and `ScatterList` selftests Date: Tue, 30 May 2023 14:48:21 +0800 Message-Id: <20230530064821.1222290-3-changxian.cqs@antgroup.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230530064821.1222290-1-changxian.cqs@antgroup.com> References: <20230530064821.1222290-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 selftest module to provide a temporary place to put "pure tests" for Rust funtionality and wrappers. Add test cases for `SgTable` and `ScatterList`. Co-developed-by: Boqun Feng Signed-off-by: Boqun Feng Signed-off-by: Qingsong Chen --- rust/kernel/error.rs | 2 +- samples/rust/Kconfig | 10 ++ samples/rust/Makefile | 1 + samples/rust/rust_selftests.rs | 186 +++++++++++++++++++++++++++++++++ 4 files changed, 198 insertions(+), 1 deletion(-) create mode 100644 samples/rust/rust_selftests.rs diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 5f4114b30b94..40f2db9d57a6 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -68,7 +68,7 @@ pub mod code { /// # Invariants /// /// The value is a valid `errno` (i.e. `>=3D -MAX_ERRNO && < 0`). -#[derive(Clone, Copy, PartialEq, Eq)] +#[derive(Clone, Copy, PartialEq, Eq, Debug)] pub struct Error(core::ffi::c_int); =20 impl Error { diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig index b0f74a81c8f9..a1f29e5aaf83 100644 --- a/samples/rust/Kconfig +++ b/samples/rust/Kconfig @@ -30,6 +30,16 @@ config SAMPLE_RUST_PRINT =20 If unsure, say N. =20 +config SAMPLE_RUST_SELFTESTS + tristate "Self tests" + help + This option builds the self test cases for Rust. + + To compile this as a module, choose M here: + the module will be called rust_selftests. + + If unsure, say N. + config SAMPLE_RUST_HOSTPROGS bool "Host programs" help diff --git a/samples/rust/Makefile b/samples/rust/Makefile index 03086dabbea4..4519a567db7c 100644 --- a/samples/rust/Makefile +++ b/samples/rust/Makefile @@ -2,5 +2,6 @@ =20 obj-$(CONFIG_SAMPLE_RUST_MINIMAL) +=3D rust_minimal.o obj-$(CONFIG_SAMPLE_RUST_PRINT) +=3D rust_print.o +obj-$(CONFIG_SAMPLE_RUST_SELFTESTS) +=3D rust_selftests.o =20 subdir-$(CONFIG_SAMPLE_RUST_HOSTPROGS) +=3D hostprogs diff --git a/samples/rust/rust_selftests.rs b/samples/rust/rust_selftests.rs new file mode 100644 index 000000000000..843d53159ac8 --- /dev/null +++ b/samples/rust/rust_selftests.rs @@ -0,0 +1,186 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Self test cases for Rust. + +use kernel::prelude::*; +// Keep the `use` for a test in its test function. Module-level `use`s are= only for the test +// framework. + +module! { + type: RustSelftests, + name: "rust_selftests", + author: "Rust for Linux Contributors", + description: "Self test cases for Rust", + license: "GPL", +} + +struct RustSelftests; + +/// A summary of testing. +/// +/// A test can +/// +/// * pass (successfully), or +/// * fail (without hitting any error), or +/// * hit an error (interrupted). +/// +/// This is the type that differentiates the first two (pass and fail) cas= es. +/// +/// When a test hits an error, the test function should skip and return th= e error. Note that this +/// doesn't mean the test fails, for example if the system doesn't have en= ough memory for +/// testing, the test function may return an `Err(ENOMEM)` and skip. +#[allow(dead_code)] +enum TestSummary { + Pass, + Fail, +} + +use TestSummary::Fail; +use TestSummary::Pass; + +macro_rules! do_tests { + ($($name:ident),*) =3D> { + let mut total =3D 0; + let mut pass =3D 0; + let mut fail =3D 0; + + $({ + total +=3D 1; + + match $name() { + Ok(Pass) =3D> { + pass +=3D 1; + pr_info!("{} passed!", stringify!($name)); + }, + Ok(Fail) =3D> { + fail +=3D 1; + pr_info!("{} failed!", stringify!($name)); + }, + Err(err) =3D> { + pr_info!("{} hit error {:?}", stringify!($name), err); + } + } + })* + + pr_info!("{} tests run, {} passed, {} failed, {} hit errors\n", + total, pass, fail, total - pass - fail); + + if total =3D=3D pass { + pr_info!("All tests passed. Congratulations!\n"); + } + } +} + +/// An example of test. +#[allow(dead_code)] +fn test_example() -> Result { + // `use` declarations for the test can be put here, e.g. `use foo::bar= ;`. + + // Always pass. + Ok(Pass) +} + +/// A selftest case for `SgTable`. +fn test_sgtable() -> Result { + use core::pin::pin; + use kernel::scatterlist::*; + + // Prepare memory buffers. + let buf0: Pin<&mut [u8]> =3D pin!([0u8; 512]); + let buf1: Pin<&mut [u8]> =3D pin!([1u8; 512]); + let mut entries =3D Vec::>::new(); + entries.try_push(buf0)?; + entries.try_push(buf1)?; + + // Construct two `SgTable` instances. And the first is chainable, which + // requires one entry reserved. + let mut sgt0: Pin>> =3D + Box::pin_init(SgTable::<'_, 3>::new(entries.as_slice(), true))?; + let mut sgt1: Pin>> =3D + Box::pin_init(SgTable::<'_, 2>::new(entries.as_slice(), false))?; + + // Assert the total count of entries in the table. + assert_eq!(sgt0.count(), 2); + assert_eq!(sgt1.count(), 2); + + // Chain two `SgTable` together. + sgt0.chain_sgt(sgt1.as_mut())?; + assert_eq!(sgt0.count(), 4); + assert_eq!(sgt1.count(), 2); + + // Get the immutable reference to the entry in the table. + let sgl1: Pin<&ScatterList<'_>> =3D sgt0.get(1).ok_or(EINVAL)?; + assert_eq!(sgl1.count(), 3); + + // Get the mutable reference to the entry in the table. + let sgl3: Pin<&mut ScatterList<'_>> =3D sgt0.get_mut(3).ok_or(EINVAL)?; + assert_eq!(sgl3.count(), 1); + + // Try to get a non-exist entry from the table. + let sgl4 =3D sgt0.get(4); + assert_eq!(sgl4.is_none(), true); + + // Split the first table from chained scatterlist. + sgt0.split()?; + assert_eq!(sgt0.count(), 2); + assert_eq!(sgt1.count(), 2); + + // Chain `SgTable` with single `ScatterList`. + let mut sgl: Pin>> =3D Box::pin_init(ScatterList::= new(&entries[0]))?; + sgt0.chain_sgl(sgl.as_mut())?; + assert_eq!(sgt0.count(), 3); + + Ok(Pass) +} + +/// A selftest case for `ScatterList`. +fn test_scatterlist() -> Result { + use core::pin::pin; + use kernel::scatterlist::*; + + // Prepare memory buffers. + let buf0: Pin<&mut [u8]> =3D pin!([0u8; 512]); + let buf1: Pin<&mut [u8]> =3D pin!([1u8; 512]); + + // Construct a `ScatterList` instance. And assert its attributes. + let mut sgl: Pin>> =3D Box::pin_init(ScatterList::= new(&buf0))?; + assert_eq!(sgl.length(), 512); + assert_eq!(sgl.is_dma_bus_address(), false); + assert_eq!(sgl.dma_address(), 0); + assert_eq!(sgl.dma_length(), 0); + assert_eq!(sgl.is_chain(), false); + assert_eq!(sgl.is_last(), true); + assert_eq!(sgl.count(), 1); + + // Get an immutable reference to the memory buffer. + assert_eq!(sgl.get_buf(), [0u8; 512]); + + // Reset the memory buffer. + sgl.set_buf(&buf1); + assert_eq!(sgl.get_buf(), [1u8; 512]); + + // Get a mutable reference to memory buffer. + sgl.get_mut_buf().fill(2); + assert_eq!(sgl.get_buf(), [2u8; 512]); + + Ok(Pass) +} + +impl kernel::Module for RustSelftests { + fn init(_module: &'static ThisModule) -> Result { + pr_info!("Rust self tests (init)\n"); + + do_tests! { + test_sgtable, + test_scatterlist + }; + + Ok(RustSelftests) + } +} + +impl Drop for RustSelftests { + fn drop(&mut self) { + pr_info!("Rust self tests (exit)\n"); + } +} --=20 2.40.1