Skip to contentSkip to conversation

Auxiliary bus Rust abstractions

PATCH In review Danilo Krummrich 4 participants 18 messages Apr 14, 2025 – Apr 19, 2025

Subsystems (3)
lore
Share & tools
lore

Danilo Krummrich

author maintainer
#0 lore raw

v4 cover Auxiliary bus Rust abstractions

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.

A branch containing the patches can be found in [1].

[1] https://web.git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=rust/auxiliary

Changes in v4:
- drop TryFrom<&Device> for &auxiliary::Device for now; we likely don't need it anytime soon
- sample: rename PciDriver to ParentDriver; add connect() to ParentDriver
- rebase onto https://lore.kernel.org/rust-for-linux/[email protected]/

Changes in v3:
- export auxiliary_bus_type
- implement impl TryFrom<&Device> for &auxiliary::Device
- implement Send + Sync for Registration and Device

Changes in v2:
- implement bus device soundness improvements from [2]

Danilo Krummrich (5):
rust: types: add Opaque::zeroed
rust: device: implement Device::parent()
rust: auxiliary: add auxiliary device / driver abstractions
rust: auxiliary: add auxiliary registration
samples: rust: add Rust auxiliary driver sample

 MAINTAINERS                           |   3 +
 rust/bindings/bindings_helper.h       |   1 +
 rust/helpers/auxiliary.c              |  23 ++
 rust/helpers/helpers.c                |   1 +
 rust/kernel/auxiliary.rs              | 360 ++++++++++++++++++++++++++
 rust/kernel/device.rs                 |  18 ++
 rust/kernel/lib.rs                    |   2 +
 rust/kernel/types.rs                  |   8 +
 samples/rust/Kconfig                  |  12 +
 samples/rust/Makefile                 |   1 +
 samples/rust/rust_driver_auxiliary.rs | 122 +++++++++
 11 files changed, 551 insertions(+)
 create mode 100644 rust/helpers/auxiliary.c
 create mode 100644 rust/kernel/auxiliary.rs
 create mode 100644 samples/rust/rust_driver_auxiliary.rs
Signature · 1 line
2.49.0
author maintainer
#1 lore raw

PATCH v4 1/5 rust: types: add `Opaque::zeroed`

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.

---
 rust/kernel/types.rs | 8 ++++++++
 1 file changed, 8 insertions(+)
