Skip to contentSkip to conversation

firmware_loader: annotate doctests as `no_run`

PATCH Superseded Danilo Krummrich 2 participants 4 messages Jul 7, 2024 – Jul 8, 2024

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/2 firmware_loader: annotate doctests as `no_run`

The doctests of Firmware are compile-time only tests, since they require a proper Device and a valid path to a (firmware) blob in order to do something sane on runtime - we can't satisfy both of those requirements.

Hence, configure the example as no_run.

Unfortunately, the kernel's Rust build system can't consider the no_run attribute yet. Hence, for the meantime, wrap the example code into a new function and never actually call it.

Fixes de6582833db0 ("rust: add firmware abstractions")
---
 rust/kernel/firmware.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
rust/kernel/firmware.rs +6 -2
index 386c8fb44785..106a928a535e 100644
@@ -26,14 +26,18 @@
 ///
 /// # Examples
 ///
-/// ```
+/// ```no_run
 /// # use kernel::{c_str, device::Device, firmware::Firmware};
 ///
+/// # fn no_run() -> Result<(), Error> {
 /// # // SAFETY: *NOT* safe, just for the example to get an `ARef<Device>` instance
 /// # let dev = unsafe { Device::from_raw(core::ptr::null_mut()) };
 ///
-/// let fw = Firmware::request(c_str!("path/to/firmware.bin"), &dev).unwrap();
+/// let fw = Firmware::request(c_str!("path/to/firmware.bin"), &dev)?;
 /// let blob = fw.data();
+///
+/// # Ok(())
+/// # }
 /// ```
 pub struct Firmware(NonNull<bindings::firmware>);
 

base-commit: 997197b58bf6e22b8c6ef88a168d8292fa9acec9

Signature · 1 line
2.45.2
#1 lore raw

PATCH 2/2 firmware_loader: fix soundness issue in `request_internal`

request_internal must be called with one of the following function
pointers: request_firmware(), firmware_request_nowarn(), firmware_request_platform() or request_firmware_direct().

The previous FwFunc alias did not guarantee this, which is unsound.

In order to fix this up, implement FwFunc as new type with a corresponding type invariant and unsafe new function.

---
 rust/kernel/firmware.rs | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)
rust/kernel/firmware.rs +26 -6
index 106a928a535e..d765ecc85d38 100644
@@ -7,11 +7,24 @@
 use crate::{bindings, device::Device, error::Error, error::Result, str::CStr};
 use core::ptr::NonNull;
 
-// One of the following: `bindings::request_firmware`, `bindings::firmware_request_nowarn`,
-// `firmware_request_platform`, `bindings::request_firmware_direct`
-type FwFunc =
+type RawFwFunc =
     unsafe extern "C" fn(*mut *const bindings::firmware, *const i8, *mut bindings::device) -> i32;
 
+/// # Invariants
+///
+/// One of the following: `bindings::request_firmware`, `bindings::firmware_request_nowarn`,
+/// `firmware_request_platform`, `bindings::request_firmware_direct`
+struct FwFunc(RawFwFunc);
+
+impl FwFunc {
+    /// # Safety
+    ///
+    /// Must be one of the functions listed in the type invariants.
+    unsafe fn from_raw(func: RawFwFunc) -> Self {
+        Self(func)
+    }
+}
+
 /// Abstraction around a C `struct firmware`.
 ///
 /// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
