From 46384d0990bf99ed8b597e8794ea581e2a647710 Mon Sep 17 00:00:00 2001 From: Asahi Lina Date: Mon, 3 Apr 2023 18:48:10 +0900 Subject: rust: error: Rename to_kernel_errno() -> to_errno() This is kernel code, so specifying "kernel" is redundant. Let's simplify things and just call it to_errno(). Reviewed-by: Gary Guo Reviewed-by: Martin Rodriguez Reboredo Signed-off-by: Asahi Lina Link: https://lore.kernel.org/r/20230224-rust-error-v3-1-03779bddc02b@asahilina.net Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'rust/kernel/error.rs') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 5b9751d7ff1d..35894fa35efe 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -73,7 +73,7 @@ pub struct Error(core::ffi::c_int); impl Error { /// Returns the kernel error code. - pub fn to_kernel_errno(self) -> core::ffi::c_int { + pub fn to_errno(self) -> core::ffi::c_int { self.0 } } -- cgit v1.2.3-59-g8ed1b From c7e20faa5fcad7a177cf6c306138010343dd6d3e Mon Sep 17 00:00:00 2001 From: Asahi Lina Date: Mon, 3 Apr 2023 18:48:11 +0900 Subject: rust: error: Add Error::to_ptr() This is the Rust equivalent to ERR_PTR(), for use in C callbacks. Marked as #[allow(dead_code)] for now, since it does not have any consumers yet. Reviewed-by: Martin Rodriguez Reboredo Signed-off-by: Asahi Lina Reviewed-by: Gary Guo Link: https://lore.kernel.org/r/20230224-rust-error-v3-2-03779bddc02b@asahilina.net Signed-off-by: Miguel Ojeda --- rust/helpers.c | 7 +++++++ rust/kernel/error.rs | 7 +++++++ 2 files changed, 14 insertions(+) (limited to 'rust/kernel/error.rs') diff --git a/rust/helpers.c b/rust/helpers.c index 09a4d93f9d62..89f4cd1e0df3 100644 --- a/rust/helpers.c +++ b/rust/helpers.c @@ -20,6 +20,7 @@ #include #include +#include #include __noreturn void rust_helper_BUG(void) @@ -46,6 +47,12 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r) } EXPORT_SYMBOL_GPL(rust_helper_refcount_dec_and_test); +__force void *rust_helper_ERR_PTR(long err) +{ + return ERR_PTR(err); +} +EXPORT_SYMBOL_GPL(rust_helper_ERR_PTR); + /* * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type * as the Rust `usize` type, so we can use it in contexts where Rust diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 35894fa35efe..154d0ca6e2dc 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -76,6 +76,13 @@ impl Error { pub fn to_errno(self) -> core::ffi::c_int { self.0 } + + /// Returns the error encoded as a pointer. + #[allow(dead_code)] + pub(crate) fn to_ptr(self) -> *mut T { + // SAFETY: self.0 is a valid error due to its invariant. + unsafe { bindings::ERR_PTR(self.0.into()) as *mut _ } + } } impl From for Error { -- cgit v1.2.3-59-g8ed1b From 6551a7fe0acbbc816802350414b37d9b42daccc8 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Mon, 3 Apr 2023 18:48:12 +0900 Subject: rust: error: Add Error::from_errno{_unchecked}() Add a function to create `Error` values out of a kernel error return, which safely upholds the invariant that the error code is well-formed (negative and greater than -MAX_ERRNO). If a malformed code is passed in, it will be converted to EINVAL. Lina: Imported from rust-for-linux/rust as authored by Miguel and Fox with refactoring from Wedson, renamed from_kernel_errno() to from_errno(). Co-developed-by: Fox Chen Signed-off-by: Fox Chen Co-developed-by: Wedson Almeida Filho Signed-off-by: Wedson Almeida Filho Signed-off-by: Miguel Ojeda Reviewed-by: Andreas Hindborg Reviewed-by: Gary Guo Reviewed-by: Martin Rodriguez Reboredo Signed-off-by: Asahi Lina Link: https://lore.kernel.org/r/20230224-rust-error-v3-3-03779bddc02b@asahilina.net [ Mark the new associated functions as `#[allow(dead_code)]`. ] Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'rust/kernel/error.rs') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 154d0ca6e2dc..0223d48ab43d 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -72,6 +72,38 @@ pub mod code { pub struct Error(core::ffi::c_int); 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. + #[allow(dead_code)] + pub(crate) fn from_errno(errno: core::ffi::c_int) -> Error { + if errno < -(bindings::MAX_ERRNO as i32) || errno >= 0 { + // TODO: Make it a `WARN_ONCE` once available. + crate::pr_warn!( + "attempted to create `Error` with out of range `errno`: {}", + errno + ); + return code::EINVAL; + } + + // INVARIANT: The check above ensures the type invariant + // will hold. + Error(errno) + } + + /// Creates an [`Error`] from a kernel error code. + /// + /// # Safety + /// + /// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`). + #[allow(dead_code)] + unsafe fn from_errno_unchecked(errno: core::ffi::c_int) -> Error { + // INVARIANT: The contract ensures the type invariant + // will hold. + Error(errno) + } + /// Returns the kernel error code. pub fn to_errno(self) -> core::ffi::c_int { self.0 -- cgit v1.2.3-59-g8ed1b From 086fbfa3b328901fa8b369093ba468864e20544e Mon Sep 17 00:00:00 2001 From: Wedson Almeida Filho Date: Mon, 3 Apr 2023 18:48:13 +0900 Subject: rust: error: Add to_result() helper Add a to_result() helper to convert kernel C return values to a Rust Result, mapping >=0 values to Ok(()) and negative values to Err(...), with Error::from_errno() ensuring that the errno is within range. Lina: Imported from rust-for-linux/rust, originally developed by Wedson as part of the AMBA device driver support. Signed-off-by: Wedson Almeida Filho Reviewed-by: Andreas Hindborg Reviewed-by: Gary Guo Reviewed-by: Martin Rodriguez Reboredo Signed-off-by: Asahi Lina Link: https://lore.kernel.org/r/20230224-rust-error-v3-4-03779bddc02b@asahilina.net [ Add a removal of `#[allow(dead_code)]`. ] Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'rust/kernel/error.rs') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 0223d48ab43d..7e25871063df 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -76,7 +76,6 @@ impl Error { /// /// It is a bug to pass an out-of-range `errno`. `EINVAL` would /// be returned in such a case. - #[allow(dead_code)] pub(crate) fn from_errno(errno: core::ffi::c_int) -> Error { if errno < -(bindings::MAX_ERRNO as i32) || errno >= 0 { // TODO: Make it a `WARN_ONCE` once available. @@ -180,3 +179,13 @@ impl From for Error { /// it should still be modeled as returning a `Result` rather than /// just an [`Error`]. 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. +pub fn to_result(err: core::ffi::c_int) -> Result { + if err < 0 { + Err(Error::from_errno(err)) + } else { + Ok(()) + } +} -- cgit v1.2.3-59-g8ed1b From 752417b3f0e7721f1d630f40da22d57e0dae043e Mon Sep 17 00:00:00 2001 From: Sven Van Asbroeck Date: Mon, 3 Apr 2023 18:48:14 +0900 Subject: rust: error: Add a helper to convert a C ERR_PTR to a `Result` Some kernel C API functions return a pointer which embeds an optional `errno`. Callers are supposed to check the returned pointer with `IS_ERR()` and if this returns `true`, retrieve the `errno` using `PTR_ERR()`. Create a Rust helper function to implement the Rust equivalent: transform a `*mut T` to `Result<*mut T>`. Lina: Imported from rust-for-linux/linux, with subsequent refactoring and contributions squashed in and attributed below. Renamed the function to from_err_ptr(). Co-developed-by: Boqun Feng Signed-off-by: Boqun Feng Co-developed-by: Miguel Ojeda Signed-off-by: Miguel Ojeda Co-developed-by: Fox Chen Signed-off-by: Fox Chen Co-developed-by: Gary Guo Signed-off-by: Gary Guo Signed-off-by: Sven Van Asbroeck Reviewed-by: Martin Rodriguez Reboredo Signed-off-by: Asahi Lina Link: https://lore.kernel.org/r/20230224-rust-error-v3-5-03779bddc02b@asahilina.net [ Add a removal of `#[allow(dead_code)]`. ] Signed-off-by: Miguel Ojeda --- rust/helpers.c | 12 ++++++++++++ rust/kernel/error.rs | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 61 insertions(+), 1 deletion(-) (limited to 'rust/kernel/error.rs') diff --git a/rust/helpers.c b/rust/helpers.c index 89f4cd1e0df3..04b9be46e887 100644 --- a/rust/helpers.c +++ b/rust/helpers.c @@ -53,6 +53,18 @@ __force void *rust_helper_ERR_PTR(long err) } EXPORT_SYMBOL_GPL(rust_helper_ERR_PTR); +bool rust_helper_IS_ERR(__force const void *ptr) +{ + return IS_ERR(ptr); +} +EXPORT_SYMBOL_GPL(rust_helper_IS_ERR); + +long rust_helper_PTR_ERR(__force const void *ptr) +{ + return PTR_ERR(ptr); +} +EXPORT_SYMBOL_GPL(rust_helper_PTR_ERR); + /* * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type * as the Rust `usize` type, so we can use it in contexts where Rust diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 7e25871063df..67637b874267 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -96,7 +96,6 @@ impl Error { /// # Safety /// /// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`). - #[allow(dead_code)] unsafe fn from_errno_unchecked(errno: core::ffi::c_int) -> Error { // INVARIANT: The contract ensures the type invariant // will hold. @@ -189,3 +188,52 @@ pub fn to_result(err: core::ffi::c_int) -> Result { Ok(()) } } + +/// Transform a kernel "error pointer" to a normal pointer. +/// +/// Some kernel C API functions return an "error pointer" which optionally +/// embeds an `errno`. Callers are supposed to check the returned pointer +/// for errors. This function performs the check and converts the "error pointer" +/// to a normal pointer in an idiomatic fashion. +/// +/// # Examples +/// +/// ```ignore +/// # use kernel::from_err_ptr; +/// # use kernel::bindings; +/// fn devm_platform_ioremap_resource( +/// pdev: &mut PlatformDevice, +/// index: u32, +/// ) -> Result<*mut core::ffi::c_void> { +/// // SAFETY: FFI call. +/// unsafe { +/// from_err_ptr(bindings::devm_platform_ioremap_resource( +/// pdev.to_ptr(), +/// index, +/// )) +/// } +/// } +/// ``` +// TODO: Remove `dead_code` marker once an in-kernel client is available. +#[allow(dead_code)] +pub(crate) fn from_err_ptr(ptr: *mut T) -> Result<*mut T> { + // CAST: Casting a pointer to `*const core::ffi::c_void` is always valid. + let const_ptr: *const core::ffi::c_void = ptr.cast(); + // SAFETY: The FFI function does not deref the pointer. + if unsafe { bindings::IS_ERR(const_ptr) } { + // SAFETY: The FFI function does not deref the pointer. + let err = unsafe { bindings::PTR_ERR(const_ptr) }; + // CAST: If `IS_ERR()` returns `true`, + // then `PTR_ERR()` is guaranteed to return a + // negative value greater-or-equal to `-bindings::MAX_ERRNO`, + // which always fits in an `i16`, as per the invariant above. + // And an `i16` always fits in an `i32`. So casting `err` to + // an `i32` can never overflow, and is always valid. + // + // SAFETY: `IS_ERR()` ensures `err` is a + // negative value greater-or-equal to `-bindings::MAX_ERRNO`. + #[allow(clippy::unnecessary_cast)] + return Err(unsafe { Error::from_errno_unchecked(err as core::ffi::c_int) }); + } + Ok(ptr) +} -- cgit v1.2.3-59-g8ed1b From ef4dc4cc7001e9cce8a3b556362171648be9ad92 Mon Sep 17 00:00:00 2001 From: Wedson Almeida Filho Date: Mon, 3 Apr 2023 18:48:15 +0900 Subject: rust: error: Add from_result() helper Add a helper function to easily return C result codes from a Rust function that calls functions which return a Result. Lina: Imported from rust-for-linux/rust, originally developed by Wedson as part of file_operations.rs. Added the allow() flags since there is no user in the kernel crate yet and fixed a typo in a comment. Replaced the macro with a function taking a closure, per discussion on the ML. Co-developed-by: Fox Chen Signed-off-by: Fox Chen Co-developed-by: Miguel Ojeda Signed-off-by: Miguel Ojeda Signed-off-by: Wedson Almeida Filho Reviewed-by: Martin Rodriguez Reboredo Signed-off-by: Asahi Lina Link: https://lore.kernel.org/r/20230224-rust-error-v3-6-03779bddc02b@asahilina.net Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'rust/kernel/error.rs') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 67637b874267..5f4114b30b94 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -237,3 +237,42 @@ pub(crate) fn from_err_ptr(ptr: *mut T) -> Result<*mut T> { } Ok(ptr) } + +/// Calls a closure returning a [`crate::error::Result`] and converts the result to +/// a C integer result. +/// +/// This is useful when calling Rust functions that return [`crate::error::Result`] +/// from inside `extern "C"` functions that need to return an integer error result. +/// +/// `T` should be convertible from an `i16` via `From`. +/// +/// # Examples +/// +/// ```ignore +/// # use kernel::from_result; +/// # use kernel::bindings; +/// unsafe extern "C" fn probe_callback( +/// pdev: *mut bindings::platform_device, +/// ) -> core::ffi::c_int { +/// from_result(|| { +/// let ptr = devm_alloc(pdev)?; +/// bindings::platform_set_drvdata(pdev, ptr); +/// Ok(0) +/// }) +/// } +/// ``` +// TODO: Remove `dead_code` marker once an in-kernel client is available. +#[allow(dead_code)] +pub(crate) fn from_result(f: F) -> T +where + T: From, + F: FnOnce() -> Result, +{ + match f() { + Ok(v) => v, + // NO-OVERFLOW: negative `errno`s are no smaller than `-bindings::MAX_ERRNO`, + // `-bindings::MAX_ERRNO` fits in an `i16` as per invariant above, + // therefore a negative `errno` always fits in an `i16` and will not overflow. + Err(e) => T::from(e.to_errno() as i16), + } +} -- cgit v1.2.3-59-g8ed1b