[PATCH v4 0/3] rust: add kunit doctest with doc fixes

[PATCH v4 0/3] rust: add kunit doctest with doc fixes

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

Link: https://lore.kernel.org/lkml/20241203051843.291729-1-jtostler1@gmail.com/ [v1]
Link: https://lore.kernel.org/lkml/20241205105627.992587-1-jtostler1@gmail.com/ [v2]
Link: https://lore.kernel.org/lkml/cover.1734477232.git.jtostler1@gmail.com/    [v3]
Signed-off-by: Jimmy Ostler <jtostler1@gmail.com>
---
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/20241205105627.992587-1-jtostler1@gmail.com/

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/20241203051843.291729-1-jtostler1@gmail.com/

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

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

[Jimmy Ostler]

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

Acked-by: Danilo Krummrich <dakr@kernel.org>
Signed-off-by: Jimmy Ostler <jtostler1@gmail.com>
---
 rust/kernel/error.rs | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs
index 914e8dec1abd..f6ecf09cb65f 100644
--- a/rust/kernel/error.rs
+++ b/rust/kernel/error.rs
@@ -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;
-- 
2.47.1

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

[Jimmy Ostler]

Change documentation imports to use `kernel::alloc::AllocError`,
because `KBox::new()` now returns that, instead of the 'core'
`AllocError`.

Reviewed-by: Danilo Krummrich <dakr@kernel.org>
Signed-off-by: Jimmy Ostler <jtostler1@gmail.com>
---
 rust/kernel/init.rs | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
index 347049df556b..3d099908dbd5 100644
--- a/rust/kernel/init.rs
+++ b/rust/kernel/init.rs
@@ -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]
-- 
2.47.1

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

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

Suggested-by: Boqun Feng <boqun.feng@gmail.com>
Link: https://github.com/Rust-for-Linux/linux/issues/1131
Reviewed-by: Danilo Krummrich <dakr@kernel.org>
Signed-off-by: Jimmy Ostler <jtostler1@gmail.com>
---
 rust/kernel/alloc/layout.rs | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/rust/kernel/alloc/layout.rs b/rust/kernel/alloc/layout.rs
index 4b3cd7fdc816..0e053dcc7941 100644
--- a/rust/kernel/alloc/layout.rs
+++ b/rust/kernel/alloc/layout.rs
@@ -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 => {
-- 
2.47.1

Re: [PATCH v4 0/3] rust: add kunit doctest with doc fixes

[Miguel Ojeda]

On Fri, Dec 20, 2024 at 7:25 AM Jimmy Ostler <jtostler1@gmail.com> wrote:
>
> 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