@@ -48,7 +61,7 @@ fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> {
 
         // SAFETY: `pfw` is a valid pointer to a NULL initialized `bindings::firmware` pointer.
         // `name` and `dev` are valid as by their type invariants.
-        let ret = unsafe { func(pfw as _, name.as_char_ptr(), dev.as_raw()) };
+        let ret = unsafe { func.0(pfw as _, name.as_char_ptr(), dev.as_raw()) };
         if ret != 0 {
             return Err(Error::from_errno(ret));
         }
@@ -60,13 +73,20 @@ fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> {
 
     /// Send a firmware request and wait for it. See also `bindings::request_firmware`.
     pub fn request(name: &CStr, dev: &Device) -> Result<Self> {
-        Self::request_internal(name, dev, bindings::request_firmware)
+        // SAFETY: `bindings::request_firmware` is valid by the safety requirement of `FwFunc`.
+        let func = unsafe { FwFunc::from_raw(bindings::request_firmware) };
+
+        Self::request_internal(name, dev, func)
     }
 
     /// Send a request for an optional firmware module. See also
     /// `bindings::firmware_request_nowarn`.
     pub fn request_nowarn(name: &CStr, dev: &Device) -> Result<Self> {
-        Self::request_internal(name, dev, bindings::firmware_request_nowarn)
+        // SAFETY: `bindings::firmware_request_nowarn` is valid by the safety requirement of
+        // `FwFunc::new`.
+        let func = unsafe { FwFunc::from_raw(bindings::firmware_request_nowarn) };
+
+        Self::request_internal(name, dev, func)
     }
 
     fn as_raw(&self) -> *mut bindings::firmware {
Signature · 1 line
2.45.2
#2 lore raw

Re: [PATCH 2/2] firmware_loader: fix soundness issue in `request_internal`

Greetings.

Quoted 33 lines · Danilo Krummrich

request_internal must be called with one of the following function
pointers: request_firmware(), firmware_request_nowarn(), firmware_request_platform() or request_firmware_direct().

The previous FwFunc alias did not guarantee this, which is unsound.

In order to fix this up, implement FwFunc as new type with a corresponding type invariant and unsafe new function.

---
 rust/kernel/firmware.rs | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)
rust/kernel/firmware.rs +4 -3
index 106a928a535e..d765ecc85d38 100644
@@ -7,11 +7,24 @@
 use crate::{bindings, device::Device, error::Error, error::Result, str::CStr};
 use core::ptr::NonNull;
 
-// One of the following: `bindings::request_firmware`, `bindings::firmware_request_nowarn`,
-// `firmware_request_platform`, `bindings::request_firmware_direct`
-type FwFunc =
+type RawFwFunc =
     unsafe extern "C" fn(*mut *const bindings::firmware, *const i8, *mut bindings::device) -> i32;
 
+/// # Invariants
+///
+/// One of the following: `bindings::request_firmware`, `bindings::firmware_request_nowarn`,

rust/kernel/firmware.rs line 25

Quoted 10 lines
rust/kernel/firmware.rs +10 -0
+/// `firmware_request_platform`, `bindings::request_firmware_direct`
+struct FwFunc(RawFwFunc);
+
+impl FwFunc {
+    /// # Safety
+    ///
+    /// Must be one of the functions listed in the type invariants.
+    unsafe fn from_raw(func: RawFwFunc) -> Self {
+        Self(func)
+    }

Why not write methods that construct each possible FwFunc?
That way the code that needs to know abut this invariant is only inside a single impl block. Something like:

impl FwFunc {
    fn request_firmware() -> Self {
        // # Safety
        // As per the Type Invariant `bindings::request_firmware` is a valid vaule.
    	FwFunc(bindings::request_firmware)
    }
}
Quoted 27 lines
rust/kernel/firmware.rs +7 -2
+}
+
 /// Abstraction around a C `struct firmware`.
 ///
 /// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
@@ -48,7 +61,7 @@ fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> {
 
         // SAFETY: `pfw` is a valid pointer to a NULL initialized `bindings::firmware` pointer.
         // `name` and `dev` are valid as by their type invariants.
-        let ret = unsafe { func(pfw as _, name.as_char_ptr(), dev.as_raw()) };
+        let ret = unsafe { func.0(pfw as _, name.as_char_ptr(), dev.as_raw()) };
         if ret != 0 {
             return Err(Error::from_errno(ret));
         }
@@ -60,13 +73,20 @@ fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> {
 
     /// Send a firmware request and wait for it. See also `bindings::request_firmware`.
     pub fn request(name: &CStr, dev: &Device) -> Result<Self> {
-        Self::request_internal(name, dev, bindings::request_firmware)
+        // SAFETY: `bindings::request_firmware` is valid by the safety requirement of `FwFunc`.
+        let func = unsafe { FwFunc::from_raw(bindings::request_firmware) };
+
+        Self::request_internal(name, dev, func)
     }
 
     /// Send a request for an optional firmware module. See also
     /// `bindings::firmware_request_nowarn`.

rust/kernel/firmware.rs fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> { · line 92

Quoted 10 lines
rust/kernel/firmware.rs +5 -1
     pub fn request_nowarn(name: &CStr, dev: &Device) -> Result<Self> {
-        Self::request_internal(name, dev, bindings::firmware_request_nowarn)
+        // SAFETY: `bindings::firmware_request_nowarn` is valid by the safety requirement of
+        // `FwFunc::new`.
+        let func = unsafe { FwFunc::from_raw(bindings::firmware_request_nowarn) };
+
+        Self::request_internal(name, dev, func)
     }
 
     fn as_raw(&self) -> *mut bindings::firmware {

Cheers,
Christian

#3 lore raw

Re: [PATCH 2/2] firmware_loader: fix soundness issue in `request_internal`

Quoted 33 lines · Christian Schrefl

Greetings.

Quoted 30 lines · Danilo Krummrich

request_internal must be called with one of the following function
pointers: request_firmware(), firmware_request_nowarn(), firmware_request_platform() or request_firmware_direct().

The previous FwFunc alias did not guarantee this, which is unsound.

In order to fix this up, implement FwFunc as new type with a corresponding type invariant and unsafe new function.

---
 rust/kernel/firmware.rs | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)
rust/kernel/firmware.rs +1 -3
index 106a928a535e..d765ecc85d38 100644
@@ -7,11 +7,24 @@
 use crate::{bindings, device::Device, error::Error, error::Result, str::CStr};
 use core::ptr::NonNull;
 
-// One of the following: `bindings::request_firmware`, `bindings::firmware_request_nowarn`,
-// `firmware_request_platform`, `bindings::request_firmware_direct`
-type FwFunc =
+type RawFwFunc =
     unsafe extern "C" fn(*mut *const bindings::firmware, *const i8, *mut bindings::device) -> i32;
 
Quoted 14 lines

rust/kernel/firmware.rs line 25

Quoted 13 lines
rust/kernel/firmware.rs +13 -0
+/// # Invariants
+///
+/// One of the following: `bindings::request_firmware`, `bindings::firmware_request_nowarn`,
+/// `firmware_request_platform`, `bindings::request_firmware_direct`
+struct FwFunc(RawFwFunc);
+
+impl FwFunc {
+    /// # Safety
+    ///
+    /// Must be one of the functions listed in the type invariants.
+    unsafe fn from_raw(func: RawFwFunc) -> Self {
+        Self(func)
+    }

Why not write methods that construct each possible FwFunc?

Thanks, this is a good idea indeed, will send a v2.

Quoted 51 lines

That way the code that needs to know abut this invariant is only inside a single impl block. Something like:

impl FwFunc {
    fn request_firmware() -> Self {
        // # Safety
        // As per the Type Invariant `bindings::request_firmware` is a valid vaule.
    	FwFunc(bindings::request_firmware)
    }
}
Quoted 27 lines
rust/kernel/firmware.rs +7 -2
+}
+
 /// Abstraction around a C `struct firmware`.
 ///
 /// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
@@ -48,7 +61,7 @@ fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> {
 
         // SAFETY: `pfw` is a valid pointer to a NULL initialized `bindings::firmware` pointer.
         // `name` and `dev` are valid as by their type invariants.
-        let ret = unsafe { func(pfw as _, name.as_char_ptr(), dev.as_raw()) };
+        let ret = unsafe { func.0(pfw as _, name.as_char_ptr(), dev.as_raw()) };
         if ret != 0 {
             return Err(Error::from_errno(ret));
         }
@@ -60,13 +73,20 @@ fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> {
 
     /// Send a firmware request and wait for it. See also `bindings::request_firmware`.
     pub fn request(name: &CStr, dev: &Device) -> Result<Self> {
-        Self::request_internal(name, dev, bindings::request_firmware)
+        // SAFETY: `bindings::request_firmware` is valid by the safety requirement of `FwFunc`.
+        let func = unsafe { FwFunc::from_raw(bindings::request_firmware) };
+
+        Self::request_internal(name, dev, func)
     }
 
     /// Send a request for an optional firmware module. See also
     /// `bindings::firmware_request_nowarn`.

rust/kernel/firmware.rs fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> { · line 92

Quoted 10 lines
rust/kernel/firmware.rs +5 -1
     pub fn request_nowarn(name: &CStr, dev: &Device) -> Result<Self> {
-        Self::request_internal(name, dev, bindings::firmware_request_nowarn)
+        // SAFETY: `bindings::firmware_request_nowarn` is valid by the safety requirement of
+        // `FwFunc::new`.
+        let func = unsafe { FwFunc::from_raw(bindings::firmware_request_nowarn) };
+
+        Self::request_internal(name, dev, func)
     }
 
     fn as_raw(&self) -> *mut bindings::firmware {

Cheers,
Christian