rust: add kunit doctest with doc fixes
Subsystems (3)
v3 cover rust: add kunit doctest with doc fixes
This patch series adds a doctest for the ArrayLayout type, as well as implements From<LayoutError> for Error for the internal LayoutError. This change in the first patch is required for the added rustdoc kunit test in the third patch to compile.
This series also adds a change to the stack_try_pin_init example documentation, so it correctly imports the AllocError kernel type.
---
v2 -> v3:
- Remove From implementation on core::alloc::LayoutError
- Move changes to "rust/kernel/alloc/layout.rs" to separate patch
- Move changes to "rust/kernel/error.rs" to separate patch
- Change documentation in "rust/kernel/init.rs"
- Link [v2]: https://lore.kernel.org/lkml/[email protected]/
v1 -> v2 changes:
- Add third assert where length is smaller but still overflows
- Remove rustdoc markdown codeblock languge signifier
- Change tests to return results using ? instead of panic
- Remove #[derive(Debug)] for LayoutError
- Add From<LayoutError> for Error implementation
- Link [v1]: https://lore.kernel.org/lkml/[email protected]/
Jimmy Ostler (3):
rust: error: Change LayoutError to internal
rust: error: Update 'stack_try_pin_init' example
rust: alloc: Add doctest for ArrayLayout
rust/kernel/alloc/layout.rs | 19 +++++++++++++++++++ rust/kernel/error.rs | 7 ++++--- rust/kernel/init.rs | 22 ++++++++++++++++++---- 3 files changed, 41 insertions(+), 7 deletions(-)
base-commit: 9a02cbc5139e668f8b74e75a611d3a04b5241228
Signature · 1 line
2.47.1
PATCH v3 1/3 rust: error: Change `LayoutError` to internal
Add an implementation of From<LayoutError> for Error for the kernel::alloc::layout::LayoutError.
Remove the implementation on core::alloc::LayoutError, because we don't use it anywhere.
--- rust/kernel/error.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
rust/kernel/error.rs +4 -3
@@ -4,9 +4,10 @@//! //! C header: [`include/uapi/asm-generic/errno-base.h`](srctree/include/uapi/asm-generic/errno-base.h) -use crate ::{alloc::AllocError , str::CStr }; - -use core::alloc::LayoutError ; +use crate ::{ + alloc::{layout::LayoutError ,AllocError }, + str::CStr , +};use core::fmt;use core::num::NonZeroI32 ;
Signature · 1 line
2.47.1
Re: [PATCH v3 1/3] rust: error: Change `LayoutError` to internal
Quoted 5 lines · Jimmy Ostler
Add an implementation of
From<LayoutError> for Errorfor thekernel::alloc::layout::LayoutError.
Remove the implementation oncore::alloc::LayoutError, because we don't use it anywhere.
No need to send a new version for this, but it may make sense to reword to clarify that this switches the import, and therefore the impl switches from one to the other. The way it is written, it sounds like an actual impl item was textually added and another one removed.
Cheers,
Miguel
Re: [PATCH v3 1/3] rust: error: Change `LayoutError` to internal
Quoted 7 lines · Miguel Ojeda
Quoted 5 lines · Jimmy Ostler
Add an implementation of
From<LayoutError> for Errorfor thekernel::alloc::layout::LayoutError.
Remove the implementation oncore::alloc::LayoutError, because we don't use it anywhere.
Quoted 5 lines
No need to send a new version for this, but it may make sense to reword to clarify that this switches the import, and therefore the
implswitches from one to the other. The way it is written, it sounds like an actualimplitem was textually added and another one removed.
Agree with Miguel, the commit message is slightly misleading.
With that fixed,
Quoted 3 lines
Cheers,
Miguel
Re: [PATCH v3 1/3] rust: error: Change `LayoutError` to internal
Quoted 9 lines · Danilo Krummrich
Quoted 7 lines · Miguel Ojeda
Quoted 5 lines · Jimmy Ostler
Add an implementation of
From<LayoutError> for Errorfor thekernel::alloc::layout::LayoutError.
Remove the implementation oncore::alloc::LayoutError, because we don't use it anywhere.
Quoted 7 lines
Quoted 5 lines
No need to send a new version for this, but it may make sense to reword to clarify that this switches the import, and therefore the
implswitches from one to the other. The way it is written, it sounds like an actualimplitem was textually added and another one removed.Agree with Miguel, the commit message is slightly misleading.
That's a good point, I can reword that.
Quoted 1 line
With that fixed,
I'll submit a v4 with that fixed, thanks.
Quoted 5 lines
Acked-by Danilo Krummrich <[email protected]>Quoted 3 lines
Cheers,
Miguel
Thanks,
Jimmy Ostler
PATCH v3 2/3 rust: error: Update 'stack_try_pin_init' example
In reply to Jimmy OstlerChange documentation imports to use kernel::alloc::AllocError, because KBox::new() now returns that, instead of the 'core' AllocError.
--- rust/kernel/init.rs | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-)
rust/kernel/init.rs +18 -4
@@ -290,9 +290,16 @@ macro_rules! stack_pin_init {/// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] -/// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex}; +/// # use kernel::{init, +/// # pin_init, +/// # stack_try_pin_init, +/// # init::*, +/// # sync::Mutex, +/// # new_mutex, +/// # alloc::AllocError +/// # }; /// # use macros::pin_data; -/// # use core::{alloc::AllocError, pin::Pin}; +/// # use core::pin::Pin; /// #[pin_data] /// struct Foo { /// #[pin]
@@ -316,9 +323,16 @@ macro_rules! stack_pin_init {/// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] -/// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex}; +/// # use kernel::{init, +/// # pin_init, +/// # stack_try_pin_init, +/// # init::*, +/// # sync::Mutex, +/// # new_mutex, +/// # alloc::AllocError +/// # }; /// # use macros::pin_data; -/// # use core::{alloc::AllocError, pin::Pin}; +/// # use core::pin::Pin; /// #[pin_data] /// struct Foo { /// #[pin]
Signature · 1 line
2.47.1
Re: [PATCH v3 2/3] rust: error: Update 'stack_try_pin_init' example
Quoted 5 lines · Jimmy Ostler
Change documentation imports to use
kernel::alloc::AllocError, becauseKBox::new()now returns that, instead of the 'core'AllocError.Signed-off-by Jimmy Ostler <[email protected]>
Quoted 49 lines
--- rust/kernel/init.rs | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-)rust/kernel/init.rs +18
-4@@ -290,9 +290,16 @@ macro_rules! stack_pin_init {/// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] -/// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex}; +/// # use kernel::{init, +/// # pin_init, +/// # stack_try_pin_init, +/// # init::*, +/// # sync::Mutex, +/// # new_mutex, +/// # alloc::AllocError +/// # }; /// # use macros::pin_data; -/// # use core::{alloc::AllocError, pin::Pin}; +/// # use core::pin::Pin; /// #[pin_data] /// struct Foo { /// #[pin] @@ -316,9 +323,16 @@ macro_rules! stack_pin_init {/// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] -/// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex}; +/// # use kernel::{init, +/// # pin_init, +/// # stack_try_pin_init, +/// # init::*, +/// # sync::Mutex, +/// # new_mutex, +/// # alloc::AllocError +/// # }; /// # use macros::pin_data; -/// # use core::{alloc::AllocError, pin::Pin}; +/// # use core::pin::Pin; /// #[pin_data] /// struct Foo { /// #[pin] Signature · 1 line
2.47.1
PATCH v3 3/3 rust: alloc: Add doctest for `ArrayLayout`
In reply to Jimmy OstlerAdd a rustdoc example and Kunit test to the ArrayLayout struct's ArrayLayout::new() function.
This patch depends on the first patch in this series in order for the kunit test to compile.
--- rust/kernel/alloc/layout.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)
rust/kernel/alloc/layout.rs +19 -0
@@ -43,6 +43,25 @@ pub const fn empty() -> Self {/// # Errors /// /// When `len * size_of::<T>()` overflows or when `len * size_of::<T>() > isize::MAX`. +/// +/// # Examples +/// +/// ``` +/// # use kernel::alloc::layout::{ArrayLayout, LayoutError}; +/// let layout = ArrayLayout::<i32>::new(15)?; +/// assert_eq!(layout.len(), 15); +/// +/// // Errors because `len * size_of::<T>()` overflows +/// let layout = ArrayLayout::<i32>::new(isize::MAX as usize); +/// assert!(layout.is_err()); +/// +/// // Errors because `len * size_of::<i32>() > isize::MAX`, +/// // even though `len < isize::MAX` +/// let layout = ArrayLayout::<i32>::new(isize::MAX as usize / 2); +/// assert!(layout.is_err()); +/// +/// # Ok::<(), Error>(()) +/// ``` pub const fn new (len:usize ) ->Result <Self ,LayoutError > {match len.checked_mul (core::mem::size_of ::<T >()) {Some (size)if size <=ISIZE_MAX => {
Signature · 1 line
2.47.1
Re: [PATCH v3 3/3] rust: alloc: Add doctest for `ArrayLayout`
Quoted 9 lines · Jimmy Ostler
Add a rustdoc example and Kunit test to the
ArrayLayoutstruct'sArrayLayout::new()function.This patch depends on the first patch in this series in order for the kunit test to compile.
Suggested-by Boqun Feng <[email protected]>Signed-off-by Jimmy Ostler <[email protected]>
Quoted 37 lines
--- rust/kernel/alloc/layout.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)rust/kernel/alloc/layout.rs +19
-0@@ -43,6 +43,25 @@ pub const fn empty() -> Self {/// # Errors /// /// When `len * size_of::<T>()` overflows or when `len * size_of::<T>() > isize::MAX`. +/// +/// # Examples +/// +/// ``` +/// # use kernel::alloc::layout::{ArrayLayout, LayoutError}; +/// let layout = ArrayLayout::<i32>::new(15)?; +/// assert_eq!(layout.len(), 15); +/// +/// // Errors because `len * size_of::<T>()` overflows +/// let layout = ArrayLayout::<i32>::new(isize::MAX as usize); +/// assert!(layout.is_err()); +/// +/// // Errors because `len * size_of::<i32>() > isize::MAX`, +/// // even though `len < isize::MAX` +/// let layout = ArrayLayout::<i32>::new(isize::MAX as usize / 2); +/// assert!(layout.is_err()); +/// +/// # Ok::<(), Error>(()) +/// ``` pub const fn new (len:usize ) ->Result <Self ,LayoutError > {match len.checked_mul (core::mem::size_of ::<T >()) {Some (size)if size <=ISIZE_MAX => {Signature · 1 line
2.47.1