* [PATCH v2 1/4] rust: types: add `Opaque::zeroed`
2025-03-13 2:23 [PATCH v2 0/4] Auxiliary bus Rust abstractions Danilo Krummrich
@ 2025-03-13 2:23 ` Danilo Krummrich
2025-03-13 2:23 ` [PATCH v2 2/4] rust: auxiliary: add auxiliary device / driver abstractions Danilo Krummrich
` (3 subsequent siblings)
4 siblings, 0 replies; 10+ messages in thread
From: Danilo Krummrich @ 2025-03-13 2:23 UTC (permalink / raw)
To: gregkh, rafael, ojeda, alex.gaynor, boqun.feng, gary, bjorn3_gh,
benno.lossin, a.hindborg, aliceryhl, tmgross, airlied, acourbot,
jhubbard
Cc: linux-kernel, rust-for-linux, Danilo Krummrich
Analogous to `Opaque::uninit` add `Opaque::zeroed`, which sets the
corresponding memory to zero. In contrast to `Opaque::uninit`, the
corresponding value, depending on its type, may be initialized.
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
rust/kernel/types.rs | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index 2bbaab83b9d6..f5e7fed903a7 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -326,6 +326,14 @@ pub const fn uninit() -> Self {
}
}
+ /// Creates a new zeroed opaque value.
+ pub const fn zeroed() -> Self {
+ Self {
+ value: UnsafeCell::new(MaybeUninit::zeroed()),
+ _pin: PhantomPinned,
+ }
+ }
+
/// Create an opaque pin-initializer from the given pin-initializer.
pub fn pin_init(slot: impl PinInit<T>) -> impl PinInit<Self> {
Self::ffi_init(|ptr: *mut T| {
--
2.48.1
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH v2 2/4] rust: auxiliary: add auxiliary device / driver abstractions
2025-03-13 2:23 [PATCH v2 0/4] Auxiliary bus Rust abstractions Danilo Krummrich
2025-03-13 2:23 ` [PATCH v2 1/4] rust: types: add `Opaque::zeroed` Danilo Krummrich
@ 2025-03-13 2:23 ` Danilo Krummrich
2025-03-13 2:23 ` [PATCH v2 3/4] rust: auxiliary: add auxiliary registration Danilo Krummrich
` (2 subsequent siblings)
4 siblings, 0 replies; 10+ messages in thread
From: Danilo Krummrich @ 2025-03-13 2:23 UTC (permalink / raw)
To: gregkh, rafael, ojeda, alex.gaynor, boqun.feng, gary, bjorn3_gh,
benno.lossin, a.hindborg, aliceryhl, tmgross, airlied, acourbot,
jhubbard
Cc: linux-kernel, rust-for-linux, Danilo Krummrich
Implement the basic auxiliary abstractions required to implement a
driver matching an auxiliary device.
The design and implementation is analogous to PCI and platform and is
based on the generic device / driver abstractions.
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
MAINTAINERS | 1 +
rust/bindings/bindings_helper.h | 1 +
rust/helpers/auxiliary.c | 23 +++
rust/helpers/helpers.c | 1 +
rust/kernel/auxiliary.rs | 267 ++++++++++++++++++++++++++++++++
rust/kernel/lib.rs | 2 +
6 files changed, 295 insertions(+)
create mode 100644 rust/helpers/auxiliary.c
create mode 100644 rust/kernel/auxiliary.rs
diff --git a/MAINTAINERS b/MAINTAINERS
index f5c7022937a7..0a737b28cdfa 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7114,6 +7114,7 @@ F: include/linux/kobj*
F: include/linux/property.h
F: include/linux/sysfs.h
F: lib/kobj*
+F: rust/kernel/auxiliary.rs
F: rust/kernel/device.rs
F: rust/kernel/device_id.rs
F: rust/kernel/devres.rs
diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
index f46cf3bb7069..83026b6e53b2 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -7,6 +7,7 @@
*/
#include <kunit/test.h>
+#include <linux/auxiliary_bus.h>
#include <linux/blk-mq.h>
#include <linux/blk_types.h>
#include <linux/blkdev.h>
diff --git a/rust/helpers/auxiliary.c b/rust/helpers/auxiliary.c
new file mode 100644
index 000000000000..0db3860d774e
--- /dev/null
+++ b/rust/helpers/auxiliary.c
@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: GPL-2.0
+
+#include <linux/auxiliary_bus.h>
+
+void rust_helper_auxiliary_set_drvdata(struct auxiliary_device *adev, void *data)
+{
+ auxiliary_set_drvdata(adev, data);
+}
+
+void *rust_helper_auxiliary_get_drvdata(struct auxiliary_device *adev)
+{
+ return auxiliary_get_drvdata(adev);
+}
+
+void rust_helper_auxiliary_device_uninit(struct auxiliary_device *adev)
+{
+ return auxiliary_device_uninit(adev);
+}
+
+void rust_helper_auxiliary_device_delete(struct auxiliary_device *adev)
+{
+ return auxiliary_device_delete(adev);
+}
diff --git a/rust/helpers/helpers.c b/rust/helpers/helpers.c
index 0640b7e115be..d744af85e3b2 100644
--- a/rust/helpers/helpers.c
+++ b/rust/helpers/helpers.c
@@ -7,6 +7,7 @@
* Sorted alphabetically.
*/
+#include "auxiliary.c"
#include "blk.c"
#include "bug.c"
#include "build_assert.c"
diff --git a/rust/kernel/auxiliary.rs b/rust/kernel/auxiliary.rs
new file mode 100644
index 000000000000..e453f821f7cb
--- /dev/null
+++ b/rust/kernel/auxiliary.rs
@@ -0,0 +1,267 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Abstractions for the auxiliary bus.
+//!
+//! C header: [`include/linux/auxiliary_bus.h`](srctree/include/linux/auxiliary_bus.h)
+
+use crate::{
+ bindings, device,
+ device_id::RawDeviceId,
+ driver,
+ error::{to_result, Result},
+ prelude::*,
+ str::CStr,
+ types::{ForeignOwnable, Opaque},
+ ThisModule,
+};
+use core::{
+ marker::PhantomData,
+ ops::Deref,
+ ptr::{addr_of_mut, NonNull},
+};
+
+/// An adapter for the registration of auxiliary drivers.
+pub struct Adapter<T: Driver>(T);
+
+// SAFETY: A call to `unregister` for a given instance of `RegType` is guaranteed to be valid if
+// a preceding call to `register` has been successful.
+unsafe impl<T: Driver + 'static> driver::RegistrationOps for Adapter<T> {
+ type RegType = bindings::auxiliary_driver;
+
+ unsafe fn register(
+ adrv: &Opaque<Self::RegType>,
+ name: &'static CStr,
+ module: &'static ThisModule,
+ ) -> Result {
+ // SAFETY: It's safe to set the fields of `struct auxiliary_driver` on initialization.
+ unsafe {
+ (*adrv.get()).name = name.as_char_ptr();
+ (*adrv.get()).probe = Some(Self::probe_callback);
+ (*adrv.get()).remove = Some(Self::remove_callback);
+ (*adrv.get()).id_table = T::ID_TABLE.as_ptr();
+ }
+
+ // SAFETY: `adrv` is guaranteed to be a valid `RegType`.
+ to_result(unsafe {
+ bindings::__auxiliary_driver_register(adrv.get(), module.0, name.as_char_ptr())
+ })
+ }
+
+ unsafe fn unregister(adrv: &Opaque<Self::RegType>) {
+ // SAFETY: `adrv` is guaranteed to be a valid `RegType`.
+ unsafe { bindings::auxiliary_driver_unregister(adrv.get()) }
+ }
+}
+
+impl<T: Driver + 'static> Adapter<T> {
+ extern "C" fn probe_callback(
+ adev: *mut bindings::auxiliary_device,
+ id: *const bindings::auxiliary_device_id,
+ ) -> core::ffi::c_int {
+ // SAFETY: The auxiliary bus only ever calls the probe callback with a valid pointer to a
+ // `struct auxiliary_device`.
+ //
+ // INVARIANT: `adev` is valid for the duration of `probe_callback()`.
+ let adev = unsafe { &*adev.cast::<Device<device::Core>>() };
+
+ // SAFETY: `DeviceId` is a `#[repr(transparent)` wrapper of `struct auxiliary_device_id` and
+ // does not add additional invariants, so it's safe to transmute.
+ let id = unsafe { &*id.cast::<DeviceId>() };
+ let info = T::ID_TABLE.info(id.index());
+
+ match T::probe(adev, info) {
+ Ok(data) => {
+ // Let the `struct auxiliary_device` own a reference of the driver's private data.
+ // SAFETY: By the type invariant `adev.as_raw` returns a valid pointer to a
+ // `struct auxiliary_device`.
+ unsafe { bindings::auxiliary_set_drvdata(adev.as_raw(), data.into_foreign()) };
+ }
+ Err(err) => return Error::to_errno(err),
+ }
+
+ 0
+ }
+
+ extern "C" fn remove_callback(adev: *mut bindings::auxiliary_device) {
+ // SAFETY: The auxiliary bus only ever calls the remove callback with a valid pointer to a
+ // `struct auxiliary_device`.
+ let ptr = unsafe { bindings::auxiliary_get_drvdata(adev) };
+
+ // SAFETY: `remove_callback` is only ever called after a successful call to
+ // `probe_callback`, hence it's guaranteed that `ptr` points to a valid and initialized
+ // `KBox<T>` pointer created through `KBox::into_foreign`.
+ let _ = unsafe { KBox::<T>::from_foreign(ptr) };
+ }
+}
+
+/// Declares a kernel module that exposes a single auxiliary driver.
+#[macro_export]
+macro_rules! module_auxiliary_driver {
+ ($($f:tt)*) => {
+ $crate::module_driver!(<T>, $crate::auxiliary::Adapter<T>, { $($f)* });
+ };
+}
+
+/// Abstraction for `bindings::auxiliary_device_id`.
+#[repr(transparent)]
+#[derive(Clone, Copy)]
+pub struct DeviceId(bindings::auxiliary_device_id);
+
+impl DeviceId {
+ /// Create a new [`DeviceId`] from name.
+ pub const fn new(modname: &'static CStr, name: &'static CStr) -> Self {
+ let name = name.as_bytes_with_nul();
+ let modname = modname.as_bytes_with_nul();
+
+ // TODO: Replace with `bindings::auxiliary_device_id::default()` once stabilized for
+ // `const`.
+ //
+ // SAFETY: FFI type is valid to be zero-initialized.
+ let mut id: bindings::auxiliary_device_id = unsafe { core::mem::zeroed() };
+
+ let mut i = 0;
+ while i < modname.len() {
+ id.name[i] = modname[i];
+ i += 1;
+ }
+
+ // Reuse the space of the NULL terminator.
+ id.name[i - 1] = b'.';
+
+ let mut j = 0;
+ while j < name.len() {
+ id.name[i] = name[j];
+ i += 1;
+ j += 1;
+ }
+
+ Self(id)
+ }
+}
+
+// SAFETY:
+// * `DeviceId` is a `#[repr(transparent)` wrapper of `auxiliary_device_id` and does not add
+// additional invariants, so it's safe to transmute to `RawType`.
+// * `DRIVER_DATA_OFFSET` is the offset to the `driver_data` field.
+unsafe impl RawDeviceId for DeviceId {
+ type RawType = bindings::auxiliary_device_id;
+
+ const DRIVER_DATA_OFFSET: usize =
+ core::mem::offset_of!(bindings::auxiliary_device_id, driver_data);
+
+ fn index(&self) -> usize {
+ self.0.driver_data
+ }
+}
+
+/// IdTable type for auxiliary drivers.
+pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;
+
+/// Create a auxiliary `IdTable` with its alias for modpost.
+#[macro_export]
+macro_rules! auxiliary_device_table {
+ ($table_name:ident, $module_table_name:ident, $id_info_type: ty, $table_data: expr) => {
+ const $table_name: $crate::device_id::IdArray<
+ $crate::auxiliary::DeviceId,
+ $id_info_type,
+ { $table_data.len() },
+ > = $crate::device_id::IdArray::new($table_data);
+
+ $crate::module_device_table!("auxiliary", $module_table_name, $table_name);
+ };
+}
+
+/// The auxiliary driver trait.
+///
+/// Drivers must implement this trait in order to get an auxiliary driver registered.
+pub trait Driver {
+ /// The type holding information about each device id supported by the driver.
+ ///
+ /// TODO: Use associated_type_defaults once stabilized:
+ ///
+ /// type IdInfo: 'static = ();
+ type IdInfo: 'static;
+
+ /// The table of device ids supported by the driver.
+ const ID_TABLE: IdTable<Self::IdInfo>;
+
+ /// Auxiliary driver probe.
+ ///
+ /// Called when a new auxiliary device is added or discovered. Implementers should attempt
+ /// to initialize the device here.
+ fn probe(dev: &Device<device::Core>, id_info: &Self::IdInfo) -> Result<Pin<KBox<Self>>>;
+}
+
+/// The auxiliary device representation.
+///
+/// This structure represents the Rust abstraction for a C `struct auxiliary_device`. The
+/// implementation abstracts the usage of an already existing C `struct auxiliary_device` within
+/// Rust code that we get passed from the C side.
+///
+/// # Invariants
+///
+/// A [`Device`] instance represents a valid `struct auxiliary_device` created by the C portion of
+/// the kernel.
+#[repr(transparent)]
+pub struct Device<Ctx: device::DeviceContext = device::Normal>(
+ Opaque<bindings::auxiliary_device>,
+ PhantomData<Ctx>,
+);
+
+impl Device {
+ fn as_raw(&self) -> *mut bindings::auxiliary_device {
+ self.0.get()
+ }
+
+ /// Returns the auxiliary device' id.
+ pub fn id(&self) -> u32 {
+ // SAFETY: By the type invariant `self.as_raw()` is a valid pointer to a
+ // `struct auxiliary_device`.
+ unsafe { (*self.as_raw()).id }
+ }
+}
+
+impl Deref for Device<device::Core> {
+ type Target = Device;
+
+ fn deref(&self) -> &Self::Target {
+ let ptr: *const Self = self;
+
+ // CAST: `Device<Ctx>` is a transparent wrapper of `Opaque<bindings::auxiliary_device>`.
+ let ptr = ptr.cast::<Device>();
+
+ // SAFETY: `ptr` was derived from `&self`.
+ unsafe { &*ptr }
+ }
+}
+
+// SAFETY: Instances of `Device` are always reference-counted.
+unsafe impl crate::types::AlwaysRefCounted for Device {
+ fn inc_ref(&self) {
+ // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
+ unsafe { bindings::get_device(self.as_ref().as_raw()) };
+ }
+
+ unsafe fn dec_ref(obj: NonNull<Self>) {
+ // CAST: `Self` a transparent wrapper of `bindings::auxiliary_device`.
+ let adev: *mut bindings::auxiliary_device = obj.cast().as_ptr();
+
+ // SAFETY: By the type invariant of `Self`, `adev` is a pointer to a valid
+ // `struct auxiliary_device`.
+ let dev = unsafe { addr_of_mut!((*adev).dev) };
+
+ // SAFETY: The safety requirements guarantee that the refcount is non-zero.
+ unsafe { bindings::put_device(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 auxiliary_device`.
+ let dev = unsafe { addr_of_mut!((*self.as_raw()).dev) };
+
+ // SAFETY: `dev` points to a valid `struct device`.
+ unsafe { device::Device::as_ref(dev) }
+ }
+}
diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index 398242f92a96..d9a2ca9d1f20 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -36,6 +36,8 @@
pub use ffi;
pub mod alloc;
+#[cfg(CONFIG_AUXILIARY_BUS)]
+pub mod auxiliary;
#[cfg(CONFIG_BLOCK)]
pub mod block;
#[doc(hidden)]
--
2.48.1
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH v2 3/4] rust: auxiliary: add auxiliary registration
2025-03-13 2:23 [PATCH v2 0/4] Auxiliary bus Rust abstractions Danilo Krummrich
2025-03-13 2:23 ` [PATCH v2 1/4] rust: types: add `Opaque::zeroed` Danilo Krummrich
2025-03-13 2:23 ` [PATCH v2 2/4] rust: auxiliary: add auxiliary device / driver abstractions Danilo Krummrich
@ 2025-03-13 2:23 ` Danilo Krummrich
2025-03-17 20:42 ` Benoît du Garreau
2025-03-13 2:23 ` [PATCH v2 4/4] samples: rust: add Rust auxiliary driver sample Danilo Krummrich
2025-03-17 7:05 ` [PATCH v2 0/4] Auxiliary bus Rust abstractions Greg KH
4 siblings, 1 reply; 10+ messages in thread
From: Danilo Krummrich @ 2025-03-13 2:23 UTC (permalink / raw)
To: gregkh, rafael, ojeda, alex.gaynor, boqun.feng, gary, bjorn3_gh,
benno.lossin, a.hindborg, aliceryhl, tmgross, airlied, acourbot,
jhubbard
Cc: linux-kernel, rust-for-linux, Danilo Krummrich
Implement the `auxiliary::Registration` type, which provides an API to
create and register new auxiliary devices in the system.
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
rust/kernel/auxiliary.rs | 80 +++++++++++++++++++++++++++++++++++++++-
1 file changed, 79 insertions(+), 1 deletion(-)
diff --git a/rust/kernel/auxiliary.rs b/rust/kernel/auxiliary.rs
index e453f821f7cb..fc4bb5388a9b 100644
--- a/rust/kernel/auxiliary.rs
+++ b/rust/kernel/auxiliary.rs
@@ -5,7 +5,7 @@
//! C header: [`include/linux/auxiliary_bus.h`](srctree/include/linux/auxiliary_bus.h)
use crate::{
- bindings, device,
+ bindings, container_of, device,
device_id::RawDeviceId,
driver,
error::{to_result, Result},
@@ -219,6 +219,16 @@ pub fn id(&self) -> u32 {
// `struct auxiliary_device`.
unsafe { (*self.as_raw()).id }
}
+
+ extern "C" fn release(dev: *mut bindings::device) {
+ // SAFETY: By the type invariant `self.0.as_raw` is a pointer to the `struct device`
+ // embedded in `struct auxiliary_device`.
+ let adev = unsafe { container_of!(dev, bindings::auxiliary_device, dev) }.cast_mut();
+
+ // SAFETY: `adev` points to the memory that has been allocated in `Registration::new`, via
+ // `KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)`.
+ let _ = unsafe { KBox::<Opaque<bindings::auxiliary_device>>::from_raw(adev.cast()) };
+ }
}
impl Deref for Device<device::Core> {
@@ -265,3 +275,71 @@ fn as_ref(&self) -> &device::Device {
unsafe { device::Device::as_ref(dev) }
}
}
+
+/// The registration of an auxiliary device.
+///
+/// This type represents the registration of a [`struct auxiliary_device`]. When an instance of this
+/// type is dropped, its respective auxiliary device will be unregistered from the system.
+///
+/// # Invariants
+///
+/// `self.0` always holds a valid pointer to an initialized and registered
+/// [`struct auxiliary_device`].
+pub struct Registration(NonNull<bindings::auxiliary_device>);
+
+impl Registration {
+ /// Create and register a new auxiliary device.
+ pub fn new(parent: &device::Device, name: &CStr, id: u32, modname: &CStr) -> Result<Self> {
+ let boxed = KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)?;
+ let adev = boxed.get();
+
+ // SAFETY: It's safe to set the fields of `struct auxiliary_device` on initialization.
+ unsafe {
+ (*adev).dev.parent = parent.as_raw();
+ (*adev).dev.release = Some(Device::release);
+ (*adev).name = name.as_char_ptr();
+ (*adev).id = id;
+ }
+
+ // SAFETY: `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`,
+ // which has not been initialized yet.
+ unsafe { bindings::auxiliary_device_init(adev) };
+
+ // Now that `adev` is initialized, leak the `Box`; the corresponding memory will be freed
+ // by `Device::release` when the last reference to the `struct auxiliary_device` is dropped.
+ let _ = KBox::into_raw(boxed);
+
+ // SAFETY:
+ // - `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`, which has
+ // been initialialized,
+ // - `modname.as_char_ptr()` is a NULL terminated string.
+ let ret = unsafe { bindings::__auxiliary_device_add(adev, modname.as_char_ptr()) };
+ if ret != 0 {
+ // SAFETY: `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`,
+ // which has been initialialized.
+ unsafe { bindings::auxiliary_device_uninit(adev) };
+
+ return Err(Error::from_errno(ret));
+ }
+
+ // SAFETY: `adev` is guaranteed to be non-null, since the `KBox` was allocated successfully.
+ //
+ // INVARIANT: The device will remain registered until `auxiliary_device_delete()` is called,
+ // which happens in `Self::drop()`.
+ Ok(Self(unsafe { NonNull::new_unchecked(adev) }))
+ }
+}
+
+impl Drop for Registration {
+ fn drop(&mut self) {
+ // SAFETY: By the type invariant of `Self`, `self.0.as_ptr()` is a valid registered
+ // `struct auxiliary_device`.
+ unsafe { bindings::auxiliary_device_delete(self.0.as_ptr()) };
+
+ // This drops the reference we acquired through `auxiliary_device_init()`.
+ //
+ // SAFETY: By the type invariant of `Self`, `self.0.as_ptr()` is a valid registered
+ // `struct auxiliary_device`.
+ unsafe { bindings::auxiliary_device_uninit(self.0.as_ptr()) };
+ }
+}
--
2.48.1
^ permalink raw reply related [flat|nested] 10+ messages in thread* Re: [PATCH v2 3/4] rust: auxiliary: add auxiliary registration
2025-03-13 2:23 ` [PATCH v2 3/4] rust: auxiliary: add auxiliary registration Danilo Krummrich
@ 2025-03-17 20:42 ` Benoît du Garreau
2025-03-17 20:55 ` Danilo Krummrich
2025-03-18 18:36 ` Benno Lossin
0 siblings, 2 replies; 10+ messages in thread
From: Benoît du Garreau @ 2025-03-17 20:42 UTC (permalink / raw)
To: Danilo Krummrich
Cc: Benoît du Garreau, gregkh, rafael, ojeda, alex.gaynor,
boqun.feng, gary, bjorn3_gh, benno.lossin, a.hindborg, aliceryhl,
tmgross, airlied, acourbot, jhubbard, linux-kernel,
rust-for-linux
On Thu, 13 Mar 2025 03:23:52 +0100 Danilo Krummrich <dakr@kernel.org> wrote:
> Implement the `auxiliary::Registration` type, which provides an API to
> create and register new auxiliary devices in the system.
>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
> ---
> rust/kernel/auxiliary.rs | 80 +++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 79 insertions(+), 1 deletion(-)
>
> diff --git a/rust/kernel/auxiliary.rs b/rust/kernel/auxiliary.rs
> index e453f821f7cb..fc4bb5388a9b 100644
> --- a/rust/kernel/auxiliary.rs
> +++ b/rust/kernel/auxiliary.rs
> @@ -5,7 +5,7 @@
> //! C header: [`include/linux/auxiliary_bus.h`](srctree/include/linux/auxiliary_bus.h)
>
> use crate::{
> - bindings, device,
> + bindings, container_of, device,
> device_id::RawDeviceId,
> driver,
> error::{to_result, Result},
> @@ -219,6 +219,16 @@ pub fn id(&self) -> u32 {
> // `struct auxiliary_device`.
> unsafe { (*self.as_raw()).id }
> }
> +
> + extern "C" fn release(dev: *mut bindings::device) {
> + // SAFETY: By the type invariant `self.0.as_raw` is a pointer to the `struct device`
> + // embedded in `struct auxiliary_device`.
> + let adev = unsafe { container_of!(dev, bindings::auxiliary_device, dev) }.cast_mut();
> +
> + // SAFETY: `adev` points to the memory that has been allocated in `Registration::new`, via
> + // `KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)`.
> + let _ = unsafe { KBox::<Opaque<bindings::auxiliary_device>>::from_raw(adev.cast()) };
> + }
> }
>
> impl Deref for Device<device::Core> {
> @@ -265,3 +275,71 @@ fn as_ref(&self) -> &device::Device {
> unsafe { device::Device::as_ref(dev) }
> }
> }
> +
> +/// The registration of an auxiliary device.
> +///
> +/// This type represents the registration of a [`struct auxiliary_device`]. When an instance of this
> +/// type is dropped, its respective auxiliary device will be unregistered from the system.
> +///
> +/// # Invariants
> +///
> +/// `self.0` always holds a valid pointer to an initialized and registered
> +/// [`struct auxiliary_device`].
> +pub struct Registration(NonNull<bindings::auxiliary_device>);
> +
> +impl Registration {
> + /// Create and register a new auxiliary device.
> + pub fn new(parent: &device::Device, name: &CStr, id: u32, modname: &CStr) -> Result<Self> {
> + let boxed = KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)?;
You can use `KBox::init(kernel::init::zeroed(), GFP_KERNEL)` here. It avoids
the need for the first patch.
> + let adev = boxed.get();
> +
> + // SAFETY: It's safe to set the fields of `struct auxiliary_device` on initialization.
> + unsafe {
> + (*adev).dev.parent = parent.as_raw();
> + (*adev).dev.release = Some(Device::release);
> + (*adev).name = name.as_char_ptr();
> + (*adev).id = id;
> + }
> +
> + // SAFETY: `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`,
> + // which has not been initialized yet.
> + unsafe { bindings::auxiliary_device_init(adev) };
> +
> + // Now that `adev` is initialized, leak the `Box`; the corresponding memory will be freed
> + // by `Device::release` when the last reference to the `struct auxiliary_device` is dropped.
> + let _ = KBox::into_raw(boxed);
> +
> + // SAFETY:
> + // - `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`, which has
> + // been initialialized,
> + // - `modname.as_char_ptr()` is a NULL terminated string.
> + let ret = unsafe { bindings::__auxiliary_device_add(adev, modname.as_char_ptr()) };
> + if ret != 0 {
> + // SAFETY: `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`,
> + // which has been initialialized.
> + unsafe { bindings::auxiliary_device_uninit(adev) };
> +
> + return Err(Error::from_errno(ret));
> + }
> +
> + // SAFETY: `adev` is guaranteed to be non-null, since the `KBox` was allocated successfully.
> + //
> + // INVARIANT: The device will remain registered until `auxiliary_device_delete()` is called,
> + // which happens in `Self::drop()`.
> + Ok(Self(unsafe { NonNull::new_unchecked(adev) }))
> + }
> +}
> +
> +impl Drop for Registration {
> + fn drop(&mut self) {
> + // SAFETY: By the type invariant of `Self`, `self.0.as_ptr()` is a valid registered
> + // `struct auxiliary_device`.
> + unsafe { bindings::auxiliary_device_delete(self.0.as_ptr()) };
> +
> + // This drops the reference we acquired through `auxiliary_device_init()`.
> + //
> + // SAFETY: By the type invariant of `Self`, `self.0.as_ptr()` is a valid registered
> + // `struct auxiliary_device`.
> + unsafe { bindings::auxiliary_device_uninit(self.0.as_ptr()) };
> + }
> +}
> --
> 2.48.1
>
>
Benoît du Garreau
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: [PATCH v2 3/4] rust: auxiliary: add auxiliary registration
2025-03-17 20:42 ` Benoît du Garreau
@ 2025-03-17 20:55 ` Danilo Krummrich
2025-03-18 18:36 ` Benno Lossin
1 sibling, 0 replies; 10+ messages in thread
From: Danilo Krummrich @ 2025-03-17 20:55 UTC (permalink / raw)
To: Benoît du Garreau
Cc: gregkh, rafael, ojeda, alex.gaynor, boqun.feng, gary, bjorn3_gh,
benno.lossin, a.hindborg, aliceryhl, tmgross, airlied, acourbot,
jhubbard, linux-kernel, rust-for-linux
On Mon, Mar 17, 2025 at 09:42:51PM +0100, Benoît du Garreau wrote:
> On Thu, 13 Mar 2025 03:23:52 +0100 Danilo Krummrich <dakr@kernel.org> wrote:
>
> > +impl Registration {
> > + /// Create and register a new auxiliary device.
> > + pub fn new(parent: &device::Device, name: &CStr, id: u32, modname: &CStr) -> Result<Self> {
> > + let boxed = KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)?;
>
> You can use `KBox::init(kernel::init::zeroed(), GFP_KERNEL)` here. It avoids
> the need for the first patch.
You're right, that works indeed, the full call looks like this.
let boxed = KBox::init(kernel::init::zeroed::<Opaque::<bindings::auxiliary_device>>(), GFP_KERNEL)?;
However, I think Opaque::zeroed() reads a bit better. Unless anything speaks
against adding it, I think I prefer it as it is.
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: [PATCH v2 3/4] rust: auxiliary: add auxiliary registration
2025-03-17 20:42 ` Benoît du Garreau
2025-03-17 20:55 ` Danilo Krummrich
@ 2025-03-18 18:36 ` Benno Lossin
1 sibling, 0 replies; 10+ messages in thread
From: Benno Lossin @ 2025-03-18 18:36 UTC (permalink / raw)
To: Benoît du Garreau, Danilo Krummrich
Cc: gregkh, rafael, ojeda, alex.gaynor, boqun.feng, gary, bjorn3_gh,
a.hindborg, aliceryhl, tmgross, airlied, acourbot, jhubbard,
linux-kernel, rust-for-linux
On Mon Mar 17, 2025 at 9:42 PM CET, Benoît du Garreau wrote:
> On Thu, 13 Mar 2025 03:23:52 +0100 Danilo Krummrich <dakr@kernel.org> wrote:
>> Implement the `auxiliary::Registration` type, which provides an API to
>> +impl Registration {
>> + /// Create and register a new auxiliary device.
>> + pub fn new(parent: &device::Device, name: &CStr, id: u32, modname: &CStr) -> Result<Self> {
>> + let boxed = KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)?;
>
> You can use `KBox::init(kernel::init::zeroed(), GFP_KERNEL)` here. It avoids
> the need for the first patch.
We probably should have the zeroed function on the `Zeroable` trait...
---
Cheers,
Benno
^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH v2 4/4] samples: rust: add Rust auxiliary driver sample
2025-03-13 2:23 [PATCH v2 0/4] Auxiliary bus Rust abstractions Danilo Krummrich
` (2 preceding siblings ...)
2025-03-13 2:23 ` [PATCH v2 3/4] rust: auxiliary: add auxiliary registration Danilo Krummrich
@ 2025-03-13 2:23 ` Danilo Krummrich
2025-03-17 7:05 ` [PATCH v2 0/4] Auxiliary bus Rust abstractions Greg KH
4 siblings, 0 replies; 10+ messages in thread
From: Danilo Krummrich @ 2025-03-13 2:23 UTC (permalink / raw)
To: gregkh, rafael, ojeda, alex.gaynor, boqun.feng, gary, bjorn3_gh,
benno.lossin, a.hindborg, aliceryhl, tmgross, airlied, acourbot,
jhubbard
Cc: linux-kernel, rust-for-linux, Danilo Krummrich
Add a sample Rust auxiliary driver based on a PCI driver for QEMU's
"pci-testdev" device.
The PCI driver only registers an auxiliary device, in order to make the
corresponding auxiliary driver probe.
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
MAINTAINERS | 1 +
samples/rust/Kconfig | 12 ++++
samples/rust/Makefile | 1 +
samples/rust/rust_driver_auxiliary.rs | 99 +++++++++++++++++++++++++++
4 files changed, 113 insertions(+)
create mode 100644 samples/rust/rust_driver_auxiliary.rs
diff --git a/MAINTAINERS b/MAINTAINERS
index 0a737b28cdfa..6ec20e4f715d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7121,6 +7121,7 @@ F: rust/kernel/devres.rs
F: rust/kernel/driver.rs
F: rust/kernel/faux.rs
F: rust/kernel/platform.rs
+F: samples/rust/rust_driver_auxiliary.rs
F: samples/rust/rust_driver_platform.rs
F: samples/rust/rust_driver_faux.rs
diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig
index 3b6eae84b297..413216da1b70 100644
--- a/samples/rust/Kconfig
+++ b/samples/rust/Kconfig
@@ -71,6 +71,18 @@ config SAMPLE_RUST_DRIVER_FAUX
If unsure, say N.
+config SAMPLE_RUST_DRIVER_AUXILIARY
+ tristate "Auxiliary Driver"
+ depends on AUXILIARY_BUS
+ depends on PCI
+ help
+ This option builds the Rust auxiliary driver sample.
+
+ To compile this as a module, choose M here:
+ the module will be called rust_driver_auxiliary.
+
+ If unsure, say N.
+
config SAMPLE_RUST_HOSTPROGS
bool "Host programs"
help
diff --git a/samples/rust/Makefile b/samples/rust/Makefile
index 0dbc6d90f1ef..30a8809d0a15 100644
--- a/samples/rust/Makefile
+++ b/samples/rust/Makefile
@@ -7,6 +7,7 @@ obj-$(CONFIG_SAMPLE_RUST_PRINT) += rust_print.o
obj-$(CONFIG_SAMPLE_RUST_DRIVER_PCI) += rust_driver_pci.o
obj-$(CONFIG_SAMPLE_RUST_DRIVER_PLATFORM) += rust_driver_platform.o
obj-$(CONFIG_SAMPLE_RUST_DRIVER_FAUX) += rust_driver_faux.o
+obj-$(CONFIG_SAMPLE_RUST_DRIVER_AUXILIARY) += rust_driver_auxiliary.o
rust_print-y := rust_print_main.o rust_print_events.o
diff --git a/samples/rust/rust_driver_auxiliary.rs b/samples/rust/rust_driver_auxiliary.rs
new file mode 100644
index 000000000000..416af6210e10
--- /dev/null
+++ b/samples/rust/rust_driver_auxiliary.rs
@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Rust auxiliary driver sample (based on a PCI driver for QEMU's `pci-testdev`).
+//!
+//! To make this driver probe, QEMU must be run with `-device pci-testdev`.
+
+use kernel::{
+ auxiliary, bindings, c_str, device::Core, driver, error::Error, init, pci, prelude::*,
+ str::CStr, InPlaceModule,
+};
+
+const MODULE_NAME: &CStr = <LocalModule as kernel::ModuleMetadata>::NAME;
+const AUXILIARY_NAME: &CStr = c_str!("auxiliary");
+
+struct AuxiliaryDriver;
+
+kernel::auxiliary_device_table!(
+ AUX_TABLE,
+ MODULE_AUX_TABLE,
+ <AuxiliaryDriver as auxiliary::Driver>::IdInfo,
+ [(auxiliary::DeviceId::new(MODULE_NAME, AUXILIARY_NAME), ())]
+);
+
+impl auxiliary::Driver for AuxiliaryDriver {
+ type IdInfo = ();
+
+ const ID_TABLE: auxiliary::IdTable<Self::IdInfo> = &AUX_TABLE;
+
+ fn probe(adev: &auxiliary::Device<Core>, _info: &Self::IdInfo) -> Result<Pin<KBox<Self>>> {
+ dev_info!(
+ adev.as_ref(),
+ "Probing auxiliary driver for auxiliary device with id={}\n",
+ adev.id()
+ );
+
+ let this = KBox::new(Self, GFP_KERNEL)?;
+
+ Ok(this.into())
+ }
+}
+
+struct PciDriver {
+ _reg: [auxiliary::Registration; 2],
+}
+
+kernel::pci_device_table!(
+ PCI_TABLE,
+ MODULE_PCI_TABLE,
+ <PciDriver as pci::Driver>::IdInfo,
+ [(
+ pci::DeviceId::from_id(bindings::PCI_VENDOR_ID_REDHAT, 0x5),
+ ()
+ )]
+);
+
+impl pci::Driver for PciDriver {
+ type IdInfo = ();
+
+ const ID_TABLE: pci::IdTable<Self::IdInfo> = &PCI_TABLE;
+
+ fn probe(pdev: &pci::Device<Core>, _info: &Self::IdInfo) -> Result<Pin<KBox<Self>>> {
+ let this = KBox::new(
+ Self {
+ _reg: [
+ auxiliary::Registration::new(pdev.as_ref(), AUXILIARY_NAME, 0, MODULE_NAME)?,
+ auxiliary::Registration::new(pdev.as_ref(), AUXILIARY_NAME, 1, MODULE_NAME)?,
+ ],
+ },
+ GFP_KERNEL,
+ )?;
+
+ Ok(this.into())
+ }
+}
+
+#[pin_data]
+struct SampleModule {
+ #[pin]
+ _pci_driver: driver::Registration<pci::Adapter<PciDriver>>,
+ #[pin]
+ _aux_driver: driver::Registration<auxiliary::Adapter<AuxiliaryDriver>>,
+}
+
+impl InPlaceModule for SampleModule {
+ fn init(module: &'static kernel::ThisModule) -> impl init::PinInit<Self, Error> {
+ try_pin_init!(Self {
+ _pci_driver <- driver::Registration::new(MODULE_NAME, module),
+ _aux_driver <- driver::Registration::new(MODULE_NAME, module),
+ })
+ }
+}
+
+module! {
+ type: SampleModule,
+ name: "rust_driver_auxiliary",
+ author: "Danilo Krummrich",
+ description: "Rust auxiliary driver",
+ license: "GPL v2",
+}
--
2.48.1
^ permalink raw reply related [flat|nested] 10+ messages in thread* Re: [PATCH v2 0/4] Auxiliary bus Rust abstractions
2025-03-13 2:23 [PATCH v2 0/4] Auxiliary bus Rust abstractions Danilo Krummrich
` (3 preceding siblings ...)
2025-03-13 2:23 ` [PATCH v2 4/4] samples: rust: add Rust auxiliary driver sample Danilo Krummrich
@ 2025-03-17 7:05 ` Greg KH
2025-03-17 11:33 ` Danilo Krummrich
4 siblings, 1 reply; 10+ messages in thread
From: Greg KH @ 2025-03-17 7:05 UTC (permalink / raw)
To: Danilo Krummrich
Cc: rafael, ojeda, alex.gaynor, boqun.feng, gary, bjorn3_gh,
benno.lossin, a.hindborg, aliceryhl, tmgross, airlied, acourbot,
jhubbard, linux-kernel, rust-for-linux
On Thu, Mar 13, 2025 at 03:23:49AM +0100, Danilo Krummrich wrote:
> This series adds Rust abstractions for the auxiliary bus.
>
> It implements the required abstractions to write auxiliary drivers and create
> auxiliary device registrations. A driver sample illustrates how the
> corresponding abstractions work.
>
> The auxiliary abstractions are required for the Nova driver project, in order to
> connect nova-core with the nova-drm driver.
>
> This patch series depends on [1] (taken through the nova tree for v6.15) and
> [2]; a branch containing the patches, including the dependency can be found in
> [3].
>
> [1] https://lore.kernel.org/rust-for-linux/20250306222336.23482-2-dakr@kernel.org/
> [2] https://lore.kernel.org/lkml/20250313021550.133041-1-dakr@kernel.org/
> [3] https://web.git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=rust/auxiliary
As this seems to depend on different branches in different trees, I'll
hold off on applying these to my tree now. But if you want to take
them sooner (i.e. before 6.15-rc1), that's fine with me:
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: [PATCH v2 0/4] Auxiliary bus Rust abstractions
2025-03-17 7:05 ` [PATCH v2 0/4] Auxiliary bus Rust abstractions Greg KH
@ 2025-03-17 11:33 ` Danilo Krummrich
0 siblings, 0 replies; 10+ messages in thread
From: Danilo Krummrich @ 2025-03-17 11:33 UTC (permalink / raw)
To: Greg KH
Cc: rafael, ojeda, alex.gaynor, boqun.feng, gary, bjorn3_gh,
benno.lossin, a.hindborg, aliceryhl, tmgross, airlied, acourbot,
jhubbard, linux-kernel, rust-for-linux
On Mon, Mar 17, 2025 at 08:05:46AM +0100, Greg KH wrote:
> On Thu, Mar 13, 2025 at 03:23:49AM +0100, Danilo Krummrich wrote:
> > This series adds Rust abstractions for the auxiliary bus.
> >
> > It implements the required abstractions to write auxiliary drivers and create
> > auxiliary device registrations. A driver sample illustrates how the
> > corresponding abstractions work.
> >
> > The auxiliary abstractions are required for the Nova driver project, in order to
> > connect nova-core with the nova-drm driver.
> >
> > This patch series depends on [1] (taken through the nova tree for v6.15) and
> > [2]; a branch containing the patches, including the dependency can be found in
> > [3].
> >
> > [1] https://lore.kernel.org/rust-for-linux/20250306222336.23482-2-dakr@kernel.org/
> > [2] https://lore.kernel.org/lkml/20250313021550.133041-1-dakr@kernel.org/
> > [3] https://web.git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=rust/auxiliary
>
> As this seems to depend on different branches in different trees, I'll
> hold off on applying these to my tree now. But if you want to take
> them sooner (i.e. before 6.15-rc1), that's fine with me:
>
> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Thanks! I wouldn't take them for the upcoming merge window, but maybe for the
next one through the nova tree.
^ permalink raw reply [flat|nested] 10+ messages in thread