In the NVIDIA vGPU RFC [1], the vGPU type blobs must be provided to the GSP before userspace can enumerate available vGPU types and create vGPU instances. The original design relied on the firmware loading interface, but fwctl is a more natural fit for this use case, as it is designed for uploading configuration or firmware data required before the device becomes operational. This patch introduces a Rust abstraction over the fwctl subsystem, providing safe and idiomatic bindings. The new `fwctl` module allows Rust drivers to integrate with the existing C-side fwctl core through a typed trait interface. It provides: - `Operations` trait — defines driver-specific operations such as `open_uctx()`, `close_uctx()`, `info()`, and `fw_rpc()`. Each Rust driver implements this trait to describe its own per-FD user-context behavior and RPC handling. - `UserCtx<T>` — a generic wrapper around `struct fwctl_uctx` embedding driver-specific context data, providing safe conversion from raw C pointers and access to the parent device. - `Registration<T>` — safe registration and automatic unregistration of `struct fwctl_device` objects using the kernel's device model. - `VTable<T>` — a static vtable bridging C callbacks and Rust trait methods, ensuring type safety across the FFI boundary. `rust/kernel/lib.rs` is updated to conditionally include this module under `CONFIG_FWCTL`. The repo with the patches can be found at [2]. v2: - Don't open fwctl_put(). Add a rust helper. (Jason/Danilo) - Wrap Registration with Devres to guarantee proper lifetime management. (Jason/Danilo) - Rename FwctlOps to Operations, FwctlUserCtx to UserCtx, FwctlDevice to Device. (Danilo) - Use fwctl::DeviceType enum instead of raw u32 for DEVICE_TYPE. (Danilo) - Change fwctl_uctx field in UserCtx to Opaque<bindings::fwctl_uctx> and make it private. (Danilo) - Provide Deref and DerefMut implementations for UserCtx::uctx. (Danilo) - Add UserCtx::parent_device_from_raw() to simplify parent device access. - Use cast() and cast_mut() instead of manual pointer casts. (Danilo) - Implement AlwaysRefCounted for Device and use ARef<Device> in Registration. (Danilo) - Add rust_helper_fwctl_get() for reference counting. - Improve safety comments for slice::from_raw_parts_mut() in fw_rpc_callback. (Danilo) - Convert imports to vertical style. - Fix all clippy warnings. v1: - Initial submission introducing fwctl Rust abstractions. [1] https://lore.kernel.org/all/20250903221111.3866249-1-zhiw@nvidia.com/ [2] https://github.com/zhiwang-nvidia/driver-core/tree/fwctl-rust-abstraction-v2 Zhi Wang (2): rust: introduce abstractions for fwctl samples: rust: fwctl: add sample code for fwctl drivers/fwctl/Kconfig | 12 + include/uapi/fwctl/fwctl.h | 1 + rust/bindings/bindings_helper.h | 1 + rust/helpers/fwctl.c | 17 ++ rust/helpers/helpers.c | 3 +- rust/kernel/fwctl.rs | 456 ++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + samples/rust/Kconfig | 11 + samples/rust/Makefile | 1 + samples/rust/rust_driver_fwctl.rs | 136 +++++++++ 10 files changed, 639 insertions(+), 1 deletion(-) create mode 100644 rust/helpers/fwctl.c create mode 100644 rust/kernel/fwctl.rs create mode 100644 samples/rust/rust_driver_fwctl.rs -- 2.51.0 Introduce safe wrappers around `struct fwctl_device` and `struct fwctl_uctx`, allowing rust drivers to register fwctl devices and implement their control and RPC logic in safe rust. Cc: Danilo Krummrich <dakr@kernel.org> Cc: Jason Gunthorpe <jgg@nvidia.com> Signed-off-by: Zhi Wang <zhiw@nvidia.com> --- drivers/fwctl/Kconfig | 12 + include/uapi/fwctl/fwctl.h | 1 + rust/bindings/bindings_helper.h | 1 + rust/helpers/fwctl.c | 17 ++ rust/helpers/helpers.c | 3 +- rust/kernel/fwctl.rs | 456 ++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 7 files changed, 491 insertions(+), 1 deletion(-) create mode 100644 rust/helpers/fwctl.c create mode 100644 rust/kernel/fwctl.rs diff --git a/drivers/fwctl/Kconfig b/drivers/fwctl/Kconfig index XXXXXXX..XXXXXXX 100644 --- a/drivers/fwctl/Kconfig +++ b/drivers/fwctl/Kconfig @@ -XXX,XX +XXX,XX @@ menuconfig FWCTL manipulating device FLASH, debugging, and other activities that don't fit neatly into an existing subsystem. +config RUST_FWCTL_ABSTRACTIONS + bool "Rust fwctl abstractions" + depends on RUST + select FWCTL + help + This enables the Rust abstractions for the fwctl device firmware + access framework. It provides safe wrappers around struct fwctl_device + and struct fwctl_uctx, allowing Rust drivers to register fwctl devices + and implement their control and RPC logic in safe Rust. + + If unsure, say N. + if FWCTL config FWCTL_MLX5 tristate "mlx5 ConnectX control fwctl driver" diff --git a/include/uapi/fwctl/fwctl.h b/include/uapi/fwctl/fwctl.h index XXXXXXX..XXXXXXX 100644 --- a/include/uapi/fwctl/fwctl.h +++ b/include/uapi/fwctl/fwctl.h @@ -XXX,XX +XXX,XX @@ enum fwctl_device_type { FWCTL_DEVICE_TYPE_MLX5 = 1, FWCTL_DEVICE_TYPE_CXL = 2, FWCTL_DEVICE_TYPE_PDS = 4, + FWCTL_DEVICE_TYPE_RUST_FWCTL_TEST = 8, }; /** diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h index XXXXXXX..XXXXXXX 100644 --- a/rust/bindings/bindings_helper.h +++ b/rust/bindings/bindings_helper.h @@ -XXX,XX +XXX,XX @@ #include <linux/fdtable.h> #include <linux/file.h> #include <linux/firmware.h> +#include <linux/fwctl.h> #include <linux/interrupt.h> #include <linux/fs.h> #include <linux/i2c.h> diff --git a/rust/helpers/fwctl.c b/rust/helpers/fwctl.c new file mode 100644 index XXXXXXX..XXXXXXX --- /dev/null +++ b/rust/helpers/fwctl.c @@ -XXX,XX +XXX,XX @@ +// SPDX-License-Identifier: GPL-2.0 + +#include <linux/fwctl.h> + +#if IS_ENABLED(CONFIG_RUST_FWCTL_ABSTRACTIONS) + +struct fwctl_device *rust_helper_fwctl_get(struct fwctl_device *fwctl) +{ + return fwctl_get(fwctl); +} + +void rust_helper_fwctl_put(struct fwctl_device *fwctl) +{ + fwctl_put(fwctl); +} + +#endif diff --git a/rust/helpers/helpers.c b/rust/helpers/helpers.c index XXXXXXX..XXXXXXX 100644 --- a/rust/helpers/helpers.c +++ b/rust/helpers/helpers.c @@ -XXX,XX +XXX,XX @@ #include "dma.c" #include "drm.c" #include "err.c" -#include "irq.c" #include "fs.c" +#include "fwctl.c" +#include "irq.c" #include "io.c" #include "jump_label.c" #include "kunit.c" diff --git a/rust/kernel/fwctl.rs b/rust/kernel/fwctl.rs new file mode 100644 index XXXXXXX..XXXXXXX --- /dev/null +++ b/rust/kernel/fwctl.rs @@ -XXX,XX +XXX,XX @@ +// SPDX-License-Identifier: GPL-2.0-only + +//! Abstractions for the fwctl. +//! +//! This module provides bindings for working with fwctl devices in kernel modules. +//! +//! C header: [`include/linux/fwctl.h`] + +use crate::{ + bindings, + container_of, + device, + devres::Devres, + prelude::*, + types::{ + ARef, + Opaque, // + }, // +}; +use core::{ + marker::PhantomData, + ptr::NonNull, + slice, // +}; + +/// Represents a fwctl device type. +/// +/// This enum corresponds to the C `enum fwctl_device_type` and is used to identify +/// the specific firmware control interface implemented by a device. +#[repr(u32)] +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +pub enum DeviceType { + /// Error/invalid device type. + Error = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_ERROR, + /// MLX5 device type. + Mlx5 = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_MLX5, + /// CXL device type. + Cxl = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_CXL, + /// PDS device type. + Pds = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_PDS, + /// Rust fwctl test device type. + RustFwctlTest = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_RUST_FWCTL_TEST, +} + +impl From<DeviceType> for u32 { + fn from(device_type: DeviceType) -> Self { + device_type as u32 + } +} + +/// A fwctl device. +/// +/// Wraps the C `struct fwctl_device` and manages its reference count. +/// +/// # Invariants +/// +/// Instances of this type represent a valid `struct fwctl_device` created by the C portion +/// of the kernel. +#[repr(transparent)] +pub struct Device(Opaque<bindings::fwctl_device>); + +impl Device { + /// # Safety + /// + /// `ptr` must be a valid pointer to a `struct fwctl_device`. + unsafe fn from_raw<'a>(ptr: *mut bindings::fwctl_device) -> &'a Self { + // CAST: `Self` is a transparent wrapper around `bindings::fwctl_device`. + // SAFETY: By the safety requirement, `ptr` is valid. + unsafe { &*ptr.cast() } + } + + fn as_raw(&self) -> *mut bindings::fwctl_device { + self.0.get() + } + + /// Returns the parent device. + pub fn parent(&self) -> &device::Device { + // SAFETY: By the type invariant, `self.as_raw()` is a valid pointer to a + // `struct fwctl_device`, which always has a parent device. + let parent_dev = unsafe { (*self.as_raw()).dev.parent }; + // SAFETY: `parent_dev` points to a valid `struct device`. The parent device + // is guaranteed to be valid for the lifetime of the fwctl_device. + unsafe { device::Device::from_raw(parent_dev) } + } +} + +impl AsRef<device::Device> for Device { + fn as_ref(&self) -> &device::Device { + // SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid + // `struct fwctl_device`. + let dev = unsafe { core::ptr::addr_of_mut!((*self.as_raw()).dev) }; + + // SAFETY: `dev` points to a valid `struct device`. + unsafe { device::Device::from_raw(dev) } + } +} + +// SAFETY: The fwctl_device is reference counted through the embedded `struct device`, +// and inc_ref/dec_ref use fwctl_get/fwctl_put to manage its lifetime. +unsafe impl crate::sync::aref::AlwaysRefCounted for Device { + fn inc_ref(&self) { + // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero. + // `self.as_raw()` is a valid pointer to a `struct fwctl_device`. + unsafe { bindings::fwctl_get(self.as_raw()) }; + } + + unsafe fn dec_ref(obj: NonNull<Self>) { + // CAST: `Self` is a transparent wrapper of `bindings::fwctl_device`. + let fwctl: *mut bindings::fwctl_device = obj.cast().as_ptr(); + + // SAFETY: By the type invariant, `fwctl` is a valid pointer to a `struct fwctl_device`. + unsafe { bindings::fwctl_put(fwctl) }; + } +} + +// SAFETY: A `Device` is always reference-counted and can be released from any thread. +unsafe impl Send for Device {} + +// SAFETY: `Device` can be shared among threads because all methods are thread-safe. +unsafe impl Sync for Device {} + +/// The registration of a fwctl device. +/// +/// This type represents the registration of a [`struct fwctl_device`]. It should always be +/// used within a [`Devres`] wrapper to ensure proper lifetime management. When dropped, +/// the fwctl device will be unregistered and freed. +/// +/// [`Devres`] guarantees that the device is unregistered before the parent device is unbound. +/// +/// [`struct fwctl_device`]: srctree/include/linux/device/fwctl.h +pub struct Registration<T: Operations> { + device: ARef<Device>, + _marker: PhantomData<T>, +} + +impl<T: Operations> Registration<T> { + /// Allocate and register a new fwctl device under the given parent device. + /// + /// The returned [`Devres`] wrapper ensures that the fwctl device is unregistered + /// before the parent device is unbound. + pub fn new<'a>( + parent: &'a device::Device<device::Bound>, + ) -> impl PinInit<Devres<Self>, Error> + 'a + where + T: 'a, + { + pin_init::pin_init_scope(move || { + let ops = core::ptr::from_ref::<bindings::fwctl_ops>(&VTable::<T>::VTABLE).cast_mut(); + + // SAFETY: `_fwctl_alloc_device()` allocates a new `fwctl_device` + // and initializes its embedded `struct device`. The `ops` pointer + // points to a static VTABLE that outlives the device. The parent + // device is guaranteed to be bound to a driver (Device<Bound>), + // ensuring it remains valid during allocation. + let dev = unsafe { + bindings::_fwctl_alloc_device( + parent.as_raw(), + ops, + core::mem::size_of::<bindings::fwctl_device>(), + ) + }; + + if dev.is_null() { + return Err(ENOMEM); + } + + // SAFETY: dev is guaranteed to be a valid pointer from `_fwctl_alloc_device()`. + let ret = unsafe { bindings::fwctl_register(dev) }; + if ret != 0 { + // SAFETY: dev is guaranteed to be a valid pointer from `_fwctl_alloc_device()`. + unsafe { + bindings::fwctl_put(dev); + } + return Err(Error::from_errno(ret)); + } + + // SAFETY: dev is guaranteed to be a valid pointer from `_fwctl_alloc_device()`. + let device = unsafe { + let dev_ref = Device::from_raw(dev); + // SAFETY: We just verified dev is non-null above, and Device::from_raw + // returns a reference, so NonNull::new_unchecked is safe. + ARef::from_raw(NonNull::new_unchecked( + core::ptr::from_ref(dev_ref).cast_mut(), + )) + }; + + Ok(Devres::new( + parent, + Self { + device, + _marker: PhantomData, + }, + )) + }) + } + + fn as_raw(&self) -> *mut bindings::fwctl_device { + self.device.as_raw() + } +} + +impl<T: Operations> Drop for Registration<T> { + fn drop(&mut self) { + // SAFETY: `fwctl_unregister()` expects a valid registered device. + // By the type invariant, `self.device` holds a valid fwctl_device. + unsafe { + bindings::fwctl_unregister(self.as_raw()); + } + // The ARef<Device> will automatically call fwctl_put() when dropped. + } +} + +// SAFETY: `Registration` can be sent to other threads because: +// - It only contains a `NonNull<fwctl_device>` pointer and a PhantomData marker +// - The underlying C fwctl_device is thread-safe with internal locking +// - `Drop` calls `fwctl_unregister()/fwctl_put()` which are safe from any sleepable context +unsafe impl<T: Operations> Send for Registration<T> {} + +// SAFETY: `Registration` can be shared between threads because: +// - It provides no methods for mutation (except Drop, which takes &mut self) +// - The underlying C fwctl_device is protected by internal locking (registration_lock) +// - Multiple threads can safely hold immutable references to the same Registration +unsafe impl<T: Operations> Sync for Registration<T> {} + +/// Trait implemented by each Rust driver that integrates with the fwctl subsystem. +/// +/// Each implementation corresponds to a specific device type and provides +/// the vtable used by the core `fwctl` layer to manage per-FD user contexts +/// and handle RPC requests. +pub trait Operations: Sized { + /// Driver user context type. + type UserCtx; + + /// fwctl device type. + const DEVICE_TYPE: DeviceType; + + /// Called when a new user context is opened by userspace. + fn open( + fwctl_uctx: &Opaque<bindings::fwctl_uctx>, + ) -> Result<impl PinInit<Self::UserCtx, Error>, Error>; + + /// Called when the user context is being closed. + fn close(uctx: &mut UserCtx<Self::UserCtx>); + + /// Return device or context information to userspace. + fn info(uctx: &mut UserCtx<Self::UserCtx>) -> Result<KVec<u8>, Error>; + + /// Called when a userspace RPC request is received. + fn fw_rpc( + uctx: &mut UserCtx<Self::UserCtx>, + scope: u32, + rpc_in: &mut [u8], + out_len: *mut usize, + ) -> Result<Option<KVec<u8>>, Error>; +} + +/// Represents a per-FD user context (`struct fwctl_uctx`). +#[repr(C)] +#[pin_data] +pub struct UserCtx<T> { + /// The core fwctl user context shared with the C implementation. + #[pin] + fwctl_uctx: Opaque<bindings::fwctl_uctx>, + + /// Driver-specific data associated with this user context. + #[pin] + uctx: T, +} + +impl<T> UserCtx<T> { + /// Converts a raw C pointer to `struct fwctl_uctx` into a reference to the + /// enclosing `UserCtx<T>`. + /// + /// # Safety + /// * `ptr` must be a valid pointer to a `fwctl_uctx` that is embedded + /// inside an existing `UserCtx<T>` instance. + /// * The caller must ensure that the lifetime of the returned reference + /// does not outlive the underlying object managed on the C side. + unsafe fn from_raw<'a>(ptr: *mut bindings::fwctl_uctx) -> &'a mut Self { + // SAFETY: `ptr` was originally created from a valid `UserCtx<T>`. + // We cast through `Opaque` since `fwctl_uctx` is wrapped in `Opaque`. + unsafe { &mut *container_of!(Opaque::cast_from(ptr), UserCtx<T>, fwctl_uctx).cast_mut() } + } + + /// Returns a reference to the parent device from a raw `fwctl_uctx` pointer. + pub fn parent_device_from_raw( + fwctl_uctx: &Opaque<bindings::fwctl_uctx>, + ) -> &device::Device<device::Bound> { + // SAFETY: `fwctl_uctx` is initialized by the fwctl subsystem + // and guaranteed to remain valid. + let raw_fwctl = unsafe { (*fwctl_uctx.get()).fwctl }; + // SAFETY: `raw_fwctl` is a valid pointer to a `fwctl_device`, and its `dev.parent` + // field points to a valid parent device. + let raw_dev = unsafe { (*raw_fwctl).dev.parent }; + + // SAFETY: `raw_dev` points to a live device object. + let dev: &device::Device = unsafe { device::Device::from_raw(raw_dev) }; + + // SAFETY: The device is guaranteed to be bound. + unsafe { dev.as_bound() } + } + + /// Returns a reference to the parent device of this user context. + pub fn get_parent_device(&self) -> &device::Device<device::Bound> { + Self::parent_device_from_raw(&self.fwctl_uctx) + } +} + +impl<T> core::ops::Deref for UserCtx<T> { + type Target = T; + + fn deref(&self) -> &Self::Target { + &self.uctx + } +} + +impl<T> core::ops::DerefMut for UserCtx<T> { + fn deref_mut(&mut self) -> &mut Self::Target { + &mut self.uctx + } +} + +/// Static vtable mapping Rust trait methods to C callbacks. +pub struct VTable<T: Operations>(PhantomData<T>); + +impl<T: Operations> VTable<T> { + /// Static instance of `fwctl_ops` used by the C core to call into Rust. + pub const VTABLE: bindings::fwctl_ops = bindings::fwctl_ops { + device_type: T::DEVICE_TYPE as u32, + uctx_size: core::mem::size_of::<UserCtx<T::UserCtx>>(), + open_uctx: Some(Self::open_uctx_callback), + close_uctx: Some(Self::close_uctx_callback), + info: Some(Self::info_callback), + fw_rpc: Some(Self::fw_rpc_callback), + }; + + /// Called when a new user context is opened by userspace. + /// # Safety + /// + /// `uctx` must be a valid pointer to an initialized `fwctl_uctx` structure, + /// embedded within a C-allocated `UserCtx<T::UserCtx>` with sufficient space. + unsafe extern "C" fn open_uctx_callback(uctx: *mut bindings::fwctl_uctx) -> ffi::c_int { + // SAFETY: `uctx` points to valid, initialized `fwctl_uctx` structure. + let fwctl_uctx_ref = unsafe { &*Opaque::cast_from(uctx) }; + + let initializer = match T::open(fwctl_uctx_ref) { + Ok(init) => init, + Err(e) => return e.to_errno(), + }; + + let uctx_offset = core::mem::offset_of!(UserCtx<T::UserCtx>, uctx); + + // SAFETY: The C side allocated enough space for the entire UserCtx. + let uctx_ptr: *mut T::UserCtx = unsafe { uctx.cast::<u8>().add(uctx_offset).cast() }; + + // Initialize the uctx field in-place using the pin initializer. + // SAFETY: + // - uctx_ptr points to valid allocated memory + // - The memory is properly aligned (guaranteed by #[repr(C)] and our compile-time check) + // - The memory is uninitialized, which is what PinInit expects + // - After this call, the memory will be properly initialized + match unsafe { initializer.__pinned_init(uctx_ptr.cast()) } { + Ok(()) => 0, + Err(e) => e.to_errno(), + } + } + + /// Called when the user context is being closed. + /// # Safety + /// + /// `uctx` must be a valid pointer to an initialized `fwctl_uctx` structure, + /// embedded within a fully initialized `UserCtx<T::UserCtx>`. + unsafe extern "C" fn close_uctx_callback(uctx: *mut bindings::fwctl_uctx) { + // SAFETY: `uctx` is guaranteed by the fwctl subsystem to be a valid pointer. + let ctx = unsafe { UserCtx::<T::UserCtx>::from_raw(uctx) }; + T::close(ctx); + } + + /// Returns device or context information. + /// # Safety + /// + /// - `uctx` must be a valid pointer to an initialized `fwctl_uctx` structure, + /// embedded within a fully initialized `UserCtx<T::UserCtx>`. + /// - `length` must be a valid pointer to write the output length. + unsafe extern "C" fn info_callback( + uctx: *mut bindings::fwctl_uctx, + length: *mut usize, + ) -> *mut ffi::c_void { + // SAFETY: `uctx` is guaranteed by the fwctl subsystem to be a valid pointer. + let ctx = unsafe { UserCtx::<T::UserCtx>::from_raw(uctx) }; + + match T::info(ctx) { + Ok(kvec) => { + // The ownership of the buffer is now transferred to the foreign + // caller. It must eventually be released by fwctl framework. + let (ptr, len, _cap) = kvec.into_raw_parts(); + + // SAFETY: `length` is a valid out-parameter provided by the C + // caller. Write the number of bytes in the returned buffer. + unsafe { + *length = len; + } + + ptr.cast::<ffi::c_void>() + } + + Err(e) => Error::to_ptr(e), + } + } + + /// Called when a user-space RPC request is received. + /// # Safety + /// + /// - `uctx` must be a valid pointer to an initialized `fwctl_uctx` structure, + /// embedded within a fully initialized `UserCtx<T::UserCtx>`. + /// - `rpc_in` must be a valid pointer to `in_len` bytes of readable/writable memory. + /// - `out_len` must be a valid pointer to write the output length. + unsafe extern "C" fn fw_rpc_callback( + uctx: *mut bindings::fwctl_uctx, + scope: u32, + rpc_in: *mut ffi::c_void, + in_len: usize, + out_len: *mut usize, + ) -> *mut ffi::c_void { + // SAFETY: `uctx` is guaranteed by the fwctl framework to be a valid pointer. + let ctx = unsafe { UserCtx::<T::UserCtx>::from_raw(uctx) }; + + // SAFETY: Creating a mutable slice from `rpc_in`: + // - `rpc_in` is non-null and properly aligned: guaranteed by the fwctl subsystem + // - `rpc_in` points to `in_len` consecutive properly initialized bytes + // - The memory is valid for reads and writes for the lifetime of the returned slice + // - The total size `in_len` does not exceed `isize::MAX`: checked by the fwctl subsystem + // - No other references to this memory exist during this callback + let rpc_in_slice: &mut [u8] = + unsafe { slice::from_raw_parts_mut(rpc_in.cast::<u8>(), in_len) }; + + match T::fw_rpc(ctx, scope, rpc_in_slice, out_len) { + // Driver allocates a new output buffer. + Ok(Some(kvec)) => { + // The ownership of the buffer is now transferred to the foreign + // caller. It must eventually be released by fwctl subsystem. + let (ptr, len, _cap) = kvec.into_raw_parts(); + + // SAFETY: `out_len` is a valid writable pointer provided by the C caller. + unsafe { *out_len = len }; + + ptr.cast::<ffi::c_void>() + } + + // Driver re-uses the existing input buffer and writes the out_len. + Ok(None) => rpc_in, + + Err(e) => Error::to_ptr(e), + } + } +} diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index XXXXXXX..XXXXXXX 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -XXX,XX +XXX,XX @@ pub mod firmware; pub mod fmt; pub mod fs; +#[cfg(CONFIG_RUST_FWCTL_ABSTRACTIONS)] +pub mod fwctl; #[cfg(CONFIG_I2C = "y")] pub mod i2c; pub mod id_pool; -- 2.51.0 This patch adds a sample Rust driver demonstrating the usage of the fwctl Rust abstractions. Add sample code for creating a FwCtl device, getting device info and issuing an RPC. Cc: Danilo Krummrich <dakr@kernel.org> Cc: Jason Gunthorpe <jgg@nvidia.com> Signed-off-by: Zhi Wang <zhiw@nvidia.com> --- samples/rust/Kconfig | 11 +++ samples/rust/Makefile | 1 + samples/rust/rust_driver_fwctl.rs | 136 ++++++++++++++++++++++++++++++ 3 files changed, 148 insertions(+) create mode 100644 samples/rust/rust_driver_fwctl.rs diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig index XXXXXXX..XXXXXXX 100644 --- a/samples/rust/Kconfig +++ b/samples/rust/Kconfig @@ -XXX,XX +XXX,XX @@ config SAMPLE_RUST_SOC If unsure, say N. +config SAMPLE_RUST_DRIVER_FWCTL + tristate "Fwctl Driver" + depends on FWCTL + help + This option builds the Rust Fwctl driver sample. + + To compile this as a module, choose M here: + the module will be called rust_driver_fwctl. + + If unsure, say N. + config SAMPLE_RUST_HOSTPROGS bool "Host programs" help diff --git a/samples/rust/Makefile b/samples/rust/Makefile index XXXXXXX..XXXXXXX 100644 --- a/samples/rust/Makefile +++ b/samples/rust/Makefile @@ -XXX,XX +XXX,XX @@ obj-$(CONFIG_SAMPLE_RUST_DRIVER_PLATFORM) += rust_driver_platform.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_USB) += rust_driver_usb.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_FAUX) += rust_driver_faux.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_AUXILIARY) += rust_driver_auxiliary.o +obj-$(CONFIG_SAMPLE_RUST_DRIVER_FWCTL) += rust_driver_fwctl.o obj-$(CONFIG_SAMPLE_RUST_CONFIGFS) += rust_configfs.o obj-$(CONFIG_SAMPLE_RUST_SOC) += rust_soc.o diff --git a/samples/rust/rust_driver_fwctl.rs b/samples/rust/rust_driver_fwctl.rs new file mode 100644 index XXXXXXX..XXXXXXX --- /dev/null +++ b/samples/rust/rust_driver_fwctl.rs @@ -XXX,XX +XXX,XX @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Rust fwctl API test (based on QEMU's `pci-testdev`). +//! +//! To make this driver probe, QEMU must be run with `-device pci-testdev`. + +use kernel::{ + bindings, + device, + device::Core, + devres::Devres, + fwctl, + pci, + prelude::*, + sync::aref::ARef, + types, +}; + +struct FwctlSampleUserCtx { + _drvdata: u32, +} + +struct FwctlSampleOps; + +impl fwctl::Operations for FwctlSampleOps { + type UserCtx = FwctlSampleUserCtx; + + const DEVICE_TYPE: fwctl::DeviceType = fwctl::DeviceType::RustFwctlTest; + + fn open( + fwctl_uctx: &types::Opaque<bindings::fwctl_uctx> + ) -> Result<impl PinInit<Self::UserCtx, Error>, Error> { + let dev = fwctl::UserCtx::<Self::UserCtx>::parent_device_from_raw(fwctl_uctx); + + dev_info!(dev, "fwctl test driver: open_uctx()"); + + // Return an initializer for the user context. + // The framework will initialize this in-place in the C-allocated memory. + Ok(try_init!(FwctlSampleUserCtx { + _drvdata: 0, + })) + } + + fn close(uctx: &mut fwctl::UserCtx<FwctlSampleUserCtx>) { + let dev = uctx.get_parent_device(); + + dev_info!(dev, "fwctl test driver: close_uctx()"); + } + + fn info(uctx: &mut fwctl::UserCtx<FwctlSampleUserCtx>) -> Result<KVec<u8>, Error> { + let dev = uctx.get_parent_device(); + + dev_info!(dev, "fwctl test driver: info()"); + + let mut infobuf = KVec::<u8>::new(); + infobuf.push(0xef, GFP_KERNEL)?; + infobuf.push(0xbe, GFP_KERNEL)?; + infobuf.push(0xad, GFP_KERNEL)?; + infobuf.push(0xde, GFP_KERNEL)?; + + Ok(infobuf) + } + + fn fw_rpc( + uctx: &mut fwctl::UserCtx<FwctlSampleUserCtx>, + scope: u32, + rpc_in: &mut [u8], + _out_len: *mut usize, + ) -> Result<Option<KVec<u8>>, Error> { + let dev = uctx.get_parent_device(); + + dev_info!(dev, "fwctl test driver: fw_rpc() scope {}", scope); + + if rpc_in.len() != 4 { + return Err(EINVAL); + } + + dev_info!( + dev, + "fwctl test driver: inbuf len{} bytes[0-3] {:x} {:x} {:x} {:x}", + rpc_in.len(), + rpc_in[0], + rpc_in[1], + rpc_in[2], + rpc_in[3] + ); + + let mut outbuf = KVec::<u8>::new(); + outbuf.push(0xef, GFP_KERNEL)?; + outbuf.push(0xbe, GFP_KERNEL)?; + outbuf.push(0xad, GFP_KERNEL)?; + outbuf.push(0xde, GFP_KERNEL)?; + + Ok(Some(outbuf)) + } +} + +#[pin_data] +struct FwctlSampleDriver { + pdev: ARef<pci::Device>, + #[pin] + fwctl: Devres<fwctl::Registration<FwctlSampleOps>>, +} + +kernel::pci_device_table!( + PCI_TABLE, + MODULE_PCI_TABLE, + <FwctlSampleDriver as pci::Driver>::IdInfo, + [(pci::DeviceId::from_id(pci::Vendor::REDHAT, 0x5), ())] +); + +impl pci::Driver for FwctlSampleDriver { + type IdInfo = (); + const ID_TABLE: pci::IdTable<Self::IdInfo> = &PCI_TABLE; + + fn probe(pdev: &pci::Device<Core>, _info: &Self::IdInfo) -> impl PinInit<Self, Error> { + dev_info!(pdev.as_ref(), "Probe fwctl test driver"); + + // `pdev` is `Device<Core>`, which derefs to `Device<Bound>` during probe. + let pdev_bound: &pci::Device<device::Bound> = pdev; + + try_pin_init!(Self { + pdev: pdev.into(), + fwctl <- fwctl::Registration::<FwctlSampleOps>::new(pdev_bound.as_ref()), + }) + } +} + +kernel::module_pci_driver! { + type: FwctlSampleDriver, + name: "rust_driver_fwctl", + authors: ["Zhi Wang"], + description: "Rust fwctl test", + license: "GPL v2", + imports_ns: ["FWCTL"], +} -- 2.51.0 In the NVIDIA vGPU RFC [1], the vGPU type blobs must be provided to the GSP before userspace can enumerate available vGPU types and create vGPU instances. The original design relied on the firmware loading interface, but fwctl is a more natural fit for this use case, as it is designed for uploading configuration or firmware data required before the device becomes operational. This series introduces a Rust abstraction over the fwctl subsystem, providing safe and idiomatic bindings. The series is a single patch. `Registration` owns the callback-visible driver data and ties it to the parent device binding lifetime using a GAT on `Operations`. `Device<T>` remains the refcounted fwctl object, while callbacks borrow registration data for the callback lifetime. The Rust fwctl module provides: - `Operations`: driver-specific `open()`, `close()`, `info()`, and `fw_rpc()` callbacks. The implementing type is the per-FD user context. - `RegistrationData<'a>`: a GAT associated type owned by `Registration` and borrowed by callbacks under the fwctl registration lock. - `Device<T>`: a refcounted wrapper around `struct fwctl_device`. - `Registration<T>`: registration and automatic unregistration, including verification that the supplied bound parent is the device's actual parent. - `RpcScope` and `FwRpcResponse`: type-safe RPC scope and response handling. The safe callback receives the userspace output-buffer size as a numeric value, while raw output-length pointer handling remains confined to the abstraction. `DeviceType` intentionally models every valid, non-error `fwctl_device_type` UAPI value rather than the set of existing Rust drivers. This preserves a typed interface while making `FWCTL_DEVICE_TYPE_ERROR` and arbitrary integers unrepresentable. Device-specific Rust consumers can add new variants together with their UAPI allocation. `rust/kernel/lib.rs` conditionally includes the module under `CONFIG_RUST_FWCTL_ABSTRACTIONS`. This series is based on drm-rust-next commit d85845b64c00 ("gpu: nova-core: build SetRegistry entries dynamically"), so Nova can build on it directly. Danilo suggested taking it through the DRM tree; Jason, please let us know if you would prefer it to go through the fwctl tree. v7: - Rebase onto the latest drm-rust-next. - Pad fwctl allocation sizes for Rust alignment. (Danilo, Alexandre) - Validate the actual parent in `Registration::new()`. (Alexandre, Danilo) - Add an HRTB helper and remove the lifetime transmute. (Alexandre) - Pass `max_output_len` to safe RPC callbacks. (Alexandre, Joel) - Write `out_len` once. (Alexandre) - Return `NULL` for empty RPC replies. (Danilo) - Convert allocation results to `NonNull` immediately. (Alexandre, Gary) - Simplify callback lifetimes and raw pointer use. (Danilo, Alexandre) - Make `VTable` and `VTABLE` private. (Danilo) - Remove manual `Registration` `Send`/`Sync` impls. (Alexandre) - Tighten the rustdoc and safety comments. (Alexandre) - Document `DeviceType` as the non-error UAPI domain. (Danilo) - Update the FWCTL `MAINTAINERS` entry. (Miguel, Danilo) - Add Danilo's `Signed-off-by` trailer. (Danilo) Link to v6: [2] Links to the v6 reviews: [8] [9] [10] v6: - Use a GAT lifetime for `Operations::RegistrationData<'a>` instead of requiring `ForLt`. (Danilo) - Require `FWCTL=y` for `RUST_FWCTL_ABSTRACTIONS`. - Add `#[inline]` to small forwarding helpers. - Return `EINVAL` for an unrecognized RPC scope. Link to Danilo's GAT diff: [3] Link to v5: [4] v5: - Rebase on top of drm-rust-next. - Adopt Danilo's higher-ranked lifetime model for callback-visible registration data. - Drop the fwctl core release hook patch. - Reject `FwRpcResponse::InPlace(len)` when `len` exceeds the input buffer. - Add the missing BNXT fwctl device type. - Document the registration exclusivity requirements. Link to v4: [5] v4: - Rebase on top of drm-rust-next. - Split out the fwctl core release hook. - Drop the already-merged fwctl init-ordering change. - Add compile-time layout checks. (Jason) - Use `const_assert!()` for generic layout assertions. - Require `Operations` and its data to be `Send + Sync`. (Danilo) - Pass pinned shared references to `info()` and `fw_rpc()`. (Danilo) - Return an initializer directly from `open()`. (Danilo) - Fix clippy and rustdoc warnings. (Danilo) Link to v3: [6] v3: - Use an enum for the RPC response. (Joel) - Remove the test UAPI and sample driver. (Jason, John) - Remove `DeviceType::Error` and add fwctl reference helpers. (Gary) - Refine device-private data ownership. (Danilo) - Separate allocation and registration. (Jason) - Tie registration to a bound parent device. (Danilo) - Make the implementing type the per-FD context. (Danilo) An example nova-core fwctl consumer is available at [7]. v2: - Use a Rust helper for `fwctl_put()`. (Jason, Danilo) - Guarantee registration lifetime management. (Jason, Danilo) - Rename the main abstraction types and use a typed device identifier. (Danilo) - Improve pointer casts, reference counting, safety comments, and clippy cleanliness. v1: - Initial submission introducing fwctl Rust abstractions. [1] https://lore.kernel.org/all/20250903221111.3866249-1-zhiw@nvidia.com/ [2] https://lore.kernel.org/r/20260629150156.3169384-1-zhiw@nvidia.com/ [3] https://lore.kernel.org/r/DJJW7X4ESDSM.QCVYK2FC7ZR3@kernel.org/ [4] https://lore.kernel.org/r/20260629103946.3117152-1-zhiw@nvidia.com/ [5] https://lore.kernel.org/r/20260624091758.1678092-1-zhiw@nvidia.com/ [6] https://lore.kernel.org/r/20260217204909.211793-1-zhiw@nvidia.com/ [7] https://lore.kernel.org/r/20260305190936.398590-1-zhiw@nvidia.com/ [8] https://lore.kernel.org/r/DJQ1KX0O60J7.Q3RUZ46V153O@kernel.org/ [9] https://lore.kernel.org/r/DJR76RV8NEKN.2MP5M9Z66U4TY@nvidia.com/ [10] https://lore.kernel.org/r/DJRH022OWTTK.1KPQDQHKG7CTF@garyguo.net/ Zhi Wang (1): rust: introduce abstractions for fwctl MAINTAINERS | 2 + drivers/fwctl/Kconfig | 12 + rust/bindings/bindings_helper.h | 1 + rust/helpers/fwctl.c | 17 + rust/helpers/helpers.c | 3 +- rust/kernel/fwctl.rs | 578 ++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 7 files changed, 614 insertions(+), 1 deletion(-) create mode 100644 rust/helpers/fwctl.c create mode 100644 rust/kernel/fwctl.rs base-commit: d85845b64c0020b2812243a22fa79d57cc1c1e38 -- 2.51.0 Introduce safe Rust wrappers around struct fwctl_device and struct fwctl_uctx. This lets Rust drivers register fwctl devices and implement firmware RPC callbacks through a typed trait interface. The abstraction keeps lifetime and reference-count handling inside the wrapper, exposes pinned per-FD user contexts to drivers, and validates the layout assumptions required by the C fwctl allocation model. Allocation sizes are padded so the kmalloc-backed C allocations also satisfy Rust alignment requirements. Registration owns driver private data with a lifetime tied to the bound parent device and verifies the parent identity before registration. Callbacks access that data through a higher-ranked closure, preventing its erased lifetime from escaping, while Device remains only the refcounted fwctl object. This avoids requiring Rust drop glue from the fwctl_device release path after unregister or module teardown. RPC callbacks receive typed scope information, a mutable request/response buffer, and the userspace output-buffer size. Response pointer conversion, length validation, and raw output-length handling remain inside the abstraction. Add the Rust sources to the FWCTL MAINTAINERS entry. Co-developed-by: Danilo Krummrich <dakr@kernel.org> Signed-off-by: Danilo Krummrich <dakr@kernel.org> Link: https://lore.kernel.org/r/DJJW7X4ESDSM.QCVYK2FC7ZR3@kernel.org Link: https://lore.kernel.org/r/20260629150156.3169384-2-zhiw@nvidia.com Signed-off-by: Zhi Wang <zhiw@nvidia.com> --- MAINTAINERS | 2 + drivers/fwctl/Kconfig | 12 + rust/bindings/bindings_helper.h | 1 + rust/helpers/fwctl.c | 17 + rust/helpers/helpers.c | 3 +- rust/kernel/fwctl.rs | 578 ++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 7 files changed, 614 insertions(+), 1 deletion(-) create mode 100644 rust/helpers/fwctl.c create mode 100644 rust/kernel/fwctl.rs diff --git a/MAINTAINERS b/MAINTAINERS index XXXXXXX..XXXXXXX 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -XXX,XX +XXX,XX @@ F: Documentation/userspace-api/fwctl/ F: drivers/fwctl/ F: include/linux/fwctl.h F: include/uapi/fwctl/ +F: rust/helpers/fwctl.c +F: rust/kernel/fwctl.rs FWCTL BNXT DRIVER M: Pavan Chebbi <pavan.chebbi@broadcom.com> diff --git a/drivers/fwctl/Kconfig b/drivers/fwctl/Kconfig index XXXXXXX..XXXXXXX 100644 --- a/drivers/fwctl/Kconfig +++ b/drivers/fwctl/Kconfig @@ -XXX,XX +XXX,XX @@ menuconfig FWCTL fit neatly into an existing subsystem. if FWCTL + +config RUST_FWCTL_ABSTRACTIONS + bool "Rust fwctl abstractions" + depends on RUST && FWCTL=y + help + This enables the Rust abstractions for the fwctl device firmware + access framework. It provides safe wrappers around struct fwctl_device + and struct fwctl_uctx, allowing Rust drivers to register fwctl devices + and implement their control and RPC logic in safe Rust. + + If unsure, say N. + config FWCTL_BNXT tristate "bnxt control fwctl driver" depends on BNXT diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h index XXXXXXX..XXXXXXX 100644 --- a/rust/bindings/bindings_helper.h +++ b/rust/bindings/bindings_helper.h @@ -XXX,XX +XXX,XX @@ #include <linux/fdtable.h> #include <linux/file.h> #include <linux/firmware.h> +#include <linux/fwctl.h> #include <linux/fs.h> #include <linux/i2c.h> #include <linux/interrupt.h> diff --git a/rust/helpers/fwctl.c b/rust/helpers/fwctl.c new file mode 100644 index XXXXXXX..XXXXXXX --- /dev/null +++ b/rust/helpers/fwctl.c @@ -XXX,XX +XXX,XX @@ +// SPDX-License-Identifier: GPL-2.0 + +#include <linux/fwctl.h> + +#if IS_ENABLED(CONFIG_RUST_FWCTL_ABSTRACTIONS) + +__rust_helper struct fwctl_device *rust_helper_fwctl_get(struct fwctl_device *fwctl) +{ + return fwctl_get(fwctl); +} + +__rust_helper void rust_helper_fwctl_put(struct fwctl_device *fwctl) +{ + fwctl_put(fwctl); +} + +#endif diff --git a/rust/helpers/helpers.c b/rust/helpers/helpers.c index XXXXXXX..XXXXXXX 100644 --- a/rust/helpers/helpers.c +++ b/rust/helpers/helpers.c @@ -XXX,XX +XXX,XX @@ #include "drm.c" #include "drm_gpuvm.c" #include "err.c" -#include "irq.c" #include "fs.c" +#include "fwctl.c" #include "gpu.c" #include "io.c" +#include "irq.c" #include "jump_label.c" #include "kunit.c" #include "list.c" diff --git a/rust/kernel/fwctl.rs b/rust/kernel/fwctl.rs new file mode 100644 index XXXXXXX..XXXXXXX --- /dev/null +++ b/rust/kernel/fwctl.rs @@ -XXX,XX +XXX,XX @@ +// SPDX-License-Identifier: GPL-2.0-only + +//! Abstractions for the fwctl subsystem. +//! +//! C header: `include/linux/fwctl.h` + +use crate::{ + bindings, + container_of, + device, + prelude::*, + sync::aref::{ + ARef, + AlwaysRefCounted, // + }, + types::Opaque, // +}; +use core::{ + alloc::Layout, + cell::UnsafeCell, + marker::PhantomData, + ptr::NonNull, + slice, // +}; + +/// Returns a kmalloc-compatible allocation size for `T`. +const fn kmalloc_aligned_size<T>() -> usize { + Layout::new::<T>().pad_to_align().size() +} + +/// Represents a fwctl device type. +/// +/// Corresponds to the C `enum fwctl_device_type`. All non-error UAPI values are represented so +/// Rust drivers can select a device type without passing an untyped integer, while +/// `FWCTL_DEVICE_TYPE_ERROR` remains unrepresentable. +#[repr(u32)] +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +pub enum DeviceType { + /// Mellanox ConnectX (mlx5) device. + Mlx5 = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_MLX5, + /// CXL (Compute Express Link) device. + Cxl = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_CXL, + /// AMD/Pensando PDS device. + Pds = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_PDS, + /// Broadcom NetXtreme (bnxt) device. + Bnxt = bindings::fwctl_device_type_FWCTL_DEVICE_TYPE_BNXT, +} + +impl From<DeviceType> for u32 { + fn from(device_type: DeviceType) -> Self { + device_type as u32 + } +} + +/// Scope of access for an RPC request. +/// +/// Corresponds to the C `enum fwctl_rpc_scope`. +#[repr(u32)] +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +pub enum RpcScope { + /// Read/write access to device configuration. + Configuration = bindings::fwctl_rpc_scope_FWCTL_RPC_CONFIGURATION, + /// Read-only access to debug information. + DebugReadOnly = bindings::fwctl_rpc_scope_FWCTL_RPC_DEBUG_READ_ONLY, + /// Write access to lockdown-compatible debug information. + DebugWrite = bindings::fwctl_rpc_scope_FWCTL_RPC_DEBUG_WRITE, + /// Full read/write access to all debug information (requires `CAP_SYS_RAWIO`). + DebugWriteFull = bindings::fwctl_rpc_scope_FWCTL_RPC_DEBUG_WRITE_FULL, +} + +impl TryFrom<u32> for RpcScope { + type Error = Error; + + #[inline] + fn try_from(value: u32) -> Result<Self, Error> { + match value { + v if v == Self::Configuration as u32 => Ok(Self::Configuration), + v if v == Self::DebugReadOnly as u32 => Ok(Self::DebugReadOnly), + v if v == Self::DebugWrite as u32 => Ok(Self::DebugWrite), + v if v == Self::DebugWriteFull as u32 => Ok(Self::DebugWriteFull), + _ => Err(EINVAL), + } + } +} + +/// Response from a [`Operations::fw_rpc`] call. +pub enum FwRpcResponse { + /// Reuse the input buffer as the output, with the given output length. + InPlace(usize), + /// Return a newly allocated buffer as the output. + NewBuffer(KVec<u8>), +} + +/// Trait implemented by each Rust driver that integrates with the fwctl subsystem. +/// +/// The implementing type **is** the per-FD user context: one instance is +/// created for each `open()` call and dropped when the FD is closed. +/// +/// Each implementation corresponds to a specific device type and provides the +/// vtable used by the core `fwctl` layer to manage per-FD user contexts and +/// handle RPC requests. +pub trait Operations: Sized + Send + Sync + 'static { + /// Data owned by the [`Registration`] and accessible during callbacks. + /// + /// The lifetime `'a` is tied to the [`Registration`] scope (which lives within the parent bus + /// device binding scope). Drivers use it to store references to resources bound to this scope, + /// such as PCI BARs or typed bus device references. + type RegistrationData<'a>: Send + Sync + 'a + where + Self: 'a; + + /// fwctl device type identifier. + const DEVICE_TYPE: DeviceType; + + /// Called when a new user context is opened. + /// + /// Returns a [`PinInit`] initializer for `Self`. The instance is dropped + /// automatically when the FD is closed (after [`close`](Self::close)). + fn open<'a>( + device: &Device<Self>, + reg_data: &Self::RegistrationData<'a>, + ) -> impl PinInit<Self, Error>; + + /// Called when the user context is closed. + /// + /// The driver may perform additional cleanup here that requires access + /// to the owning [`Device`]. `Self` is dropped automatically after this + /// returns. + fn close<'a>( + _this: Pin<&mut Self>, + _device: &Device<Self>, + _reg_data: &Self::RegistrationData<'a>, + ) { + } + + /// Return device information to userspace. + /// + /// The default implementation returns no device-specific data. + fn info<'a>( + _this: Pin<&Self>, + _device: &Device<Self>, + _reg_data: &Self::RegistrationData<'a>, + ) -> Result<KVec<u8>, Error> { + Ok(KVec::new()) + } + + /// Handle a userspace RPC request. + /// + /// `max_output_len` is the size of the userspace output buffer. A driver may return a larger + /// response to report the required size; the fwctl core copies only the bytes that fit and + /// reports the full response length to userspace. + fn fw_rpc<'a>( + this: Pin<&Self>, + device: &Device<Self>, + reg_data: &Self::RegistrationData<'a>, + scope: RpcScope, + rpc_buf: &mut [u8], + max_output_len: usize, + ) -> Result<FwRpcResponse, Error>; +} + +/// A fwctl device. +/// +/// `#[repr(C)]` with the `fwctl_device` at offset 0, matching the C `fwctl_alloc_device()` layout +/// convention. Contains a pointer to the [`Registration`]'s data, set at registration time and +/// cleared on unregistration. +/// +/// # Invariants +/// +/// - `dev` is embedded at offset 0 and is initialised by fwctl. +/// - The fwctl refcount owns the allocation lifetime. +/// - `registration_data` is either `NonNull::dangling()` (before registration / after +/// unregistration) or points to valid data owned by the [`Registration`]. +#[repr(C)] +pub struct Device<T: Operations> { + dev: Opaque<bindings::fwctl_device>, + registration_data: UnsafeCell<NonNull<T::RegistrationData<'static>>>, +} + +impl<T: Operations> Device<T> { + /// Allocate a new fwctl device. + /// + /// Returns an [`ARef`] that can be passed to [`Registration::new()`] + /// to make the device visible to userspace. + pub fn new(parent: &device::Device<device::Bound>) -> Result<ARef<Self>> { + const_assert!( + core::mem::offset_of!(Self, dev) == 0, + "struct fwctl_device must be at offset 0" + ); + + let size = kmalloc_aligned_size::<Self>(); + let ops = core::ptr::from_ref::<bindings::fwctl_ops>(&VTable::<T>::VTABLE).cast_mut(); + + // SAFETY: `ops` is static, `parent` is bound, and `size` is padded so the allocation made + // by `_fwctl_alloc_device` satisfies the size and alignment required by `Device<T>`. + let raw = unsafe { bindings::_fwctl_alloc_device(parent.as_raw(), ops, size) }; + let this = NonNull::new(raw.cast::<Self>()).ok_or(ENOMEM)?; + + // INVARIANT: Set `registration_data` to dangling (no registration yet). + // SAFETY: `this` points to the allocation just returned by fwctl. + unsafe { + (&raw mut (*this.as_ptr()).registration_data) + .write(UnsafeCell::new(NonNull::dangling())); + }; + + // SAFETY: `this` owns the initial reference. + Ok(unsafe { ARef::from_raw(this) }) + } + + #[inline] + fn as_raw(&self) -> *mut bindings::fwctl_device { + self.dev.get() + } + + /// # Safety + /// + /// `ptr` must point to a valid `fwctl_device` embedded in a [`Device<T>`]. + #[inline] + unsafe fn from_raw<'a>(ptr: *mut bindings::fwctl_device) -> &'a Self { + // SAFETY: The caller upholds the offset-0 `Device<T>` invariant. + unsafe { &*ptr.cast() } + } + + /// Invokes `f` with the registration data. + /// + /// The higher-ranked callback prevents the erased registration lifetime from escaping and + /// permits registration data that is invariant over its lifetime parameter. + /// + /// # Safety + /// + /// The caller must ensure that the device is registered and that this is called from a fwctl + /// callback protected by `registration_lock`. + #[inline] + unsafe fn with_registration_data<R>( + &self, + f: impl for<'a> FnOnce(&Device<T>, &'a T::RegistrationData<'a>) -> R, + ) -> R { + // SAFETY: Caller guarantees the device is registered, so the pointer is valid. + // Lifetimes do not affect layout. The higher-ranked callback prevents the shortened + // lifetime from escaping or being selected by the caller. + let reg_data = unsafe { + (*self.registration_data.get()) + .cast::<T::RegistrationData<'_>>() + .as_ref() + }; + + f(self, reg_data) + } +} + +impl<T: Operations> AsRef<device::Device> for Device<T> { + #[inline] + fn as_ref(&self) -> &device::Device { + // SAFETY: `self` contains a live fwctl_device. + let dev = unsafe { &raw mut (*self.as_raw()).dev }; + // SAFETY: The embedded device is initialised by fwctl. + unsafe { device::Device::from_raw(dev) } + } +} + +// SAFETY: `fwctl_get` increments the refcount of a valid fwctl_device. +// `fwctl_put` decrements it and frees the device when it reaches zero. +unsafe impl<T: Operations> AlwaysRefCounted for Device<T> { + #[inline] + fn inc_ref(&self) { + // SAFETY: `self` holds a live reference. + unsafe { bindings::fwctl_get(self.as_raw()) }; + } + + #[inline] + unsafe fn dec_ref(obj: NonNull<Self>) { + // SAFETY: The caller owns a live reference. + unsafe { bindings::fwctl_put(obj.cast().as_ptr()) }; + } +} + +// SAFETY: `Device<T>` is refcounted by the fwctl core and may be released from any thread. +unsafe impl<T: Operations> Send for Device<T> {} + +// SAFETY: Shared access to the embedded `fwctl_device` is protected by the fwctl core. The +// `registration_data` field is only mutated before registration and after unregistration (both +// single-threaded with respect to callbacks). +unsafe impl<T: Operations> Sync for Device<T> {} + +/// A registered fwctl device. +/// +/// Owns the [`RegistrationData`](Operations::RegistrationData) made available to driver callbacks. +/// The parent device lifetime ensures that [`fwctl_unregister`] runs before the parent driver +/// unbinds. +/// +/// On drop the device is unregistered (all user contexts are closed and `ops` is set to `NULL`) +/// and the registration data is dropped. +/// +/// [`fwctl_unregister`]: srctree/drivers/fwctl/main.c +pub struct Registration<'a, T: Operations> { + dev: ARef<Device<T>>, + _reg_data: Pin<KBox<T::RegistrationData<'a>>>, +} + +impl<'a, T: Operations> Registration<'a, T> { + /// Register a previously allocated fwctl device with the given registration data. + /// + /// The `reg_data` is owned by the registration and accessible during callbacks. + /// + /// # Safety + /// + /// Callers must not `mem::forget()` the returned [`Registration`] or otherwise prevent its + /// [`Drop`] implementation from running, since `fwctl_unregister` must be called before the + /// parent device is unbound. + /// + /// `dev` must be an unregistered [`Device`] that is not associated with any live + /// [`Registration`], and no other thread may attempt to register the same device concurrently. + pub unsafe fn new( + parent: &'a device::Device<device::Bound>, + dev: &Device<T>, + reg_data: impl PinInit<T::RegistrationData<'a>, Error>, + ) -> Result<Self> { + let actual_parent = dev.as_ref().parent().ok_or(EINVAL)?; + let parent_device: &device::Device = parent; + if !core::ptr::eq(actual_parent, parent_device) { + return Err(EINVAL); + } + + let reg_data: Pin<KBox<T::RegistrationData<'a>>> = KBox::pin_init(reg_data, GFP_KERNEL)?; + + // Store the registration data pointer in the device before registration, so that it is + // visible once callbacks can be invoked. The `'static` type is only an erased storage + // handle; callbacks access the pointer through a higher-ranked closure. + let ptr: NonNull<T::RegistrationData<'static>> = + NonNull::from(Pin::get_ref(reg_data.as_ref())).cast(); + + // SAFETY: No concurrent access; the device is not yet registered. + unsafe { *dev.registration_data.get() = ptr }; + + // SAFETY: `dev` is a valid fwctl_device backed by an ARef. + let ret = unsafe { bindings::fwctl_register(dev.as_raw()) }; + if ret != 0 { + // SAFETY: No concurrent readers; registration failed. + unsafe { *dev.registration_data.get() = NonNull::dangling() }; + return Err(Error::from_errno(ret)); + } + + Ok(Self { + dev: dev.into(), + _reg_data: reg_data, + }) + } +} + +impl<T: Operations> Drop for Registration<'_, T> { + fn drop(&mut self) { + // SAFETY: The Registration lifetime guarantees that the parent device is still bound. + // `fwctl_unregister` takes the write lock, closes all user contexts, and sets ops=NULL. + // After it returns, no callbacks can be running or will run. + unsafe { bindings::fwctl_unregister(self.dev.as_raw()) }; + + // SAFETY: `fwctl_unregister` guarantees no concurrent readers. + unsafe { *self.dev.registration_data.get() = NonNull::dangling() }; + + // `self._reg_data` is dropped here, after callbacks have stopped. + } +} + +/// Internal per-FD user context wrapping `struct fwctl_uctx` and `T`. +/// +/// Not exposed to drivers; they work with `&T` / `Pin<&mut T>` directly. +#[repr(C)] +#[pin_data] +struct UserCtx<T: Operations> { + #[pin] + fwctl_uctx: Opaque<bindings::fwctl_uctx>, + #[pin] + uctx: T, +} + +impl<T: Operations> UserCtx<T> { + /// # Safety + /// + /// `ptr` must point to a `fwctl_uctx` embedded in a live `UserCtx<T>`. + #[inline] + unsafe fn from_raw<'a>(ptr: *mut bindings::fwctl_uctx) -> &'a Self { + // SAFETY: The caller upholds the `UserCtx<T>` embedding invariant. + unsafe { &*container_of!(Opaque::cast_from(ptr), Self, fwctl_uctx) } + } + + /// # Safety + /// + /// `ptr` must point to a `fwctl_uctx` embedded in a live `UserCtx<T>`. + /// The caller must ensure exclusive access to the `UserCtx<T>`. + #[inline] + unsafe fn from_raw_mut<'a>(ptr: *mut bindings::fwctl_uctx) -> &'a mut Self { + // SAFETY: The caller upholds the embedding and exclusivity invariants. + unsafe { &mut *container_of!(Opaque::cast_from(ptr), Self, fwctl_uctx).cast_mut() } + } + + /// Returns a reference to the fwctl [`Device`] that owns this context. + #[inline] + fn device(&self) -> &Device<T> { + // SAFETY: fwctl initialises this pointer before any driver callback. + let raw_fwctl = unsafe { (*self.fwctl_uctx.get()).fwctl }; + // SAFETY: Rust fwctl devices use the offset-0 `Device<T>` layout. + unsafe { Device::from_raw(raw_fwctl) } + } +} + +/// Static vtable mapping Rust trait methods to C callbacks. +struct VTable<T: Operations>(PhantomData<T>); + +impl<T: Operations> VTable<T> { + /// The fwctl operations vtable for this driver type. + const VTABLE: bindings::fwctl_ops = bindings::fwctl_ops { + device_type: T::DEVICE_TYPE as u32, + uctx_size: kmalloc_aligned_size::<UserCtx<T>>(), + open_uctx: Some(Self::open_uctx_callback), + close_uctx: Some(Self::close_uctx_callback), + info: Some(Self::info_callback), + fw_rpc: Some(Self::fw_rpc_callback), + }; + + /// # Safety + /// + /// `uctx` must be a valid `fwctl_uctx` embedded in a `UserCtx<T>` with + /// sufficient allocated space for the uctx field. + unsafe extern "C" fn open_uctx_callback(uctx: *mut bindings::fwctl_uctx) -> ffi::c_int { + const_assert!( + core::mem::offset_of!(UserCtx<T>, fwctl_uctx) == 0, + "struct fwctl_uctx must be at offset 0" + ); + + // SAFETY: fwctl sets this pointer before calling `open_uctx`. + let raw_fwctl = unsafe { (*uctx).fwctl }; + // SAFETY: Rust fwctl devices use the offset-0 `Device<T>` layout. + let device = unsafe { Device::<T>::from_raw(raw_fwctl) }; + + let uctx_offset = core::mem::offset_of!(UserCtx<T>, uctx); + // SAFETY: `uctx_size` reserves space for the full `UserCtx<T>`. + let uctx_ptr: *mut T = unsafe { uctx.byte_add(uctx_offset).cast() }; + + // SAFETY: `open_uctx` is called under `registration_lock` read, so the device is + // registered. `uctx_ptr` addresses the uninitialised pinned context reserved by + // `uctx_size`. + unsafe { + device.with_registration_data(|device, reg_data| { + match T::open(device, reg_data).__pinned_init(uctx_ptr) { + Ok(()) => 0, + Err(e) => e.to_errno(), + } + }) + } + } + + /// # Safety + /// + /// `uctx` must point to a fully initialised `UserCtx<T>`. + unsafe extern "C" fn close_uctx_callback(uctx: *mut bindings::fwctl_uctx) { + // SAFETY: fwctl keeps the owning device live for this callback. + let device = unsafe { Device::<T>::from_raw((*uctx).fwctl) }; + + // SAFETY: close is called for an opened Rust user context. + let ctx = unsafe { UserCtx::<T>::from_raw_mut(uctx) }; + + // SAFETY: `close_uctx` is called under `registration_lock` write (from + // `fwctl_unregister`) or read (from `fwctl_fops_release`), so the device is registered. + // fwctl never moves an opened user context. + unsafe { + device.with_registration_data(|device, reg_data| { + T::close(Pin::new_unchecked(&mut ctx.uctx), device, reg_data); + }); + } + + // SAFETY: close is the last callback before fwctl frees the allocation. + unsafe { core::ptr::drop_in_place(&mut ctx.uctx) }; + } + + /// # Safety + /// + /// `uctx` must point to a fully initialised `UserCtx<T>`. + /// `length` must be a valid pointer. + unsafe extern "C" fn info_callback( + uctx: *mut bindings::fwctl_uctx, + length: *mut usize, + ) -> *mut ffi::c_void { + // SAFETY: info is called for an opened Rust user context. + let ctx = unsafe { UserCtx::<T>::from_raw(uctx) }; + let device = ctx.device(); + + // SAFETY: `info` is called under `registration_lock` read, so the device is registered. + // fwctl never moves an opened user context. + let result = unsafe { + device.with_registration_data(|device, reg_data| { + T::info(Pin::new_unchecked(&ctx.uctx), device, reg_data) + }) + }; + + match result { + Ok(kvec) if kvec.is_empty() => { + // SAFETY: `length` is a valid out-parameter. + unsafe { *length = 0 }; + // Return NULL for empty data; kfree(NULL) is safe. + core::ptr::null_mut() + } + Ok(kvec) => { + let (ptr, len, _cap) = kvec.into_raw_parts(); + // SAFETY: `length` is a valid out-parameter. + unsafe { *length = len }; + ptr.cast::<ffi::c_void>() + } + Err(e) => Error::to_ptr(e), + } + } + + /// # Safety + /// + /// `uctx` must point to a fully initialised `UserCtx<T>`. + /// `rpc_in` must be valid, initialised, and exclusively accessible for `in_len` bytes. + /// `out_len` must be valid for reading and writing an initialised `usize`. + unsafe extern "C" fn fw_rpc_callback( + uctx: *mut bindings::fwctl_uctx, + scope: u32, + rpc_in: *mut ffi::c_void, + in_len: usize, + out_len: *mut usize, + ) -> *mut ffi::c_void { + let scope = match RpcScope::try_from(scope) { + Ok(s) => s, + Err(e) => return Error::to_ptr(e), + }; + + // SAFETY: `out_len` points to the userspace output buffer length supplied by fwctl. + let max_output_len = unsafe { *out_len }; + + // SAFETY: RPC is called for an opened Rust user context. + let ctx = unsafe { UserCtx::<T>::from_raw(uctx) }; + let device = ctx.device(); + + // SAFETY: fwctl passes an exclusively owned buffer that is valid and initialised for + // `in_len` bytes. It remains live for the duration of this callback. + let rpc_buf: &mut [u8] = unsafe { slice::from_raw_parts_mut(rpc_in.cast::<u8>(), in_len) }; + + // SAFETY: `fw_rpc` is called under `registration_lock` read, so the device is registered. + // fwctl never moves an opened user context. + let result = unsafe { + device.with_registration_data(|device, reg_data| { + T::fw_rpc( + Pin::new_unchecked(&ctx.uctx), + device, + reg_data, + scope, + rpc_buf, + max_output_len, + ) + }) + }; + + let (response, response_len) = match result { + Ok(FwRpcResponse::InPlace(len)) => { + if len > in_len { + return Error::to_ptr(EINVAL); + } + + (rpc_in, len) + } + Ok(FwRpcResponse::NewBuffer(kvec)) if kvec.is_empty() => { + // Return NULL for empty data; kvfree(NULL) is safe. + (core::ptr::null_mut(), 0) + } + Ok(FwRpcResponse::NewBuffer(kvec)) => { + let (ptr, len, _cap) = kvec.into_raw_parts(); + (ptr.cast::<ffi::c_void>(), len) + } + Err(e) => return Error::to_ptr(e), + }; + + // SAFETY: `out_len` is a valid out-parameter. + unsafe { *out_len = response_len }; + response + } +} diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index XXXXXXX..XXXXXXX 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -XXX,XX +XXX,XX @@ pub mod firmware; pub mod fmt; pub mod fs; +#[cfg(CONFIG_RUST_FWCTL_ABSTRACTIONS)] +pub mod fwctl; #[cfg(CONFIG_GPU_BUDDY = "y")] pub mod gpu; #[cfg(CONFIG_I2C = "y")] -- 2.51.0