[PATCH v2 1/2] rust: introduce abstractions for fwctl

Zhi Wang
2026-01-22T20:45:32Z

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 b5583b12a011..d8538249f3ae 100644
--- a/drivers/fwctl/Kconfig
+++ b/drivers/fwctl/Kconfig
@@ -8,6 +8,18 @@ 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 716ac0eee42d..eea1020ad180 100644
--- a/include/uapi/fwctl/fwctl.h
+++ b/include/uapi/fwctl/fwctl.h
@@ -45,6 +45,7 @@ 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 9fdf76ca630e..2c50d5bab0cf 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -56,6 +56,7 @@
#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 000000000000..bb4a028e7afb
--- /dev/null
+++ b/rust/helpers/fwctl.c
@@ -0,0 +1,17 @@
+// 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 79c72762ad9c..19a505473bef 100644
--- a/rust/helpers/helpers.c
+++ b/rust/helpers/helpers.c
@@ -27,8 +27,9 @@
#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 000000000000..4065c948784d
--- /dev/null
+++ b/rust/kernel/fwctl.rs
@@ -0,0 +1,456 @@
+// 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 6d637e2fed1b..956e865c17ea 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -97,6 +97,8 @@
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