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

[PATCH v3 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]
Signed-off-by: Jimmy Ostler <jtostler1@gmail.com>
---
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: 9a02cbc5139e668f8b74e75a611d3a04b5241228
-- 
2.47.1

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

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

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

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 v3 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
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 v3 1/3] rust: error: Change `LayoutError` to internal

[Miguel Ojeda]

On Wed, Dec 18, 2024 at 1:24 AM Jimmy Ostler <jtostler1@gmail.com> wrote:
>
> 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

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

[Danilo Krummrich]

On Wed, Dec 18, 2024 at 01:57:29AM +0100, Miguel Ojeda wrote:
> On Wed, Dec 18, 2024 at 1:24 AM Jimmy Ostler <jtostler1@gmail.com> wrote:
> >
> > 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.

Agree with Miguel, the commit message is slightly misleading.

With that fixed,

Acked-by: Danilo Krummrich <dakr@kernel.org>

> 
> Cheers,
> Miguel

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

[Danilo Krummrich]

On Tue, Dec 17, 2024 at 04:23:11PM -0800, Jimmy Ostler wrote:
> Change documentation imports to use `kernel::alloc::AllocError`,
> because `KBox::new()` now returns that, instead of the 'core'
> `AllocError`.
> 
> Signed-off-by: Jimmy Ostler <jtostler1@gmail.com>

Reviewed-by: Danilo Krummrich <dakr@kernel.org>

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

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

[Danilo Krummrich]

On Tue, Dec 17, 2024 at 04:23:12PM -0800, Jimmy Ostler wrote:
> 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
> Signed-off-by: Jimmy Ostler <jtostler1@gmail.com>


Reviewed-by: Danilo Krummrich <dakr@kernel.org>

> ---
>  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 v3 1/3] rust: error: Change `LayoutError` to internal

[Jimmy Ostler]

On Wed, Dec 18, 2024 at 4:43 AM Danilo Krummrich <dakr@kernel.org> wrote:
>
> On Wed, Dec 18, 2024 at 01:57:29AM +0100, Miguel Ojeda wrote:
> > On Wed, Dec 18, 2024 at 1:24 AM Jimmy Ostler <jtostler1@gmail.com> wrote:
> > >
> > > 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.
>
> Agree with Miguel, the commit message is slightly misleading.

That's a good point, I can reword that.

> With that fixed,

I'll submit a v4 with that fixed, thanks.

> Acked-by: Danilo Krummrich <dakr@kernel.org>
>
> >
> > Cheers,
> > Miguel

Thanks,
Jimmy Ostler