Commit 0d1803d2 authored by Danilo Krummrich's avatar Danilo Krummrich
Browse files

rust: auxiliary: add auxiliary registration 



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

Acked-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: default avatarAlice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250414131934.28418-5-dakr@kernel.org


Signed-off-by: default avatarDanilo Krummrich <dakr@kernel.org>
parent ce735e73

rust/kernel/auxiliary.rs

+87 −1
Original line number Diff line number Diff line
@@ -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 {}