rust: add kunit doctest with doc fixes
Subsystems (3)
v4 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.
---
v3 -> v4: Reword patch one message for clarity
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: 0c5928deada15a8d075516e6e0d9ee19011bb000
Signature · 1 line
2.47.1
PATCH v4 1/3 rust: error: Change `LayoutError` to internal
Change the imports in rust/kernel/error.rs to import the internal version of LayoutError instead. This results in the existing From<LayoutError> for Error implementation implmenting for the new internal type instead of for core::alloc::LayoutError.
--- 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
PATCH v4 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
PATCH v4 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
Miguel Ojeda
AppliedQuoted 8 lines · Jimmy Ostler
This patch series adds a doctest for the
ArrayLayouttype, as well as implementsFrom<LayoutError> for Errorfor the internalLayoutError. 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_initexample documentation, so it correctly imports theAllocErrorkernel type.
Applied to rust-next -- thanks everyone!
[ Reworded commit. - Miguel ]
[ Fixed formatting of imports (still unordered). Slightly reworded
commit. - Miguel ]
[ Added periods to example comments. Reworded title. - Miguel ]
Jimmy: I tried to improve the wording a bit more on the first patch following our discussions, to try to be clearer/explicit, but please let me know if I made a mistake or you disagree. Thanks!
Cheers,
Miguel