rust/kernel: introduce zero-cost from_kernel_int_result()

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 0 on success, or a non-zero errno on failure.

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

Author: Sven Van Asbroeck

rust/kernel/chrdev.rs

@@ -15,7 +15,7 @@ use core::pin::Pin;
 
 use crate::bindings;
 use crate::c_types;
-use crate::error::{Error, Result};
+use crate::error::{from_kernel_int_result, Error, Result};
 use crate::file_operations;
 use crate::str::CStr;
 
@@ -60,10 +60,9 @@ impl Cdev {
         // - [`(*self.0).owner`] will live at least as long as the
         //   module, which is an implicit requirement.
         let rc = unsafe { bindings::cdev_add(self.0, dev, count) };
-        if rc != 0 {
-            return Err(Error::from_kernel_errno(rc));
-        }
-        Ok(())
+        // SAFETY: `bindings::cdev_add()` returns zero on success,
+        // or a valid negative `errno` on error.
+        unsafe { from_kernel_int_result(rc) }
     }
 }
 
@@ -149,8 +148,10 @@ impl<const N: usize> Registration<{ N }> {
                     this.name.as_char_ptr(),
                 )
             };
-            if res != 0 {
-                return Err(Error::from_kernel_errno(res));
+            // SAFETY: `bindings::alloc_chrdev_region()` returns zero on
+            // success, or a valid negative `errno` on error.
+            unsafe {
+                from_kernel_int_result(res)?;
             }
             const NONE: Option<Cdev> = None;
             this.inner = Some(RegistrationInner {

rust/kernel/error.rs

@@ -263,3 +263,36 @@ pub(crate) fn from_kernel_err_ptr<T>(ptr: *mut T) -> Result<*mut T> {
     }
     Ok(ptr)
 }
+
+/// Transform a kernel integer result to a [`Result`].
+///
+/// Some kernel C API functions return a result in the form of an integer:
+/// zero if ok, a negative errno on error. This function converts such a
+/// return value into an idiomatic [`Result`].
+///
+/// Use this function when the C function only returns 0 on success or
+/// negative on error. If the C function returns a useful value on the
+/// happy path, use [`from_kernel_int_result_uint`] 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 ret = unsafe { bindings::misc_register(&mut this.mdev) };
+/// // SAFETY: `misc_register` returns zero on success, or a valid
+/// // negative errno on failure.
+/// unsafe { from_kernel_int_result(ret)?; }
+/// ```
+pub(crate) unsafe fn from_kernel_int_result(retval: c_types::c_int) -> Result {
+    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) });
+    }
+    Ok(())
+}
+}

rust/kernel/miscdev.rs

@@ -7,7 +7,7 @@
 //! Reference: <https://www.kernel.org/doc/html/latest/driver-api/misc_devices.html>
 
 use crate::bindings;
-use crate::error::{Error, Result};
+use crate::error::{from_kernel_int_result, Error, Result};
 use crate::file_operations::{FileOpenAdapter, FileOpener, FileOperationsVtable};
 use crate::str::CStr;
 use alloc::boxed::Box;
@@ -73,8 +73,10 @@ impl<T: Sync> Registration<T> {
         this.mdev.minor = minor.unwrap_or(bindings::MISC_DYNAMIC_MINOR as i32);
 
         let ret = unsafe { bindings::misc_register(&mut this.mdev) };
-        if ret < 0 {
-            return Err(Error::from_kernel_errno(ret));
+        // SAFETY: `bindings::alloc_chrdev_region()` returns zero on
+        // success, or a valid negative `errno` on error.
+        unsafe {
+            from_kernel_int_result(ret)?;
         }
         this.registered = true;
         Ok(())

rust/kernel/pages.rs

@@ -5,8 +5,8 @@
 //! TODO: This module is a work in progress.
 
 use crate::{
-    bindings, c_types, io_buffer::IoBufferReader, user_ptr::UserSlicePtrReader, Error, Result,
-    PAGE_SIZE,
+    bindings, c_types, error::from_kernel_int_result, io_buffer::IoBufferReader,
+    user_ptr::UserSlicePtrReader, Error, Result, PAGE_SIZE,
 };
 use core::{marker::PhantomData, ptr};
 
@@ -65,11 +65,9 @@ impl<const ORDER: u32> Pages<ORDER> {
         // SAFETY: We check above that the allocation is of order 0. The range of `address` is
         // already checked by `vm_insert_page`.
         let ret = unsafe { bindings::vm_insert_page(vma, address as _, self.pages) };
-        if ret != 0 {
-            Err(Error::from_kernel_errno(ret))
-        } else {
-            Ok(())
-        }
+        // SAFETY: `bindings::vm_insert_page()` returns zero on success,
+        // or a valid negative `errno` on error.
+        unsafe { from_kernel_int_result(ret) }
     }
 
     /// Copies data from the given [`UserSlicePtrReader`] into the pages.

rust/kernel/platdev.rs

@@ -8,7 +8,7 @@
 
 use crate::{
     bindings, c_types,
-    error::{Error, Result},
+    error::{from_kernel_int_result, Error, Result},
     from_kernel_result,
     of::OfMatchTable,
     str::CStr,
@@ -83,8 +83,10 @@ impl Registration {
         //       `bindings::platform_driver_unregister()`, or
         //      - null.
         let ret = unsafe { bindings::__platform_driver_register(&mut this.pdrv, module.0) };
-        if ret < 0 {
-            return Err(Error::from_kernel_errno(ret));
+        // SAFETY: `bindings::__platform_driver_register()` returns zero on
+        // success, or a valid negative `errno` on error.
+        unsafe {
+            from_kernel_int_result(ret)?;
         }
         this.registered = true;
         Ok(())

rust/kernel/random.rs

@@ -6,16 +6,21 @@
 
 use core::convert::TryInto;
 
-use crate::{bindings, c_types, error};
+use crate::{
+    bindings, c_types,
+    error::{self, from_kernel_int_result},
+};
 
 /// Fills a byte slice with random bytes generated from the kernel's CSPRNG.
 ///
 /// Ensures that the CSPRNG has been seeded before generating any random bytes,
 /// and will block until it is ready.
 pub fn getrandom(dest: &mut [u8]) -> error::Result {
     let res = unsafe { bindings::wait_for_random_bytes() };
-    if res != 0 {
-        return Err(error::Error::from_kernel_errno(res));
+    // SAFETY: `bindings::wait_for_random_bytes()` returns zero on success,
+    // or a valid negative `errno` on error.
+    unsafe {
+        from_kernel_int_result(res)?;
     }
 
     unsafe {