From 17d5efcbfe6f3da23afb79d84c27cefb2b3f331a Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Sat, 26 Jul 2025 20:07:50 +0200 Subject: rust: kernel: remove support for unused host `#[test]`s Since commit 028df914e546 ("rust: str: convert `rusttest` tests into KUnit"), we do not have anymore host `#[test]`s that run in the host. Moreover, we do not plan to add any new ones -- tests should generally run within KUnit, since there they are built the same way the kernel does. While we may want to have some way to define tests that can also be run outside the kernel, we still want to test within the kernel too [1], and thus would likely use a custom syntax anyway to define them. Thus simplify the `rusttest` target by removing support for host `#[test]`s for the `kernel` crate. This still maintains the support for the `macros` crate, even though we do not have any such tests there. Link: https://lore.kernel.org/rust-for-linux/CABVgOS=AKHSfifp0S68K3jgNZAkALBr=7iFb=niryG5WDxjSrg@mail.gmail.com/ [1] Signed-off-by: Miguel Ojeda Reviewed-by: Danilo Krummrich Reviewed-by: David Gow Link: https://lore.kernel.org/r/20250726180750.2735836-1-ojeda@kernel.org Signed-off-by: Danilo Krummrich --- rust/kernel/error.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'rust/kernel/error.rs') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index a41de293dcd1..67da2d118e65 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -158,7 +158,7 @@ impl Error { } /// Returns a string representing the error, if one exists. - #[cfg(not(any(test, testlib)))] + #[cfg(not(testlib))] pub fn name(&self) -> Option<&'static CStr> { // SAFETY: Just an FFI call, there are no extra safety requirements. let ptr = unsafe { bindings::errname(-self.0.get()) }; @@ -175,7 +175,7 @@ impl Error { /// When `testlib` is configured, this always returns `None` to avoid the dependency on a /// kernel function so that tests that use this (e.g., by calling [`Result::unwrap`]) can still /// run in userspace. - #[cfg(any(test, testlib))] + #[cfg(testlib)] pub fn name(&self) -> Option<&'static CStr> { None } -- cgit v1.2.3 From 6d65ccac394c7539e710c569e21067f617493171 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Onur=20=C3=96zkan?= Date: Thu, 31 Jul 2025 23:41:15 +0300 Subject: rust: error: add C header links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The error codes come from several headers. Thus, add the other header links. Signed-off-by: Onur Özkan Reviewed-by: Daniel Almeida [ Sorted headers. Added line breaks. Reworded commit message. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'rust/kernel/error.rs') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 67da2d118e65..db14da976722 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -2,7 +2,9 @@ //! Kernel errors. //! -//! C header: [`include/uapi/asm-generic/errno-base.h`](srctree/include/uapi/asm-generic/errno-base.h) +//! C header: [`include/uapi/asm-generic/errno-base.h`](srctree/include/uapi/asm-generic/errno-base.h)\ +//! C header: [`include/uapi/asm-generic/errno.h`](srctree/include/uapi/asm-generic/errno.h)\ +//! C header: [`include/linux/errno.h`](srctree/include/linux/errno.h) use crate::{ alloc::{layout::LayoutError, AllocError}, -- cgit v1.2.3 From 58b4aa53606f75c7d6e6cd4710da4d4399e8f667 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Fri, 29 Aug 2025 21:22:41 +0200 Subject: rust: error: improve `Error::from_errno` documentation This constructor is public since commit 5ed147473458 ("rust: error: make conversion functions public"), and we will refer to it from the documentation of `to_result` in a later commit. Thus improve its documentation, including adding examples. Reviewed-by: Alexandre Courbot Reviewed-by: Benno Lossin Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) (limited to 'rust/kernel/error.rs') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index db14da976722..edd576b7dfe4 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -103,8 +103,23 @@ pub struct Error(NonZeroI32); impl Error { /// Creates an [`Error`] from a kernel error code. /// - /// It is a bug to pass an out-of-range `errno`. `EINVAL` would - /// be returned in such a case. + /// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`). + /// + /// It is a bug to pass an out-of-range `errno`. [`code::EINVAL`] is returned in such a case. + /// + /// # Examples + /// + /// ``` + /// assert_eq!(Error::from_errno(-1), EPERM); + /// assert_eq!(Error::from_errno(-2), ENOENT); + /// ``` + /// + /// The following calls are considered a bug: + /// + /// ``` + /// assert_eq!(Error::from_errno(0), EINVAL); + /// assert_eq!(Error::from_errno(-1000000), EINVAL); + /// ``` pub fn from_errno(errno: crate::ffi::c_int) -> Error { if let Some(error) = Self::try_from_errno(errno) { error -- cgit v1.2.3 From 099381a08db3539c6aab6616c94d7950d74fcd2d Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Fri, 29 Aug 2025 21:22:42 +0200 Subject: rust: error: improve `to_result` documentation Core functions like `to_result` should have good documentation. Thus improve it, including adding an example of how to perform early returns with it. Reviewed-by: Benno Lossin Reviewed-by: Alexandre Courbot Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) (limited to 'rust/kernel/error.rs') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index edd576b7dfe4..1c0e0e241daa 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -392,8 +392,43 @@ impl From for Error { /// [Rust documentation]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html pub type Result = core::result::Result; -/// Converts an integer as returned by a C kernel function to an error if it's negative, and -/// `Ok(())` otherwise. +/// Converts an integer as returned by a C kernel function to a [`Result`]. +/// +/// If the integer is negative, an [`Err`] with an [`Error`] as given by [`Error::from_errno`] is +/// returned. This means the integer must be `>= -MAX_ERRNO`. +/// +/// Otherwise, it returns [`Ok`]. +/// +/// It is a bug to pass an out-of-range negative integer. `Err(EINVAL)` is returned in such a case. +/// +/// # Examples +/// +/// This function may be used to easily perform early returns with the [`?`] operator when working +/// with C APIs within Rust abstractions: +/// +/// ``` +/// # use kernel::error::to_result; +/// # mod bindings { +/// # #![expect(clippy::missing_safety_doc)] +/// # use kernel::prelude::*; +/// # pub(super) unsafe fn f1() -> c_int { 0 } +/// # pub(super) unsafe fn f2() -> c_int { EINVAL.to_errno() } +/// # } +/// fn f() -> Result { +/// // SAFETY: ... +/// to_result(unsafe { bindings::f1() })?; +/// +/// // SAFETY: ... +/// to_result(unsafe { bindings::f2() })?; +/// +/// // ... +/// +/// Ok(()) +/// } +/// # assert_eq!(f(), Err(EINVAL)); +/// ``` +/// +/// [`?`]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator pub fn to_result(err: crate::ffi::c_int) -> Result { if err < 0 { Err(Error::from_errno(err)) -- cgit v1.2.3