rust/kernel: introduce zero-cost from_kernel_int_result_uint()

In a previous PR, the type invariant for `Error` is enforced using
a runtime check. This is non-zero cost.

However we may decide to trust the return value of certain kernel C
functions. In such cases, no runtime check is required to enforce the
type invariant. So we can return to zero-cost.

This patch removes invariant checks from kernel C functions that
return a positive value on success, or a non-zero errno on failure.

Signed-off-by: Sven Van Asbroeck <[email protected]>

Author: Sven Van Asbroeck

rust/kernel/error.rs

@@ -295,4 +295,38 @@ pub(crate) unsafe fn from_kernel_int_result(retval: c_types::c_int) -> Result {
     }
     Ok(())
 }
+
+/// Transform a kernel integer result to a [`Result<c_types::c_uint>`].
+///
+/// Some kernel C API functions return a result in the form of an integer:
+/// zero or positive if ok, a negative errno on error. This function converts
+/// such a return value into an idiomatic [`Result<c_types::c_uint>`].
+///
+/// Use this function when the C function returns a useful, positive value
+/// on success, or negative on error. If the C function only returns 0 on
+/// success, use [`from_kernel_int_result`] instead.
+///
+/// # Safety
+///
+/// `retval` must be non-negative or a valid negative errno (i.e. `retval` must
+/// be in `[-MAX_ERRNO..]`).
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// let fd = unsafe { bindings::get_unused_fd_flags(flags) };
+/// // SAFETY: `bindings::get_unused_fd_flags()` returns a non-negative
+/// // `fd` on success, or a valid negative `errno` on error.
+/// let fd = unsafe { from_kernel_int_result_uint(fd)? };
+/// ```
+pub(crate) unsafe fn from_kernel_int_result_uint(
+    retval: c_types::c_int,
+) -> Result<c_types::c_uint> {
+    if retval < 0 {
+        // SAFETY: This condition together with the function precondition
+        // guarantee that `errno` is a valid negative `errno`.
+        return Err(unsafe { Error::from_kernel_errno_unchecked(retval) });
+    }
+    // CAST: a non-negative `c_types::c_int` always fits in a `c_types::c_uint`.
+    Ok(retval as c_types::c_uint)
 }

rust/kernel/file.rs

@@ -5,7 +5,11 @@
 //! C headers: [`include/linux/fs.h`](../../../../include/linux/fs.h) and
 //! [`include/linux/file.h`](../../../../include/linux/file.h)
 
-use crate::{bindings, error::Error, Result};
+use crate::{
+    bindings,
+    error::{from_kernel_int_result_uint, Error},
+    Result,
+};
 use core::{mem::ManuallyDrop, ops::Deref};
 
 /// Wraps the kernel's `struct file`.
@@ -96,9 +100,9 @@ impl FileDescriptorReservation {
     /// Creates a new file descriptor reservation.
     pub fn new(flags: u32) -> Result<Self> {
         let fd = unsafe { bindings::get_unused_fd_flags(flags) };
-        if fd < 0 {
-            return Err(Error::from_kernel_errno(fd));
-        }
+        // SAFETY: `bindings::get_unused_fd_flags()` returns a non-negative
+        // `fd` on success, or a valid negative `errno` on error.
+        let fd = unsafe { from_kernel_int_result_uint(fd)? };
         Ok(Self { fd: fd as _ })
     }