Skip to contentSkip to conversation

rust: add kunit doctest with doc fixes

PATCH Applied Jimmy Ostler 2 participants 5 messages Dec 20, 2024 – Jan 13, 2025

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 914e8dec1abd..f6ecf09cb65f 100644
@@ -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
#2 lore raw

PATCH v4 2/3 rust: error: Update 'stack_try_pin_init' example

In reply to Jimmy Ostler

Change 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
index 347049df556b..3d099908dbd5 100644
@@ -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
#3 lore raw

PATCH v4 3/3 rust: alloc: Add doctest for `ArrayLayout`

In reply to Jimmy Ostler

Add 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
index 4b3cd7fdc816..0e053dcc7941 100644
@@ -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
Applied
#4 lore raw
In reply to Jimmy Ostler
Quoted 8 lines · Jimmy Ostler

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.

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