rust/kernel/types.rs +8 -0
index 9d0471afc964..eee387727d1a 100644
@@ -329,6 +329,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| {
Signature · 1 line
2.49.0
author maintainer
#3 lore raw

Re: [PATCH v4 1/5] rust: types: add `Opaque::zeroed`

Quoted 9 lines · Alice Ryhl
Quoted 6 lines · 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.

@Miguel: Can I get an ACK for taking this one through the nova tree?

Acked-by
#4 lore raw

Re: [PATCH v4 1/5] rust: types: add `Opaque::zeroed`

Quoted 2 lines · Danilo Krummrich

@Miguel: Can I get an ACK for taking this one through the nova tree?

Sure, please go ahead.

Thanks!

Cheers,
Miguel

author maintainer
#5 lore raw

PATCH v4 2/5 rust: device: implement Device::parent()

In reply to Danilo Krummrich

Device::parent() returns a reference to the device' parent device, if any.

---
 rust/kernel/device.rs | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
rust/kernel/device.rs +19 -0
index 585a3fcfeea3..911045e32c34 100644
@@ -67,6 +67,25 @@ pub(crate) fn as_raw(&self) -> *mut bindings::device {
         self.0.get()
     }
 
+    /// Returns a reference to the parent device, if any.
+    #[expect(unused)]
+    pub(crate) fn parent(&self) -> Option<&Self> {
+        // SAFETY:
+        // - By the type invariant `self.as_raw()` is always valid.
+        // - The parent device is only ever set at device creation.
+        let parent = unsafe { (*self.as_raw()).parent };
+
+        if parent.is_null() {
+            None
+        } else {
+            // SAFETY:
+            // - Since `parent` is not NULL, it must be a valid pointer to a `struct device`.
+            // - `parent` is valid for the lifetime of `self`, since a `struct device` holds a
+            //   reference count of its parent.
+            Some(unsafe { Self::as_ref(parent) })
+        }
+    }
+
     /// Convert a raw C `struct device` pointer to a `&'a Device`.
     ///
     /// # Safety
Signature · 1 line
2.49.0
author maintainer
#6 lore raw

PATCH v4 3/5 rust: auxiliary: add auxiliary device / driver abstractions

In reply to 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.

---
 MAINTAINERS                     |   2 +
 rust/bindings/bindings_helper.h |   1 +
 rust/helpers/auxiliary.c        |  23 +++
 rust/helpers/helpers.c          |   1 +
 rust/kernel/auxiliary.rs        | 274 ++++++++++++++++++++++++++++++++
 rust/kernel/device.rs           |   1 -
 rust/kernel/lib.rs              |   2 +
 7 files changed, 303 insertions(+), 1 deletion(-)
 create mode 100644 rust/helpers/auxiliary.c
 create mode 100644 rust/kernel/auxiliary.rs
MAINTAINERS +2 -0
index 96b827049501..a7bc29ca37d4 100644
@@ -3872,6 +3872,8 @@ T:	git git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git
 F:	Documentation/driver-api/auxiliary_bus.rst
 F:	drivers/base/auxiliary.c
 F:	include/linux/auxiliary_bus.h
+F:	rust/kernel/auxiliary.rs
+F:	samples/rust/rust_driver_auxiliary.rs
 
 AUXILIARY DISPLAY DRIVERS
 M:	Andy Shevchenko <[email protected]>
rust/bindings/bindings_helper.h +1 -0
index ab37e1d35c70..8a2add69e5d6 100644
@@ -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>
rust/helpers/auxiliary.c new file +23 -0
new file mode 100644
index 000000000000..0db3860d774e
@@ -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);
+}
rust/helpers/helpers.c +1 -0
index e1c21eba9b15..6b279279cb12 100644
@@ -7,6 +7,7 @@
  * Sorted alphabetically.
  */
 
+#include "auxiliary.c"
 #include "blk.c"
 #include "bug.c"
 #include "build_assert.c"
rust/kernel/auxiliary.rs new file +274 -0

274 lines not on this page · raw message

rust/kernel/device.rs +0 -1
index 911045e32c34..bbd308b8c694 100644
@@ -68,7 +68,6 @@ pub(crate) fn as_raw(&self) -> *mut bindings::device {
     }
 
     /// Returns a reference to the parent device, if any.
-    #[expect(unused)]
     pub(crate) fn parent(&self) -> Option<&Self> {
         // SAFETY:
         // - By the type invariant `self.as_raw()` is always valid.
rust/kernel/lib.rs +2 -0
index de07aadd1ff5..55a8dfeece0b 100644
@@ -38,6 +38,8 @@
 pub use ffi;
 
 pub mod alloc;
+#[cfg(CONFIG_AUXILIARY_BUS)]
+pub mod auxiliary;
 #[cfg(CONFIG_BLOCK)]
 pub mod block;
 #[doc(hidden)]
Signature · 1 line
2.49.0
reviewer Reviewed-by on v4 3/5
#7 lore raw

Re: [PATCH v4 3/5] rust: auxiliary: add auxiliary device / driver abstractions

Quoted 8 lines · 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.

Overall looks okay to me, but I do have some comments.

Quoted 132 lines
 MAINTAINERS                     |   2 +
 rust/bindings/bindings_helper.h |   1 +
 rust/helpers/auxiliary.c        |  23 +++
 rust/helpers/helpers.c          |   1 +
 rust/kernel/auxiliary.rs        | 274 ++++++++++++++++++++++++++++++++
 rust/kernel/device.rs           |   1 -
 rust/kernel/lib.rs              |   2 +
 7 files changed, 303 insertions(+), 1 deletion(-)
 create mode 100644 rust/helpers/auxiliary.c
 create mode 100644 rust/kernel/auxiliary.rs
MAINTAINERS +2 -0
index 96b827049501..a7bc29ca37d4 100644
@@ -3872,6 +3872,8 @@ T:	git git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git
 F:	Documentation/driver-api/auxiliary_bus.rst
 F:	drivers/base/auxiliary.c
 F:	include/linux/auxiliary_bus.h
+F:	rust/kernel/auxiliary.rs
+F:	samples/rust/rust_driver_auxiliary.rs
 
 AUXILIARY DISPLAY DRIVERS
 M:	Andy Shevchenko <[email protected]>
rust/bindings/bindings_helper.h +1 -0
index ab37e1d35c70..8a2add69e5d6 100644
@@ -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>
rust/helpers/auxiliary.c new file +23 -0
new file mode 100644
index 000000000000..0db3860d774e
@@ -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);
+}
rust/helpers/helpers.c +1 -0
index e1c21eba9b15..6b279279cb12 100644
@@ -7,6 +7,7 @@
  * Sorted alphabetically.
  */
 
