firmware_loader: annotate doctests as `no_run`
Subsystems (2)
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.
--- rust/kernel/firmware.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-)
rust/kernel/firmware.rs +6 -2
@@ -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
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
@@ -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 (pfwas _ , name.as_char_ptr (), dev.as_raw ()) }; +let ret =unsafe { func.0 (pfwas _ , 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
Re: [PATCH 2/2] firmware_loader: fix soundness issue in `request_internal`
Greetings.
Quoted 33 lines · Danilo Krummrich
request_internalmust be called with one of the following function
pointers:request_firmware(),firmware_request_nowarn(),firmware_request_platform()orrequest_firmware_direct().The previous
FwFuncalias did not guarantee this, which is unsound.In order to fix this up, implement
FwFuncas new type with a corresponding type invariant and unsafenewfunction.Reported-by Gary Guo <[email protected]>Signed-off-by Danilo Krummrich <[email protected]>--- rust/kernel/firmware.rs | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-)rust/kernel/firmware.rs +4
-3@@ -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 (pfwas _ , name.as_char_ptr (), dev.as_raw ()) }; +let ret =unsafe { func.0 (pfwas _ , 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
-1pub 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
Re: [PATCH 2/2] firmware_loader: fix soundness issue in `request_internal`
Quoted 33 lines · Christian Schrefl
Greetings.
Quoted 30 lines · Danilo Krummrich
request_internalmust be called with one of the following function
pointers:request_firmware(),firmware_request_nowarn(),firmware_request_platform()orrequest_firmware_direct().The previous
FwFuncalias did not guarantee this, which is unsound.In order to fix this up, implement
FwFuncas new type with a corresponding type invariant and unsafenewfunction.Reported-by Gary Guo <[email protected]>Signed-off-by Danilo Krummrich <[email protected]>--- rust/kernel/firmware.rs | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-)rust/kernel/firmware.rs +1
-3@@ -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 (pfwas _ , name.as_char_ptr (), dev.as_raw ()) }; +let ret =unsafe { func.0 (pfwas _ , 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
-1pub 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