Rust abstractions for Device & Firmware
Subsystems (3)
v4 cover Rust abstractions for Device & Firmware
Hi,
as agreed in [1] this is the separate series for the device and firmware abstractions to unblock the inclusion of Fujita's PHY driver.
Originally, those patches were part of the patch series [2][3].
Changes in v4
=============
- add invariant of unmodified backing buffer to Firmware (Boqun)
Changes in v3
=============
- fix safety comments for Send and Sync for Device (Boqun)
- add corresponding invariant and safety requirement for Device::from_raw (Boqun)
- drop Firmware::request_platform and Firmware::request_direct (Greg)
- fix missing Kconfig entry for Firmware (Greg)
- fix doctest compilation for Firmware
Changes in v2
=============
- use the 'srctree/' notation
- expand the existing documentation and make it more unambiguous
- use NonNull in Firmware
- generalize the Firmware request functions
- add missing safety comments to Firmware
[1] https://lore.kernel.org/rust-for-linux/2024060745-palatable-dragging-32d1@gregkh/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/
[3] https://lore.kernel.org/rust-for-linux/[email protected]/
Danilo Krummrich (2):
rust: add abstraction for struct device
rust: add firmware abstractions
drivers/base/firmware_loader/Kconfig | 7 ++ rust/bindings/bindings_helper.h | 1 + rust/helpers.c | 1 + rust/kernel/device.rs | 102 +++++++++++++++++++++++++++ rust/kernel/firmware.rs | 101 ++++++++++++++++++++++++++ rust/kernel/lib.rs | 3 + 6 files changed, 215 insertions(+) create mode 100644 rust/kernel/device.rs create mode 100644 rust/kernel/firmware.rs
base-commit: 1613e604df0cd359cf2a7fbd9be7a0bcfacfabd0
Signature · 1 line
2.45.1
PATCH v4 1/2 rust: add abstraction for struct device
Add an (always) reference-counted abstraction for a generic C struct device. This abstraction encapsulates existing struct device instances and manages its reference count.
Subsystems may use this abstraction as a base to abstract subsystem specific device instances based on a generic struct device, such as struct pci_dev.
--- rust/helpers.c | 1 + rust/kernel/device.rs | 102 ++++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 3 files changed, 104 insertions(+) create mode 100644 rust/kernel/device.rs
rust/helpers.c +1 -0
@@ -23,6 +23,7 @@#include <kunit/test-bug.h> #include <linux/bug.h> #include <linux/build_bug.h> +#include <linux/device.h> #include <linux/err.h> #include <linux/errname.h> #include <linux/mutex.h>
rust/kernel/device.rs new file +102 -0
102 lines not on this page · raw message
rust/kernel/lib.rs +1 -0
@@ -28,6 +28,7 @@pub mod alloc;mod build_assert; +pub mod device;pub mod error;pub mod init;pub mod ioctl;
Signature · 1 line
2.45.1
Re: [PATCH v4 1/2] rust: add abstraction for struct device
Quoted 59 lines · Danilo Krummrich
Add an (always) reference-counted abstraction for a generic C
struct device. This abstraction encapsulates existingstruct deviceinstances and manages its reference count.Subsystems may use this abstraction as a base to abstract subsystem specific device instances based on a generic
struct device, such asstruct pci_dev.Co-developed-by Wedson Almeida Filho <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>Signed-off-by Danilo Krummrich <[email protected]>--- rust/helpers.c | 1 + rust/kernel/device.rs | 102 ++++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 3 files changed, 104 insertions(+) create mode 100644 rust/kernel/device.rsrust/helpers.c +1
-0@@ -23,6 +23,7 @@#include <kunit/test-bug.h> #include <linux/bug.h> #include <linux/build_bug.h> +#include <linux/device.h> #include <linux/err.h> #include <linux/errname.h> #include <linux/mutex.h> rust/kernel/device.rs new file +23
-0@@ -0,0 +1,102 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Generic devices that are part of the kernel's driver model. +//! +//! C header: [`include/linux/device.h`](srctree/include/linux/device.h) + +use crate ::{ + bindings, + types::{ARef ,Opaque }, +}; +use core::ptr; + +/// A reference-counted device. +/// +/// This structure represents the Rust abstraction for a C `struct device`. This implementation +/// abstracts the usage of an already existing C `struct device` within Rust code that we get +/// passed from the C side. +/// +/// An instance of this abstraction can be obtained temporarily or permanent. +/// +/// A temporary one is bound to the lifetime of the C `struct device` pointer used for creation. +/// A permanent instance is always reference-counted and hence not restricted by any lifetime +/// boundaries.
rust/kernel/device.rs line 33
Quoted 10 lines
rust/kernel/device.rs new file +10
-0+/// +/// For subsystems it is recommended to create a permanent instance to wrap into a subsystem +/// specific device structure (e.g. `pci::Device`). This is useful for passing it to drivers in +/// `T::probe()`, such that a driver can store the `ARef<Device>` (equivalent to storing a +/// `struct device` pointer in a C driver) for arbitrary purposes, e.g. allocating DMA coherent +/// memory. +/// +/// # Invariants +/// +/// The pointer stored in `Self` is non-null and valid for the lifetime of the `ARef` instance. In
There is no pointer stored in Self directly. I think you can just remove the first sentence.
The second sentence can also be improved, see Task in rust/kernel/task.rs:42.
Quoted 18 lines
rust/kernel/device.rs new file +18
-0+/// particular, the `ARef` instance owns an increment on the underlying object’s reference count. +/// +/// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be +/// dropped from any thread. +#[repr(transparent)] +pub struct Device (Opaque <bindings::device >); + +impl Device { +/// Creates a new reference-counted abstraction instance of an existing `struct device` pointer. +/// +/// # Safety +/// +/// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count, +/// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to +/// can't drop to zero, for the duration of this function call. +/// +/// It must also be ensured that `bindings::device::release` can be called from any thread. +/// While not officially documented, this should be the case for any `struct device`.
rust/kernel/device.rs line 61
Quoted 10 lines
rust/kernel/device.rs new file +10
-0+pub unsafe fn from_raw (ptr: *mut bindings::device ) ->ARef <Self > { +// SAFETY: By the safety requirements, ptr is valid. +// Initially increase the reference count by one to compensate for the final decrement once +// this newly created `ARef<Device>` instance is dropped. +unsafe { bindings::get_device (ptr) }; + +// CAST: `Self` is a `repr(transparent)` wrapper around `bindings::device`. +let ptr = ptr.cast ::<Self >(); + +// SAFETY: By the safety requirements, ptr is valid.
That is not the only requirement on from_raw, you also need to own a refcount (which you do) on ptr.
---
Cheers,
Benno
Quoted 56 lines
rust/kernel/device.rs new file +41
-0+unsafe {ARef ::from_raw (ptr::NonNull ::new_unchecked (ptr)) } + } + +/// Obtain the raw `struct device *`. +pub (crate )fn as_raw (&self) -> *mut bindings::device { + self.0 .get () + } + +/// Convert a raw C `struct device` pointer to a `&'a Device`. +/// +/// # Safety +/// +/// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count, +/// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to +/// can't drop to zero, for the duration of this function call and the entire duration when the +/// returned reference exists. +pub unsafe fn as_ref <'a>(ptr: *mut bindings::device ) -> &'aSelf { +// SAFETY: Guaranteed by the safety requirements of the function. +unsafe { &*ptr.cast () } + } +} + +// SAFETY: Instances of `Device` are always reference-counted. +unsafe impl crate ::types::AlwaysRefCounted for Device { +fn inc_ref (&self) { +// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero. +unsafe { bindings::get_device (self.as_raw ()) }; + } + +unsafe fn dec_ref (obj: ptr::NonNull <Self >) { +// SAFETY: The safety requirements guarantee that the refcount is non-zero. +unsafe { bindings::put_device (obj.cast ().as_ptr ()) } + } +} + +// SAFETY: As by the type invariant `Device` can be sent to any thread. +unsafe impl Send for Device {} + +// SAFETY: `Device` can be shared among threads because all immutable methods are protected by the +// synchronization in `struct device`. +unsafe impl Sync for Device {}rust/kernel/lib.rs +1
-1@@ -28,6 +28,7 @@pub mod alloc;mod build_assert; +pub mod device;pub mod error;pub mod init;pub mod ioctl; --2.45.1
Re: [PATCH v4 1/2] rust: add abstraction for struct device
In reply to Danilo KrummrichQuoted 11 lines · On Tue, 18 Jun 2024 17:48:34 +0200 Danilo Krummrich <[email protected]> wrote:
Add an (always) reference-counted abstraction for a generic C
struct device. This abstraction encapsulates existingstruct deviceinstances and manages its reference count.Subsystems may use this abstraction as a base to abstract subsystem specific device instances based on a generic
struct device, such asstruct pci_dev.Co-developed-by Wedson Almeida Filho <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>Signed-off-by Danilo Krummrich <[email protected]>
Quoted 6 lines
--- rust/helpers.c | 1 + rust/kernel/device.rs | 102 ++++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 3 files changed, 104 insertions(+) create mode 100644 rust/kernel/device.rs
PATCH v4 2/2 rust: add firmware abstractions
In reply to Danilo KrummrichAdd an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware's size and backing buffer.
The firmware is released once the abstraction instance is dropped.
--- drivers/base/firmware_loader/Kconfig | 7 ++ rust/bindings/bindings_helper.h | 1 + rust/kernel/firmware.rs | 101 +++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 111 insertions(+) create mode 100644 rust/kernel/firmware.rs
drivers/base/firmware_loader/Kconfig +7 -0
@@ -37,6 +37,13 @@ config FW_LOADER_DEBUG SHA256 checksums to the kernel log for each firmware file that is loaded. +config RUST_FW_LOADER_ABSTRACTIONS + bool "Rust Firmware Loader abstractions" + depends on RUST + depends on FW_LOADER=y + help + This enables the Rust abstractions for the firmware loader API. + if FW_LOADER config FW_LOADER_PAGED_BUF
rust/bindings/bindings_helper.h +1 -0
@@ -9,6 +9,7 @@#include <kunit/test.h> #include <linux/errname.h> #include <linux/ethtool.h> +#include <linux/firmware.h> #include <linux/jiffies.h> #include <linux/mdio.h> #include <linux/phy.h>
rust/kernel/firmware.rs new file +101 -0
101 lines not on this page · raw message
rust/kernel/lib.rs +2 -0
@@ -30,6 +30,8 @@mod build_assert;pub mod device;pub mod error; +#[cfg( CONFIG_RUST_FW_LOADER_ABSTRACTIONS )] +pub mod firmware;pub mod init;pub mod ioctl;#[cfg( CONFIG_KUNIT )]
Signature · 1 line
2.45.1
Re: [PATCH v4 2/2] rust: add firmware abstractions
Quoted 7 lines · Danilo Krummrich
Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware's size and backing buffer.
The firmware is released once the abstraction instance is dropped.
Signed-off-by Danilo Krummrich <[email protected]>
Thanks!
Regards,
Boqun
Quoted 161 lines
--- drivers/base/firmware_loader/Kconfig | 7 ++ rust/bindings/bindings_helper.h | 1 + rust/kernel/firmware.rs | 101 +++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 111 insertions(+) create mode 100644 rust/kernel/firmware.rsdrivers/base/firmware_loader/Kconfig +7
-0@@ -37,6 +37,13 @@ config FW_LOADER_DEBUG SHA256 checksums to the kernel log for each firmware file that is loaded. +config RUST_FW_LOADER_ABSTRACTIONS + bool "Rust Firmware Loader abstractions" + depends on RUST + depends on FW_LOADER=y + help + This enables the Rust abstractions for the firmware loader API. + if FW_LOADER config FW_LOADER_PAGED_BUFrust/bindings/bindings_helper.h +1
-0@@ -9,6 +9,7 @@#include <kunit/test.h> #include <linux/errname.h> #include <linux/ethtool.h> +#include <linux/firmware.h> #include <linux/jiffies.h> #include <linux/mdio.h> #include <linux/phy.h> rust/kernel/firmware.rs new file +101
-0@@ -0,0 +1,101 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Firmware abstraction +//! +//! C header: [`include/linux/firmware.h`](srctree/include/linux/firmware.h") + +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 = +unsafe extern "C" fn (*mut *const bindings::firmware , *const i8 , *mut bindings::device ) ->i32 ; + +/// Abstraction around a C `struct firmware`. +/// +/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// `&[u8]`. The firmware is released once [`Firmware`] is dropped. +/// +/// # Invariants +/// +/// The pointer is valid, and has ownership over the instance of `struct firmware`. +/// +/// Once requested, the `Firmware` backing buffer is not modified until it is freed when `Firmware` +/// is dropped. +/// +/// # Examples +/// +/// ``` +/// # use kernel::{c_str, device::Device, firmware::Firmware}; +/// +/// # // 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 blob = fw.data(); +/// ``` +pub struct Firmware (NonNull <bindings::firmware >); + +impl Firmware { +fn request_internal (name: &CStr , dev: &Device , func:FwFunc ) ->Result <Self > { +let mut fw: *mut bindings::firmware = core::ptr::null_mut (); +let pfw: *mut *mut bindings::firmware = &mut fw; + +// 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 ()) }; +if ret !=0 { +return Err (Error ::from_errno (ret)); + } + +// SAFETY: `func` not bailing out with a non-zero error code, guarantees that `fw` is a +// valid pointer to `bindings::firmware`. +Ok (Firmware (unsafe {NonNull ::new_unchecked (fw) })) + } + +/// 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) + } + +/// 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) + } + +fn as_raw (&self) -> *mut bindings::firmware { + self.0 .as_ptr () + } + +/// Returns the size of the requested firmware in bytes. +pub fn size (&self) ->usize { +// SAFETY: Safe by the type invariant. +unsafe { (*self.as_raw ()).size } + } + +/// Returns the requested firmware as `&[u8]`. +pub fn data (&self) -> &[u8 ] { +// SAFETY: Safe by the type invariant. Additionally, `bindings::firmware` guarantees, if +// successfully requested, that `bindings::firmware::data` has a size of +// `bindings::firmware::size` bytes. +unsafe { core::slice::from_raw_parts ((*self.as_raw ()).data, self.size ()) } + } +} + +impl Drop for Firmware { +fn drop (&mut self) { +// SAFETY: Safe by the type invariant. +unsafe { bindings::release_firmware (self.as_raw ()) }; + } +} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, which is safe to be used from +// any thread. +unsafe impl Send for Firmware {} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references to which are safe to +// be used from any thread. +unsafe impl Sync for Firmware {}rust/kernel/lib.rs +2
-0@@ -30,6 +30,8 @@mod build_assert;pub mod device;pub mod error; +#[cfg( CONFIG_RUST_FW_LOADER_ABSTRACTIONS )] +pub mod firmware;pub mod init;pub mod ioctl;#[cfg( CONFIG_KUNIT )] Signature · 1 line
2.45.1
Re: [PATCH v4 2/2] rust: add firmware abstractions
In reply to Danilo KrummrichQuoted 67 lines · Danilo Krummrich
Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware's size and backing buffer.
The firmware is released once the abstraction instance is dropped.
Signed-off-by Danilo Krummrich <[email protected]>--- drivers/base/firmware_loader/Kconfig | 7 ++ rust/bindings/bindings_helper.h | 1 + rust/kernel/firmware.rs | 101 +++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 111 insertions(+) create mode 100644 rust/kernel/firmware.rsdrivers/base/firmware_loader/Kconfig +7
-0@@ -37,6 +37,13 @@ config FW_LOADER_DEBUG SHA256 checksums to the kernel log for each firmware file that is loaded. +config RUST_FW_LOADER_ABSTRACTIONS + bool "Rust Firmware Loader abstractions" + depends on RUST + depends on FW_LOADER=y + help + This enables the Rust abstractions for the firmware loader API. + if FW_LOADER config FW_LOADER_PAGED_BUFrust/bindings/bindings_helper.h +1
-0@@ -9,6 +9,7 @@#include <kunit/test.h> #include <linux/errname.h> #include <linux/ethtool.h> +#include <linux/firmware.h> #include <linux/jiffies.h> #include <linux/mdio.h> #include <linux/phy.h> rust/kernel/firmware.rs new file +16
-0@@ -0,0 +1,101 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Firmware abstraction +//! +//! C header: [`include/linux/firmware.h`](srctree/include/linux/firmware.h") + +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 = +unsafe extern "C" fn (*mut *const bindings::firmware , *const i8 , *mut bindings::device ) ->i32 ; + +/// Abstraction around a C `struct firmware`. +///
rust/kernel/firmware.rs line 26
Quoted 10 lines
rust/kernel/firmware.rs new file +10
-0+/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// `&[u8]`. The firmware is released once [`Firmware`] is dropped. +/// +/// # Invariants +/// +/// The pointer is valid, and has ownership over the instance of `struct firmware`. +/// +/// Once requested, the `Firmware` backing buffer is not modified until it is freed when `Firmware` +/// is dropped.
This can simply be "The firmware's backing buffer is not modified." Since I interpret "Once requested" as "Once created" and you are allowed to break invariants as long as nobody can observe that.
Quoted 45 lines
rust/kernel/firmware.rs new file +45
-0+/// +/// # Examples +/// +/// ``` +/// # use kernel::{c_str, device::Device, firmware::Firmware}; +/// +/// # // 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 blob = fw.data(); +/// ``` +pub struct Firmware (NonNull <bindings::firmware >); + +impl Firmware { +fn request_internal (name: &CStr , dev: &Device , func:FwFunc ) ->Result <Self > { +let mut fw: *mut bindings::firmware = core::ptr::null_mut (); +let pfw: *mut *mut bindings::firmware = &mut fw; + +// 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 ()) }; +if ret !=0 { +return Err (Error ::from_errno (ret)); + } + +// SAFETY: `func` not bailing out with a non-zero error code, guarantees that `fw` is a +// valid pointer to `bindings::firmware`. +Ok (Firmware (unsafe {NonNull ::new_unchecked (fw) })) + } + +/// 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) + } + +/// 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) + } + +fn as_raw (&self) -> *mut bindings::firmware { + self.0 .as_ptr () + }
rust/kernel/firmware.rs line 81
Quoted 10 lines
rust/kernel/firmware.rs new file +10
-0+ +/// Returns the size of the requested firmware in bytes. +pub fn size (&self) ->usize { +// SAFETY: Safe by the type invariant. +unsafe { (*self.as_raw ()).size } + } + +/// Returns the requested firmware as `&[u8]`. +pub fn data (&self) -> &[u8 ] { +// SAFETY: Safe by the type invariant. Additionally, `bindings::firmware` guarantees, if
I would not write "Safe by ...", since it is important to know what is guaranteed by what. Instead I would write "self.as_raw() is valid by the type invariant.".
rust/kernel/firmware.rs line 90
Quoted 9 lines
rust/kernel/firmware.rs new file +9
-0+// successfully requested, that `bindings::firmware::data` has a size of +// `bindings::firmware::size` bytes. +unsafe { core::slice::from_raw_parts ((*self.as_raw ()).data, self.size ()) } + } +} + +impl Drop for Firmware { +fn drop (&mut self) { +// SAFETY: Safe by the type invariant.
Ditto.
---
Cheers,
Benno
Quoted 27 lines
rust/kernel/firmware.rs new file +11
-0+unsafe { bindings::release_firmware (self.as_raw ()) }; + } +} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, which is safe to be used from +// any thread. +unsafe impl Send for Firmware {} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references to which are safe to +// be used from any thread. +unsafe impl Sync for Firmware {}rust/kernel/lib.rs +2
-1@@ -30,6 +30,8 @@mod build_assert;pub mod device;pub mod error; +#[cfg( CONFIG_RUST_FW_LOADER_ABSTRACTIONS )] +pub mod firmware;pub mod init;pub mod ioctl;#[cfg( CONFIG_KUNIT )] --2.45.1
Re: [PATCH v4 2/2] rust: add firmware abstractions
Greg,
Benno's comments provide some nice hints to further improve the safety comments. Since I was notified that those patches hit your tree already, how do you want to proceed?
- Danilo
Quoted 187 lines · Benno Lossin
Quoted 67 lines · Danilo Krummrich
Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware's size and backing buffer.
The firmware is released once the abstraction instance is dropped.
Signed-off-by Danilo Krummrich <[email protected]>--- drivers/base/firmware_loader/Kconfig | 7 ++ rust/bindings/bindings_helper.h | 1 + rust/kernel/firmware.rs | 101 +++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 111 insertions(+) create mode 100644 rust/kernel/firmware.rsdrivers/base/firmware_loader/Kconfig +7
-0@@ -37,6 +37,13 @@ config FW_LOADER_DEBUG SHA256 checksums to the kernel log for each firmware file that is loaded. +config RUST_FW_LOADER_ABSTRACTIONS + bool "Rust Firmware Loader abstractions" + depends on RUST + depends on FW_LOADER=y + help + This enables the Rust abstractions for the firmware loader API. + if FW_LOADER config FW_LOADER_PAGED_BUFrust/bindings/bindings_helper.h +1
-0@@ -9,6 +9,7 @@#include <kunit/test.h> #include <linux/errname.h> #include <linux/ethtool.h> +#include <linux/firmware.h> #include <linux/jiffies.h> #include <linux/mdio.h> #include <linux/phy.h> rust/kernel/firmware.rs new file +16
-0@@ -0,0 +1,101 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Firmware abstraction +//! +//! C header: [`include/linux/firmware.h`](srctree/include/linux/firmware.h") + +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 = +unsafe extern "C" fn (*mut *const bindings::firmware , *const i8 , *mut bindings::device ) ->i32 ; + +/// Abstraction around a C `struct firmware`. +/// rust/kernel/firmware.rs line 26
Quoted 10 lines
rust/kernel/firmware.rs new file +10
-0+/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// `&[u8]`. The firmware is released once [`Firmware`] is dropped. +/// +/// # Invariants +/// +/// The pointer is valid, and has ownership over the instance of `struct firmware`. +/// +/// Once requested, the `Firmware` backing buffer is not modified until it is freed when `Firmware` +/// is dropped. This can simply be "The
firmware's backing buffer is not modified." Since I interpret "Once requested" as "Once created" and you are allowed to break invariants as long as nobody can observe that.Quoted 45 lines
rust/kernel/firmware.rs new file +45
-0+/// +/// # Examples +/// +/// ``` +/// # use kernel::{c_str, device::Device, firmware::Firmware}; +/// +/// # // 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 blob = fw.data(); +/// ``` +pub struct Firmware (NonNull <bindings::firmware >); + +impl Firmware { +fn request_internal (name: &CStr , dev: &Device , func:FwFunc ) ->Result <Self > { +let mut fw: *mut bindings::firmware = core::ptr::null_mut (); +let pfw: *mut *mut bindings::firmware = &mut fw; + +// 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 ()) }; +if ret !=0 { +return Err (Error ::from_errno (ret)); + } + +// SAFETY: `func` not bailing out with a non-zero error code, guarantees that `fw` is a +// valid pointer to `bindings::firmware`. +Ok (Firmware (unsafe {NonNull ::new_unchecked (fw) })) + } + +/// 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) + } + +/// 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) + } + +fn as_raw (&self) -> *mut bindings::firmware { + self.0 .as_ptr () + }rust/kernel/firmware.rs line 81
Quoted 10 lines
rust/kernel/firmware.rs new file +10
-0+ +/// Returns the size of the requested firmware in bytes. +pub fn size (&self) ->usize { +// SAFETY: Safe by the type invariant. +unsafe { (*self.as_raw ()).size } + } + +/// Returns the requested firmware as `&[u8]`. +pub fn data (&self) -> &[u8 ] { +// SAFETY: Safe by the type invariant. Additionally, `bindings::firmware` guarantees, if I would not write "Safe by ...", since it is important to know what is guaranteed by what. Instead I would write "
self.as_raw()is valid by the type invariant.".rust/kernel/firmware.rs line 90
Quoted 9 lines
rust/kernel/firmware.rs new file +9
-0+// successfully requested, that `bindings::firmware::data` has a size of +// `bindings::firmware::size` bytes. +unsafe { core::slice::from_raw_parts ((*self.as_raw ()).data, self.size ()) } + } +} + +impl Drop for Firmware { +fn drop (&mut self) { +// SAFETY: Safe by the type invariant. Ditto.
---
Cheers,
BennoQuoted 27 lines
rust/kernel/firmware.rs new file +11
-0+unsafe { bindings::release_firmware (self.as_raw ()) }; + } +} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, which is safe to be used from +// any thread. +unsafe impl Send for Firmware {} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references to which are safe to +// be used from any thread. +unsafe impl Sync for Firmware {}rust/kernel/lib.rs +2
-1@@ -30,6 +30,8 @@mod build_assert;pub mod device;pub mod error; +#[cfg( CONFIG_RUST_FW_LOADER_ABSTRACTIONS )] +pub mod firmware;pub mod init;pub mod ioctl;#[cfg( CONFIG_KUNIT )] --2.45.1
Greg KH
maintainerRe: [PATCH v4 2/2] rust: add firmware abstractions
Quoted 5 lines · Danilo Krummrich
Greg,
Benno's comments provide some nice hints to further improve the safety comments. Since I was notified that those patches hit your tree already, how do you want to proceed?
Please start by not top-posting :)
Anyway, patches on top of what is in my tree is fine, these are just comment updates, not any real broken issue to prevent the existing stuff from existing.
thanks,
greg k-h
Re: [PATCH v4 2/2] rust: add firmware abstractions
Quoted 8 lines · Greg KH
Quoted 5 lines · Danilo Krummrich
Greg,
Benno's comments provide some nice hints to further improve the safety comments. Since I was notified that those patches hit your tree already, how do you want to proceed?
Please start by not top-posting :)
Well, I guess it kinda made sense in this case, since I wasn't replying to any of the comments specifically.
Quoted 4 lines
Anyway, patches on top of what is in my tree is fine, these are just comment updates, not any real broken issue to prevent the existing stuff from existing.
Ok, I'll send you another series for this including the changes for the MAINTAINERS file.
- Danilo
Quoted 5 lines
thanks,
greg k-h
Gary Guo
reviewerRe: [PATCH v4 2/2] rust: add firmware abstractions
In reply to Danilo KrummrichQuoted 89 lines · On Tue, 18 Jun 2024 17:48:35 +0200 Danilo Krummrich <[email protected]> wrote:
Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware's size and backing buffer.
The firmware is released once the abstraction instance is dropped.
Signed-off-by Danilo Krummrich <[email protected]>--- drivers/base/firmware_loader/Kconfig | 7 ++ rust/bindings/bindings_helper.h | 1 + rust/kernel/firmware.rs | 101 +++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 111 insertions(+) create mode 100644 rust/kernel/firmware.rsdrivers/base/firmware_loader/Kconfig +7
-0@@ -37,6 +37,13 @@ config FW_LOADER_DEBUG SHA256 checksums to the kernel log for each firmware file that is loaded. +config RUST_FW_LOADER_ABSTRACTIONS + bool "Rust Firmware Loader abstractions" + depends on RUST + depends on FW_LOADER=y + help + This enables the Rust abstractions for the firmware loader API. + if FW_LOADER config FW_LOADER_PAGED_BUFrust/bindings/bindings_helper.h +1
-0@@ -9,6 +9,7 @@#include <kunit/test.h> #include <linux/errname.h> #include <linux/ethtool.h> +#include <linux/firmware.h> #include <linux/jiffies.h> #include <linux/mdio.h> #include <linux/phy.h> rust/kernel/firmware.rs new file +38
-0@@ -0,0 +1,101 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Firmware abstraction +//! +//! C header: [`include/linux/firmware.h`](srctree/include/linux/firmware.h") + +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 = +unsafe extern "C" fn (*mut *const bindings::firmware , *const i8 , *mut bindings::device ) ->i32 ; + +/// Abstraction around a C `struct firmware`. +/// +/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// `&[u8]`. The firmware is released once [`Firmware`] is dropped. +/// +/// # Invariants +/// +/// The pointer is valid, and has ownership over the instance of `struct firmware`. +/// +/// Once requested, the `Firmware` backing buffer is not modified until it is freed when `Firmware` +/// is dropped. +/// +/// # Examples +/// +/// ``` +/// # use kernel::{c_str, device::Device, firmware::Firmware}; +/// +/// # // 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 blob = fw.data(); +/// ```
rust/kernel/firmware.rs line 48
Quoted 10 lines
rust/kernel/firmware.rs new file +10
-0+pub struct Firmware (NonNull <bindings::firmware >); + +impl Firmware { +fn request_internal (name: &CStr , dev: &Device , func:FwFunc ) ->Result <Self > { +let mut fw: *mut bindings::firmware = core::ptr::null_mut (); +let pfw: *mut *mut bindings::firmware = &mut fw; + +// 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 ()) };
This is line is unsound if this function is called with an arbitrary FwFunc, therefore the safety comment should also mention that func cannot be an arbitrary function and it must be one of request_firmware, firmware_request_nowarn, firmware_request_platform, request_firmware_direct, and this is true because the function is not public and all users in the file satisfy this safety precondition.
Quoted 66 lines
rust/kernel/firmware.rs new file +53
-0+if ret !=0 { +return Err (Error ::from_errno (ret)); + } + +// SAFETY: `func` not bailing out with a non-zero error code, guarantees that `fw` is a +// valid pointer to `bindings::firmware`. +Ok (Firmware (unsafe {NonNull ::new_unchecked (fw) })) + } + +/// 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) + } + +/// 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) + } + +fn as_raw (&self) -> *mut bindings::firmware { + self.0 .as_ptr () + } + +/// Returns the size of the requested firmware in bytes. +pub fn size (&self) ->usize { +// SAFETY: Safe by the type invariant. +unsafe { (*self.as_raw ()).size } + } + +/// Returns the requested firmware as `&[u8]`. +pub fn data (&self) -> &[u8 ] { +// SAFETY: Safe by the type invariant. Additionally, `bindings::firmware` guarantees, if +// successfully requested, that `bindings::firmware::data` has a size of +// `bindings::firmware::size` bytes. +unsafe { core::slice::from_raw_parts ((*self.as_raw ()).data, self.size ()) } + } +} + +impl Drop for Firmware { +fn drop (&mut self) { +// SAFETY: Safe by the type invariant. +unsafe { bindings::release_firmware (self.as_raw ()) }; + } +} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, which is safe to be used from +// any thread. +unsafe impl Send for Firmware {} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references to which are safe to +// be used from any thread. +unsafe impl Sync for Firmware {}rust/kernel/lib.rs +2
-0@@ -30,6 +30,8 @@mod build_assert;pub mod device;pub mod error; +#[cfg( CONFIG_RUST_FW_LOADER_ABSTRACTIONS )] +pub mod firmware;pub mod init;pub mod ioctl;#[cfg( CONFIG_KUNIT )]
Re: [PATCH v4 2/2] rust: add firmware abstractions
Quoted 100 lines · Gary Guo
Quoted 97 lines · On Tue, 18 Jun 2024 17:48:35 +0200 Danilo Krummrich <[email protected]> wrote:
Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware's size and backing buffer.
The firmware is released once the abstraction instance is dropped.
Signed-off-by Danilo Krummrich <[email protected]>--- drivers/base/firmware_loader/Kconfig | 7 ++ rust/bindings/bindings_helper.h | 1 + rust/kernel/firmware.rs | 101 +++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 111 insertions(+)create mode 100644
rust/kernel/firmware.rsdrivers/base/firmware_loader/Kconfig +7
-0@@ -37,6 +37,13 @@ config FW_LOADER_DEBUG SHA256 checksums to the kernel log for each firmware file that is loaded. +config RUST_FW_LOADER_ABSTRACTIONS + bool "Rust Firmware Loader abstractions" + depends on RUST + depends on FW_LOADER=y + help + This enables the Rust abstractions for the firmware loader API. + if FW_LOADER config FW_LOADER_PAGED_BUFrust/bindings/bindings_helper.h +1
-0@@ -9,6 +9,7 @@#include <kunit/test.h> #include <linux/errname.h> #include <linux/ethtool.h> +#include <linux/firmware.h> #include <linux/jiffies.h> #include <linux/mdio.h> #include <linux/phy.h> rust/kernel/firmware.rs new file +46
-0@@ -0,0 +1,101 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Firmware abstraction +//! +//! C header: [`include/linux/firmware.h`](srctree/include/linux/firmware.h") + +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 = +unsafe extern "C" fn (*mut *const bindings::firmware , *const i8 , *mut bindings::device ) ->i32 ; + +/// Abstraction around a C `struct firmware`. +/// +/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// `&[u8]`. The firmware is released once [`Firmware`] is dropped. +/// +/// # Invariants +/// +/// The pointer is valid, and has ownership over the instance of `struct firmware`. +/// +/// Once requested, the `Firmware` backing buffer is not modified until it is freed when `Firmware` +/// is dropped. +/// +/// # Examples +/// +/// ``` +/// # use kernel::{c_str, device::Device, firmware::Firmware}; +/// +/// # // 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 blob = fw.data(); +/// ``` +pub struct Firmware (NonNull <bindings::firmware >); + +impl Firmware { +fn request_internal (name: &CStr , dev: &Device , func:FwFunc ) ->Result <Self > { +let mut fw: *mut bindings::firmware = core::ptr::null_mut (); +let pfw: *mut *mut bindings::firmware = &mut fw; + +// SAFETY: `pfw` is a valid pointer to a NULL initialized `bindings::firmware` pointer.
Quoted 8 lines
rust/kernel/firmware.rs line 48
Quoted 2 lines
rust/kernel/firmware.rs new file +2
-0+// `name` and `dev` are valid as by their type invariants. +let ret =unsafe {func (pfwas _ , name.as_char_ptr (), dev.as_raw ()) };This is line is unsound if this function is called with an arbitrary FwFunc, therefore the safety comment should also mention that
funccannot be an arbitrary function and it must be one ofrequest_firmware,firmware_request_nowarn,firmware_request_platform,request_firmware_direct, and this is
This is documented in the type definition of FwFunc. We can link to this invariant though and explicitly mark it as such. Does that make sense?
- Danilo
Quoted 71 lines
true because the function is not public and all users in the file satisfy this safety precondition.
Quoted 66 lines
rust/kernel/firmware.rs new file +53
-0+if ret !=0 { +return Err (Error ::from_errno (ret)); + } + +// SAFETY: `func` not bailing out with a non-zero error code, guarantees that `fw` is a +// valid pointer to `bindings::firmware`. +Ok (Firmware (unsafe {NonNull ::new_unchecked (fw) })) + } + +/// 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) + } + +/// 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) + } + +fn as_raw (&self) -> *mut bindings::firmware { + self.0 .as_ptr () + } + +/// Returns the size of the requested firmware in bytes. +pub fn size (&self) ->usize { +// SAFETY: Safe by the type invariant. +unsafe { (*self.as_raw ()).size } + } + +/// Returns the requested firmware as `&[u8]`. +pub fn data (&self) -> &[u8 ] { +// SAFETY: Safe by the type invariant. Additionally, `bindings::firmware` guarantees, if +// successfully requested, that `bindings::firmware::data` has a size of +// `bindings::firmware::size` bytes. +unsafe { core::slice::from_raw_parts ((*self.as_raw ()).data, self.size ()) } + } +} + +impl Drop for Firmware { +fn drop (&mut self) { +// SAFETY: Safe by the type invariant. +unsafe { bindings::release_firmware (self.as_raw ()) }; + } +} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, which is safe to be used from +// any thread. +unsafe impl Send for Firmware {} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references to which are safe to +// be used from any thread. +unsafe impl Sync for Firmware {}rust/kernel/lib.rs +2
-0@@ -30,6 +30,8 @@mod build_assert;pub mod device;pub mod error; +#[cfg( CONFIG_RUST_FW_LOADER_ABSTRACTIONS )] +pub mod firmware;pub mod init;pub mod ioctl;#[cfg( CONFIG_KUNIT )]
Gary Guo
reviewerRe: [PATCH v4 2/2] rust: add firmware abstractions
Quoted 80 lines · On Thu, 20 Jun 2024 15:43:52 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 70 lines · Gary Guo
Quoted 67 lines · On Tue, 18 Jun 2024 17:48:35 +0200 Danilo Krummrich <[email protected]> wrote:
Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware's size and backing buffer.
The firmware is released once the abstraction instance is dropped.
Signed-off-by Danilo Krummrich <[email protected]>--- drivers/base/firmware_loader/Kconfig | 7 ++ rust/bindings/bindings_helper.h | 1 + rust/kernel/firmware.rs | 101 +++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 111 insertions(+)create mode 100644
rust/kernel/firmware.rsrust/kernel/firmware.rs new file +46
-0@@ -0,0 +1,101 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Firmware abstraction +//! +//! C header: [`include/linux/firmware.h`](srctree/include/linux/firmware.h") + +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 = +unsafe extern "C" fn (*mut *const bindings::firmware , *const i8 , *mut bindings::device ) ->i32 ; + +/// Abstraction around a C `struct firmware`. +/// +/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// `&[u8]`. The firmware is released once [`Firmware`] is dropped. +/// +/// # Invariants +/// +/// The pointer is valid, and has ownership over the instance of `struct firmware`. +/// +/// Once requested, the `Firmware` backing buffer is not modified until it is freed when `Firmware` +/// is dropped. +/// +/// # Examples +/// +/// ``` +/// # use kernel::{c_str, device::Device, firmware::Firmware}; +/// +/// # // 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 blob = fw.data(); +/// ``` +pub struct Firmware (NonNull <bindings::firmware >); + +impl Firmware { +fn request_internal (name: &CStr , dev: &Device , func:FwFunc ) ->Result <Self > { +let mut fw: *mut bindings::firmware = core::ptr::null_mut (); +let pfw: *mut *mut bindings::firmware = &mut fw; + +// SAFETY: `pfw` is a valid pointer to a NULL initialized `bindings::firmware` pointer. Quoted 8 lines
rust/kernel/firmware.rs line 48
Quoted 2 lines
rust/kernel/firmware.rs new file +2
-0+// `name` and `dev` are valid as by their type invariants. +let ret =unsafe {func (pfwas _ , name.as_char_ptr (), dev.as_raw ()) };This is line is unsound if this function is called with an arbitrary FwFunc, therefore the safety comment should also mention that
funccannot be an arbitrary function and it must be one ofrequest_firmware,firmware_request_nowarn,firmware_request_platform,request_firmware_direct, and this is
Quoted 2 lines
This is documented in the type definition of
FwFunc. We can link to this invariant though and explicitly mark it as such. Does that make sense?
You can't really attach an invariant to FwFunc because it's just a type alias, although linking to the comment in FwFunc and mentioning that all users are within the module is good to me.
Some other options are:
* New type over FwFunc and attach invariant
* Make this function unsafe and have this as a safety precondition
Both would make the safety comment making local reasoning rather than file-level reasoning. Although I don't think either is necessary since this is a small file. But we need to be explicit file-level reasoning is used here.
Best,
Gary
Quoted 59 lines
- Danilo
Quoted 57 lines
true because the function is not public and all users in the file satisfy this safety precondition.
Quoted 53 lines
rust/kernel/firmware.rs new file +53
-0+if ret !=0 { +return Err (Error ::from_errno (ret)); + } + +// SAFETY: `func` not bailing out with a non-zero error code, guarantees that `fw` is a +// valid pointer to `bindings::firmware`. +Ok (Firmware (unsafe {NonNull ::new_unchecked (fw) })) + } + +/// 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) + } + +/// 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) + } + +fn as_raw (&self) -> *mut bindings::firmware { + self.0 .as_ptr () + } + +/// Returns the size of the requested firmware in bytes. +pub fn size (&self) ->usize { +// SAFETY: Safe by the type invariant. +unsafe { (*self.as_raw ()).size } + } + +/// Returns the requested firmware as `&[u8]`. +pub fn data (&self) -> &[u8 ] { +// SAFETY: Safe by the type invariant. Additionally, `bindings::firmware` guarantees, if +// successfully requested, that `bindings::firmware::data` has a size of +// `bindings::firmware::size` bytes. +unsafe { core::slice::from_raw_parts ((*self.as_raw ()).data, self.size ()) } + } +} + +impl Drop for Firmware { +fn drop (&mut self) { +// SAFETY: Safe by the type invariant. +unsafe { bindings::release_firmware (self.as_raw ()) }; + } +} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, which is safe to be used from +// any thread. +unsafe impl Send for Firmware {} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references to which are safe to +// be used from any thread. +unsafe impl Sync for Firmware {}