+#include "auxiliary.c"
 #include "blk.c"
 #include "bug.c"
 #include "build_assert.c"
rust/kernel/auxiliary.rs new file +49 -0
new file mode 100644
index 000000000000..75423737032a
@@ -0,0 +1,274 @@
+// 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,
+    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>) {

rust/kernel/auxiliary.rs line 59

Quoted 10 lines
rust/kernel/auxiliary.rs new file +10 -0
+        // 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 {

We shouldn't use core::ffi.

rust/kernel/auxiliary.rs line 66

Quoted 7 lines
rust/kernel/auxiliary.rs new file +7 -0
+        // 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

Typo: missing ]

Quoted 16 lines
rust/kernel/auxiliary.rs new file +16 -0
+        // 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
+    }

rust/kernel/auxiliary.rs line 92

Quoted 10 lines
rust/kernel/auxiliary.rs new file +10 -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) };

Nit: isn't this usually written

    drop(unsafe { KBox::<T>::from_foreign(ptr) });

?

Quoted 40 lines
rust/kernel/auxiliary.rs new file +40 -0
+    }
+}
+
+/// 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];

rust/kernel/auxiliary.rs line 142

Quoted 10 lines
rust/kernel/auxiliary.rs new file +10 -0
+            i += 1;
+            j += 1;
+        }
+
+        Self(id)
+    }
+}
+
+// SAFETY:
+// * `DeviceId` is a `#[repr(transparent)` wrapper of `auxiliary_device_id` and does not add

Typo: missing ]

Quoted 160 lines
rust/kernel/auxiliary.rs new file +132 -0
+//   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 an auxiliary device is matches a corresponding driver.
+    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<Ctx: device::DeviceContext> Device<Ctx> {
+    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 }
+    }
+
+    /// Returns a reference to the parent [`device::Device`], if any.
+    pub fn parent(&self) -> Option<&device::Device> {
+        let ptr: *const Self = self;
+        // CAST: `Device<Ctx: DeviceContext>` types are transparent to each other.
+        let ptr: *const Device = ptr.cast();
+        // SAFETY: `ptr` was derived from `&self`.
+        let this = unsafe { &*ptr };
+
+        this.as_ref().parent()
+    }
+}
+
+// SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
+// argument.
+kernel::impl_device_context_deref!(unsafe { Device });
+kernel::impl_device_context_into_aref!(Device);
+
+// 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<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
+    fn as_ref(&self) -> &device::Device<Ctx> {
+        // 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) }
+    }
+}
+
+// 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 of `Device`
+// (i.e. `Device<Normal>) are thread safe.
+unsafe impl Sync for Device {}
rust/kernel/device.rs +0 -1
index 911045e32c34..bbd308b8c694 100644
@@ -68,7 +68,6 @@ pub(crate) fn as_raw(&self) -> *mut bindings::device {
     }
 
     /// Returns a reference to the parent device, if any.
