Skip to contentSkip to conversation

rust: add kunit doctest with doc fixes

PATCH Superseded Jimmy Ostler 3 participants 9 messages Dec 18, 2024 – Dec 20, 2024

Subsystems (3)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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

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
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

Re: [PATCH v3 1/3] rust: error: Change `LayoutError` to internal

Quoted 5 lines · Jimmy Ostler

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.

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

maintainer Acked-by
#3 lore raw

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 Error for the kernel::alloc::layout::LayoutError.
Remove the implementation on core::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 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.

Agree with Miguel, the commit message is slightly misleading.

With that fixed,

Quoted 3 lines

Cheers,
Miguel

#4 lore raw

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 Error for the kernel::alloc::layout::LayoutError.
Remove the implementation on core::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 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.

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
Quoted 3 lines

Cheers,
Miguel

Thanks,
Jimmy Ostler

#5 lore raw

PATCH v3 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
maintainer Reviewed-by on v3 2/3
#6 lore raw

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, because KBox::new() now returns that, instead of the 'core' AllocError.

Quoted 49 lines
---
 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
#7 lore raw

PATCH v3 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
maintainer Reviewed-by on v3 3/3
#8 lore raw

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 ArrayLayout struct's ArrayLayout::new() function.

This patch depends on the first patch in this series in order for the kunit test to compile.

Quoted 37 lines
---
 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