Rust abstractions for Device & Firmware
Subsystems (3)
v3 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 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 | 98 +++++++++++++++++++++++++ rust/kernel/lib.rs | 3 + 6 files changed, 212 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 v3 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 v3 1/2] rust: add abstraction for struct device
Quoted 11 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]>
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
Greg KH
maintainerRe: [PATCH v3 1/2] rust: add abstraction for struct device
Quoted 19 lines · Greg KH
Quoted 11 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]>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
Quoted 2 lines
Wait, I should just take this in my driver-core tree, right? Any objections for me taking both of these there now for 6.11-rc1 inclusion?
thanks,
greg k-h
Re: [PATCH v3 1/2] rust: add abstraction for struct device
Quoted 2 lines · Greg KH
Wait, I should just take this in my driver-core tree, right? Any
That would be ideal, yeah. Thanks!
Quoted 1 line
objections for me taking both of these there now for 6.11-rc1 inclusion?
Perhaps give it a couple days to see if any last minute feedback comes (and given Boqun's in 2/2, I think Danilo may want to send a quick v4).
Cheers,
Miguel
Greg KH
maintainerRe: [PATCH v3 1/2] rust: add abstraction for struct device
Quoted 11 lines · Miguel Ojeda
Quoted 2 lines · Greg KH
Wait, I should just take this in my driver-core tree, right? Any
That would be ideal, yeah. Thanks!
Quoted 1 line
objections for me taking both of these there now for 6.11-rc1 inclusion?
Perhaps give it a couple days to see if any last minute feedback comes (and given Boqun's in 2/2, I think Danilo may want to send a quick v4).
Ok, I'll wait a bit, thanks.
greg k-h
PATCH v3 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 | 98 ++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 108 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 +98 -0
98 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 v3 2/2] rust: add firmware abstractions
Quoted 78 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 | 98 ++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 108 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 +27
-0@@ -0,0 +1,98 @@ +// 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`. +/// +/// # Examples +/// +/// ```
rust/kernel/firmware.rs line 37
Quoted 10 lines
rust/kernel/firmware.rs new file +10
-0+/// # 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 >); +
I feel like eventually we need a very simple smart pointer type for these case, for example:
/// A smart pointer owns the underlying data.
pub struct Owned<T: Ownable> {
ptr: NonNull<T>,
}
impl<T: Ownable> Owned<T> {
/// # Safety
/// `ptr` needs to be a valid pointer, and it should be the
/// unique owner to the object, in other words, no one can touch
/// or free the underlying data.
pub unsafe to_owned(ptr: *mut T) -> Self {
// SAFETY: Per function safety requirement.
Self { ptr: unsafe { NonNull::new_unchecked(ptr) } }
}
/// other safe constructors are available if a initializer (impl
/// Init) is provided
}
/// A Ownable type is a type that can be put into `Owned<T>`, and
/// when `Owned<T>` drops, `ptr_drop` will be called.
pub unsafe trait Ownable {
/// # Safety
/// This could only be called in the `Owned::drop` function.
unsafe fn ptr_drop(ptr: *mut Self);
}
impl<T: Ownable> Drop for Owned<T> {
fn drop(&mut self) {
/// SAFETY: In Owned<T>::drop.
unsafe {
<T as Ownable>::ptr_drop(self.as_mut_ptr());
}
}
}we can implement Deref and DerefMut easily on Owned<T>. And then we could define Firmware as
#[repr(transparent)]
pub struct Firmware(Opaque<bindings::firmware>);and
unsafe impl Ownable for Firmware {
unsafe fn ptr_drop(ptr: *mut Self) {
// SAFETY: Per function safety, this is called in
// Owned::drop(), so `ptr` is a unique pointer to object,
// it's safe to release the firmware.
unsafe { bindings::release_firmware(ptr.cast()); }
}
}and the request_*() will return a Result<Owned<Self>>.
Alice mentioned the need of this in page as well:
Just bring it up while we are (maybe not? ;-)) at it. Also I would like to hear whether this would work for Firmware in the longer-term ;-) But yes, I'm not that worried about merging it as it is if others are all OK.
Quoted 31 lines
rust/kernel/firmware.rs new file +31
-0+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 78
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
Does this "Safe by the type invariant" also covers the following safe requirement of from_raw_parts?
The memory referenced by the returned slice must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.
in that &[u8] has the same lifetime as &self, and as long as &self exists, no function can touch the inner data? If so, I probably want to call this out.
Regards,
Boqun
Quoted 36 lines
rust/kernel/firmware.rs new file +20
-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. +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 v3 2/2] rust: add firmware abstractions
Quoted 146 lines · Boqun Feng
Quoted 78 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 | 98 ++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 4 files changed, 108 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 +27
-0@@ -0,0 +1,98 @@ +// 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`. +/// +/// # Examples +/// +/// ``` rust/kernel/firmware.rs line 37
Quoted 10 lines
rust/kernel/firmware.rs new file +10
-0+/// # 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 >); +I feel like eventually we need a very simple smart pointer type for these case, for example:
/// A smart pointer owns the underlying data. pub struct Owned<T: Ownable> { ptr: NonNull<T>, } impl<T: Ownable> Owned<T> { /// # Safety /// `ptr` needs to be a valid pointer, and it should be the /// unique owner to the object, in other words, no one can touch /// or free the underlying data. pub unsafe to_owned(ptr: *mut T) -> Self { // SAFETY: Per function safety requirement. Self { ptr: unsafe { NonNull::new_unchecked(ptr) } } } /// other safe constructors are available if a initializer (impl /// Init) is provided } /// A Ownable type is a type that can be put into `Owned<T>`, and /// when `Owned<T>` drops, `ptr_drop` will be called. pub unsafe trait Ownable { /// # Safety /// This could only be called in the `Owned::drop` function. unsafe fn ptr_drop(ptr: *mut Self); } impl<T: Ownable> Drop for Owned<T> { fn drop(&mut self) { /// SAFETY: In Owned<T>::drop. unsafe { <T as Ownable>::ptr_drop(self.as_mut_ptr()); } } }we can implement Deref and DerefMut easily on
Owned<T>. And then we could define Firmware as#[repr(transparent)] pub struct Firmware(Opaque<bindings::firmware>);and
unsafe impl Ownable for Firmware { unsafe fn ptr_drop(ptr: *mut Self) { // SAFETY: Per function safety, this is called in // Owned::drop(), so `ptr` is a unique pointer to object, // it's safe to release the firmware. unsafe { bindings::release_firmware(ptr.cast()); } } }
Quoted 5 lines
and the request_*() will return a
Result<Owned<Self>>.Alice mentioned the need of this in page as well:
I think in the Page case this is useful to create Page references from previously allocated memory.
In the case of Firmware, I agree it makes sense to use it once we have it, but other than for consistency, is there any advantage?
Quoted 5 lines
Just bring it up while we are (maybe not? ;-)) at it. Also I would like to hear whether this would work for Firmware in the longer-term ;-) But yes, I'm not that worried about merging it as it is if others are all OK.
I think there's not too much to add here in the future, once we got an allocator API (I should get back to that soon), I want to add a method that copies the data to a new buffer allocated with a given allocator. And maybe we want to support a few other request_firmware_* functions in the future, but none of that should require the above abstraction.
Quoted 46 lines
Quoted 32 lines
rust/kernel/firmware.rs new file +31
-0+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 78
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 Does this "Safe by the type invariant" also covers the following safe requirement of
from_raw_parts?
Quoted 5 lines
The memory referenced by the returned slice must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.
in that
&[u8]has the same lifetime as&self, and as long as&selfexists, no function can touch the innerdata? If so, I probably want to call this out.
Yes, nothing should ever modify the firmware buffer after it has been requested successfully. I can add this to the type invariant.
Quoted 41 lines
Regards,
BoqunQuoted 36 lines
rust/kernel/firmware.rs new file +20
-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. +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 v3 2/2] rust: add firmware abstractions
On Tue, Jun 18, 2024 at 12:50:45AM +0200, Danilo Krummrich wrote:
[...]
Quoted 57 lines
Quoted 57 lines
/// A smart pointer owns the underlying data. pub struct Owned<T: Ownable> { ptr: NonNull<T>, } impl<T: Ownable> Owned<T> { /// # Safety /// `ptr` needs to be a valid pointer, and it should be the /// unique owner to the object, in other words, no one can touch /// or free the underlying data. pub unsafe to_owned(ptr: *mut T) -> Self { // SAFETY: Per function safety requirement. Self { ptr: unsafe { NonNull::new_unchecked(ptr) } } } /// other safe constructors are available if a initializer (impl /// Init) is provided } /// A Ownable type is a type that can be put into `Owned<T>`, and /// when `Owned<T>` drops, `ptr_drop` will be called. pub unsafe trait Ownable { /// # Safety /// This could only be called in the `Owned::drop` function. unsafe fn ptr_drop(ptr: *mut Self); } impl<T: Ownable> Drop for Owned<T> { fn drop(&mut self) { /// SAFETY: In Owned<T>::drop. unsafe { <T as Ownable>::ptr_drop(self.as_mut_ptr()); } } }we can implement Deref and DerefMut easily on
Owned<T>. And then we could define Firmware as#[repr(transparent)] pub struct Firmware(Opaque<bindings::firmware>);and
unsafe impl Ownable for Firmware { unsafe fn ptr_drop(ptr: *mut Self) { // SAFETY: Per function safety, this is called in // Owned::drop(), so `ptr` is a unique pointer to object, // it's safe to release the firmware. unsafe { bindings::release_firmware(ptr.cast()); } } }and the request_*() will return a
Result<Owned<Self>>.Alice mentioned the need of this in page as well:
Quoted 8 lines
Quoted 1 line
I think in the
Pagecase this is useful to createPagereferences from previously allocated memory.In the case of
Firmware, I agree it makes sense to use it once we have it, but other than for consistency, is there any advantage?
To help people build future abstraction easier (and make review easier as well). But I'm also waiting for a third use case, yes, I usually wait for 3 cases to begin thinking about generalization ;-)
Quoted 6 lines
Quoted 5 lines
Just bring it up while we are (maybe not? ;-)) at it. Also I would like to hear whether this would work for Firmware in the longer-term ;-) But yes, I'm not that worried about merging it as it is if others are all OK.
Quoted 6 lines
I think there's not too much to add here in the future, once we got an allocator API (I should get back to that soon), I want to add a method that copies the data to a new buffer allocated with a given allocator. And maybe we want to support a few other request_firmware_* functions in the future, but none of that should require the above abstraction.
Thank you!
Quoted 46 lines
Quoted 46 lines
Quoted 32 lines
rust/kernel/firmware.rs new file +31
-0+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 78
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 Does this "Safe by the type invariant" also covers the following safe requirement of
from_raw_parts?
Quoted 9 lines
Quoted 5 lines
The memory referenced by the returned slice must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.
in that
&[u8]has the same lifetime as&self, and as long as&selfexists, no function can touch the innerdata? If so, I probably want to call this out.Yes, nothing should ever modify the firmware buffer after it has been requested successfully. I can add this to the type invariant.
Oh, you have an even easier (stronger) type invariant. Yes, please add it and use it here. Thanks!
Regards,
Boqun
Quoted 42 lines
Quoted 41 lines
Regards,
BoqunQuoted 36 lines
rust/kernel/firmware.rs new file +20
-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. +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 v3 2/2] rust: add firmware abstractions
In reply to Boqun FengQuoted 8 lines · Boqun Feng
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]>
..
Quoted 72 lines
rust/kernel/firmware.rs line 37
Quoted 13 lines
rust/kernel/firmware.rs new file +13
-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 >); +I feel like eventually we need a very simple smart pointer type for these case, for example:
/// A smart pointer owns the underlying data. pub struct Owned<T: Ownable> { ptr: NonNull<T>, } impl<T: Ownable> Owned<T> { /// # Safety /// `ptr` needs to be a valid pointer, and it should be the /// unique owner to the object, in other words, no one can touch /// or free the underlying data. pub unsafe to_owned(ptr: *mut T) -> Self { // SAFETY: Per function safety requirement. Self { ptr: unsafe { NonNull::new_unchecked(ptr) } } } /// other safe constructors are available if a initializer (impl /// Init) is provided } /// A Ownable type is a type that can be put into `Owned<T>`, and /// when `Owned<T>` drops, `ptr_drop` will be called. pub unsafe trait Ownable { /// # Safety /// This could only be called in the `Owned::drop` function. unsafe fn ptr_drop(ptr: *mut Self); } impl<T: Ownable> Drop for Owned<T> { fn drop(&mut self) { /// SAFETY: In Owned<T>::drop. unsafe { <T as Ownable>::ptr_drop(self.as_mut_ptr()); } } }we can implement Deref and DerefMut easily on
Owned<T>. And then we could define Firmware as#[repr(transparent)] pub struct Firmware(Opaque<bindings::firmware>);and
unsafe impl Ownable for Firmware { unsafe fn ptr_drop(ptr: *mut Self) { // SAFETY: Per function safety, this is called in // Owned::drop(), so `ptr` is a unique pointer to object, // it's safe to release the firmware. unsafe { bindings::release_firmware(ptr.cast()); } } }and the request_*() will return a
Result<Owned<Self>>.
Quoted 8 lines
Alice mentioned the need of this in page as well:
Just bring it up while we are (maybe not? ;-)) at it. Also I would like to hear whether this would work for Firmware in the longer-term ;-) But yes, I'm not that worried about merging it as it is if others are all OK.
Please see [1] for an attempt at this pattern.
Best regards,
Andreas Hindborg
Luis Chamberlain
maintainerRe: [PATCH v3 2/2] rust: add firmware abstractions
In reply to Danilo KrummrichQuoted 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]>
I don't speak Rust, so if we're gonna add this, I'd just ask you also become a firmware loader maintainer, willing to spend time to help review both C and Rust code. Is that too much to ask?
Luis
Re: [PATCH v3 2/2] rust: add firmware abstractions
Hi Luis,
Quoted 5 lines · Luis Chamberlain
Quoted 4 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.
Quoted 7 lines
Quoted 3 lines
The firmware is released once the abstraction instance is dropped.
Signed-off-by Danilo Krummrich <[email protected]>I don't speak Rust, so if we're gonna add this, I'd just ask you also become a firmware loader maintainer, willing to spend time to help review both C and Rust code. Is that too much to ask?
That is fine, I'm happy to help out. I think Greg applied the patch already. But I can send a separate one adding the corresponding entry later on.
- Danilo
Quoted 3 lines
Luis