-    #[expect(unused)]
     pub(crate) fn parent(&self) -> Option<&Self> {
         // SAFETY:
         // - By the type invariant `self.as_raw()` is always valid.
rust/kernel/lib.rs +2 -0
index de07aadd1ff5..55a8dfeece0b 100644
@@ -38,6 +38,8 @@
 pub use ffi;
 
 pub mod alloc;
+#[cfg(CONFIG_AUXILIARY_BUS)]
+pub mod auxiliary;
 #[cfg(CONFIG_BLOCK)]
 pub mod block;
 #[doc(hidden)]
Signature · 1 line
2.49.0
author maintainer
#8 lore raw

Re: [PATCH v4 3/5] rust: auxiliary: add auxiliary device / driver abstractions

Quoted 11 lines · Alice Ryhl
Quoted 8 lines · 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.

Overall looks okay to me, but I do have some comments.

Thanks for reviewing; unless there are more comments, I'll address those when applying the series.

Quoted 1 line
author maintainer
#9 lore raw

PATCH v4 4/5 rust: auxiliary: add auxiliary registration

In reply to Danilo Krummrich

Implement the auxiliary::Registration type, which provides an API to create and register new auxiliary devices in the system.

---
 rust/kernel/auxiliary.rs | 88 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)
rust/kernel/auxiliary.rs +87 -1
index 75423737032a..b40d663b42eb 100644
@@ -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},
@@ -230,6 +230,18 @@ pub fn parent(&self) -> Option<&device::Device> {
     }
 }
 
+impl Device {
+    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()) };
+    }
+}
+
 // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
 // argument.
 kernel::impl_device_context_deref!(unsafe { Device });
@@ -272,3 +284,77 @@ unsafe impl Send for Device {}
 // SAFETY: `Device` can be shared among threads because all methods of `Device`
 // (i.e. `Device<Normal>) are thread safe.
 unsafe impl Sync for Device {}
+
+/// 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()) };
+    }
+}
+
+// SAFETY: A `Registration` of a `struct auxiliary_device` can be released from any thread.
+unsafe impl Send for Registration {}
+
+// SAFETY: `Registration` does not expose any methods or fields that need synchronization.
+unsafe impl Sync for Registration {}
Signature · 1 line
2.49.0
reviewer
#10 lore raw

Re: [PATCH v4 4/5] rust: auxiliary: add auxiliary registration

Quoted 23 lines · Danilo Krummrich

Implement the auxiliary::Registration type, which provides an API to create and register new auxiliary devices in the system.

---
 rust/kernel/auxiliary.rs | 88 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)
rust/kernel/auxiliary.rs +1 -1
index 75423737032a..b40d663b42eb 100644
@@ -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},

rust/kernel/auxiliary.rs pub fn parent(&self) -> Option<&device::Device> { · line 237

Quoted 8 lines
rust/kernel/auxiliary.rs +5 -0
@@ -230,6 +230,18 @@ pub fn parent(&self) -> Option<&device::Device> {
     }
 }
 
+impl Device {
+    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();

FYI, Tamir's patch makes this cast_mut() unnecessary.

Quoted 46 lines
rust/kernel/auxiliary.rs +39 -0
+        // 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()) };
+    }
+}
+
 // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
 // argument.
 kernel::impl_device_context_deref!(unsafe { Device });
@@ -272,3 +284,77 @@ unsafe impl Send for Device {}
 // SAFETY: `Device` can be shared among threads because all methods of `Device`
 // (i.e. `Device<Normal>) are thread safe.
 unsafe impl Sync for Device {}
+
+/// 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);

rust/kernel/auxiliary.rs unsafe impl Send for Device {} · line 329

Quoted 10 lines
rust/kernel/auxiliary.rs +10 -0
+
+        // 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) };

Does this error-path actually free the box?

Alice

Quoted 33 lines
rust/kernel/auxiliary.rs +30 -0
+            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()) };
+    }
+}
+
+// SAFETY: A `Registration` of a `struct auxiliary_device` can be released from any thread.
+unsafe impl Send for Registration {}
+
+// SAFETY: `Registration` does not expose any methods or fields that need synchronization.
+unsafe impl Sync for Registration {}
Signature · 1 line
2.49.0
author maintainer
#11 lore raw

Re: [PATCH v4 4/5] rust: auxiliary: add auxiliary registration

Quoted 26 lines · Alice Ryhl
Quoted 25 lines · Danilo Krummrich
rust/kernel/auxiliary.rs +25 -0
+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,
Quoted 8 lines

rust/kernel/auxiliary.rs unsafe impl Send for Device {} · line 329

Quoted 6 lines
rust/kernel/auxiliary.rs +6 -0
+        // - `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) };

Does this error-path actually free the box?

Yes, auxiliary_device_uninit() calls put_device() on the underlying struct device, hence the release() callback is called at this point, which frees the Box.

reviewer Reviewed-by
#12 lore raw

Re: [PATCH v4 4/5] rust: auxiliary: add auxiliary registration

Quoted 36 lines · Danilo Krummrich
Quoted 26 lines · Alice Ryhl
Quoted 25 lines · Danilo Krummrich
rust/kernel/auxiliary.rs +25 -0
+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,
Quoted 8 lines

rust/kernel/auxiliary.rs unsafe impl Send for Device {} · line 329

Quoted 6 lines
rust/kernel/auxiliary.rs +6 -0
+        // - `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) };

Does this error-path actually free the box?

Quoted 3 lines

Yes, auxiliary_device_uninit() calls put_device() on the underlying struct device, hence the release() callback is called at this point, which frees the Box.

In that case:

author maintainer
#13 lore raw

PATCH v4 5/5 samples: rust: add Rust auxiliary driver sample

In reply to 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.

---
 MAINTAINERS                           |   1 +
 samples/rust/Kconfig                  |  12 +++
 samples/rust/Makefile                 |   1 +
 samples/rust/rust_driver_auxiliary.rs | 122 ++++++++++++++++++++++++++
 4 files changed, 136 insertions(+)
 create mode 100644 samples/rust/rust_driver_auxiliary.rs
MAINTAINERS +1 -0
index a7bc29ca37d4..23c6ca105471 100644
@@ -7246,6 +7246,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
 
samples/rust/Kconfig +12 -0
index cad52b7120b5..43cb72d72631 100644
@@ -82,6 +82,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
samples/rust/Makefile +1 -0
index c6a2479f7d9c..6a466afd2a21 100644
@@ -8,6 +8,7 @@ obj-$(CONFIG_SAMPLE_RUST_DMA)			+= rust_dma.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
 
samples/rust/rust_driver_auxiliary.rs new file +122 -0

122 lines not on this page · raw message

Signature · 1 line
2.49.0
maintainer
#14 lore raw
In reply to Danilo Krummrich
Quoted 6 lines · Danilo Krummrich

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.

Quoted 6 lines

The auxiliary abstractions are required for the Nova driver project, in order to connect nova-core with the nova-drm driver.

A branch containing the patches can be found in [1].

[1] https://web.git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=rust/auxiliary

Looks good to me, want to take this through a gpu tree so you can build on top of it, or do you want it in the driver-core.git tree?

thanks,

greg k-h

author maintainer
#15 lore raw
Quoted 10 lines · Greg KH
Quoted 9 lines · Danilo Krummrich

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.

Quoted 6 lines
Quoted 3 lines

A branch containing the patches can be found in [1].

[1] https://web.git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=rust/auxiliary

Looks good to me, want to take this through a gpu tree so you can build on top of it, or do you want it in the driver-core.git tree?

Yes, I'd like to take this one through the nova tree.

maintainer
#16 lore raw
Quoted 11 lines · Danilo Krummrich
Quoted 10 lines · Greg KH
Quoted 9 lines · Danilo Krummrich

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.

Quoted 9 lines
Quoted 6 lines
Quoted 3 lines

A branch containing the patches can be found in [1].

[1] https://web.git.kernel.org/pub/scm/linux/kernel/git/dakr/linux.git/log/?h=rust/auxiliary

Looks good to me, want to take this through a gpu tree so you can build on top of it, or do you want it in the driver-core.git tree?

Yes, I'd like to take this one through the nova tree.

Please do!

author maintainer
#17 lore raw
In reply to Danilo Krummrich
Quoted 1 line · Danilo Krummrich

This series adds Rust abstractions for the auxiliary bus.

With the following changes, applied to nova-next, thanks!

* abstraction: fix typos, let _ = => drop(), use kernel::ffi
* sample: use ok_or() when accessing auxiliary::Device::parent()

- Danilo