kernel/auxiliary.rs
1// SPDX-License-Identifier: GPL-2.0
2
3//! Abstractions for the auxiliary bus.
4//!
5//! C header: [`include/linux/auxiliary_bus.h`](srctree/include/linux/auxiliary_bus.h)
6
7use crate::{
8 bindings, container_of, device,
9 device_id::{RawDeviceId, RawDeviceIdIndex},
10 driver,
11 error::{from_result, to_result, Result},
12 prelude::*,
13 types::Opaque,
14 ThisModule,
15};
16use core::{
17 marker::PhantomData,
18 ptr::{addr_of_mut, NonNull},
19};
20
21/// An adapter for the registration of auxiliary drivers.
22pub struct Adapter<T: Driver>(T);
23
24// SAFETY: A call to `unregister` for a given instance of `RegType` is guaranteed to be valid if
25// a preceding call to `register` has been successful.
26unsafe impl<T: Driver + 'static> driver::RegistrationOps for Adapter<T> {
27 type RegType = bindings::auxiliary_driver;
28
29 unsafe fn register(
30 adrv: &Opaque<Self::RegType>,
31 name: &'static CStr,
32 module: &'static ThisModule,
33 ) -> Result {
34 // SAFETY: It's safe to set the fields of `struct auxiliary_driver` on initialization.
35 unsafe {
36 (*adrv.get()).name = name.as_char_ptr();
37 (*adrv.get()).probe = Some(Self::probe_callback);
38 (*adrv.get()).remove = Some(Self::remove_callback);
39 (*adrv.get()).id_table = T::ID_TABLE.as_ptr();
40 }
41
42 // SAFETY: `adrv` is guaranteed to be a valid `RegType`.
43 to_result(unsafe {
44 bindings::__auxiliary_driver_register(adrv.get(), module.0, name.as_char_ptr())
45 })
46 }
47
48 unsafe fn unregister(adrv: &Opaque<Self::RegType>) {
49 // SAFETY: `adrv` is guaranteed to be a valid `RegType`.
50 unsafe { bindings::auxiliary_driver_unregister(adrv.get()) }
51 }
52}
53
54impl<T: Driver + 'static> Adapter<T> {
55 extern "C" fn probe_callback(
56 adev: *mut bindings::auxiliary_device,
57 id: *const bindings::auxiliary_device_id,
58 ) -> kernel::ffi::c_int {
59 // SAFETY: The auxiliary bus only ever calls the probe callback with a valid pointer to a
60 // `struct auxiliary_device`.
61 //
62 // INVARIANT: `adev` is valid for the duration of `probe_callback()`.
63 let adev = unsafe { &*adev.cast::<Device<device::CoreInternal>>() };
64
65 // SAFETY: `DeviceId` is a `#[repr(transparent)`] wrapper of `struct auxiliary_device_id`
66 // and does not add additional invariants, so it's safe to transmute.
67 let id = unsafe { &*id.cast::<DeviceId>() };
68 let info = T::ID_TABLE.info(id.index());
69
70 from_result(|| {
71 let data = T::probe(adev, info)?;
72
73 adev.as_ref().set_drvdata(data);
74 Ok(0)
75 })
76 }
77
78 extern "C" fn remove_callback(adev: *mut bindings::auxiliary_device) {
79 // SAFETY: The auxiliary bus only ever calls the probe callback with a valid pointer to a
80 // `struct auxiliary_device`.
81 //
82 // INVARIANT: `adev` is valid for the duration of `probe_callback()`.
83 let adev = unsafe { &*adev.cast::<Device<device::CoreInternal>>() };
84
85 // SAFETY: `remove_callback` is only ever called after a successful call to
86 // `probe_callback`, hence it's guaranteed that `Device::set_drvdata()` has been called
87 // and stored a `Pin<KBox<T>>`.
88 drop(unsafe { adev.as_ref().drvdata_obtain::<Pin<KBox<T>>>() });
89 }
90}
91
92/// Declares a kernel module that exposes a single auxiliary driver.
93#[macro_export]
94macro_rules! module_auxiliary_driver {
95 ($($f:tt)*) => {
96 $crate::module_driver!(<T>, $crate::auxiliary::Adapter<T>, { $($f)* });
97 };
98}
99
100/// Abstraction for `bindings::auxiliary_device_id`.
101#[repr(transparent)]
102#[derive(Clone, Copy)]
103pub struct DeviceId(bindings::auxiliary_device_id);
104
105impl DeviceId {
106 /// Create a new [`DeviceId`] from name.
107 pub const fn new(modname: &'static CStr, name: &'static CStr) -> Self {
108 let name = name.as_bytes_with_nul();
109 let modname = modname.as_bytes_with_nul();
110
111 // TODO: Replace with `bindings::auxiliary_device_id::default()` once stabilized for
112 // `const`.
113 //
114 // SAFETY: FFI type is valid to be zero-initialized.
115 let mut id: bindings::auxiliary_device_id = unsafe { core::mem::zeroed() };
116
117 let mut i = 0;
118 while i < modname.len() {
119 id.name[i] = modname[i];
120 i += 1;
121 }
122
123 // Reuse the space of the NULL terminator.
124 id.name[i - 1] = b'.';
125
126 let mut j = 0;
127 while j < name.len() {
128 id.name[i] = name[j];
129 i += 1;
130 j += 1;
131 }
132
133 Self(id)
134 }
135}
136
137// SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `auxiliary_device_id` and does not add
138// additional invariants, so it's safe to transmute to `RawType`.
139unsafe impl RawDeviceId for DeviceId {
140 type RawType = bindings::auxiliary_device_id;
141}
142
143// SAFETY: `DRIVER_DATA_OFFSET` is the offset to the `driver_data` field.
144unsafe impl RawDeviceIdIndex for DeviceId {
145 const DRIVER_DATA_OFFSET: usize =
146 core::mem::offset_of!(bindings::auxiliary_device_id, driver_data);
147
148 fn index(&self) -> usize {
149 self.0.driver_data
150 }
151}
152
153/// IdTable type for auxiliary drivers.
154pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;
155
156/// Create a auxiliary `IdTable` with its alias for modpost.
157#[macro_export]
158macro_rules! auxiliary_device_table {
159 ($table_name:ident, $module_table_name:ident, $id_info_type: ty, $table_data: expr) => {
160 const $table_name: $crate::device_id::IdArray<
161 $crate::auxiliary::DeviceId,
162 $id_info_type,
163 { $table_data.len() },
164 > = $crate::device_id::IdArray::new($table_data);
165
166 $crate::module_device_table!("auxiliary", $module_table_name, $table_name);
167 };
168}
169
170/// The auxiliary driver trait.
171///
172/// Drivers must implement this trait in order to get an auxiliary driver registered.
173pub trait Driver {
174 /// The type holding information about each device id supported by the driver.
175 ///
176 /// TODO: Use associated_type_defaults once stabilized:
177 ///
178 /// type IdInfo: 'static = ();
179 type IdInfo: 'static;
180
181 /// The table of device ids supported by the driver.
182 const ID_TABLE: IdTable<Self::IdInfo>;
183
184 /// Auxiliary driver probe.
185 ///
186 /// Called when an auxiliary device is matches a corresponding driver.
187 fn probe(dev: &Device<device::Core>, id_info: &Self::IdInfo) -> Result<Pin<KBox<Self>>>;
188}
189
190/// The auxiliary device representation.
191///
192/// This structure represents the Rust abstraction for a C `struct auxiliary_device`. The
193/// implementation abstracts the usage of an already existing C `struct auxiliary_device` within
194/// Rust code that we get passed from the C side.
195///
196/// # Invariants
197///
198/// A [`Device`] instance represents a valid `struct auxiliary_device` created by the C portion of
199/// the kernel.
200#[repr(transparent)]
201pub struct Device<Ctx: device::DeviceContext = device::Normal>(
202 Opaque<bindings::auxiliary_device>,
203 PhantomData<Ctx>,
204);
205
206impl<Ctx: device::DeviceContext> Device<Ctx> {
207 fn as_raw(&self) -> *mut bindings::auxiliary_device {
208 self.0.get()
209 }
210
211 /// Returns the auxiliary device' id.
212 pub fn id(&self) -> u32 {
213 // SAFETY: By the type invariant `self.as_raw()` is a valid pointer to a
214 // `struct auxiliary_device`.
215 unsafe { (*self.as_raw()).id }
216 }
217
218 /// Returns a reference to the parent [`device::Device`], if any.
219 pub fn parent(&self) -> Option<&device::Device> {
220 let ptr: *const Self = self;
221 // CAST: `Device<Ctx: DeviceContext>` types are transparent to each other.
222 let ptr: *const Device = ptr.cast();
223 // SAFETY: `ptr` was derived from `&self`.
224 let this = unsafe { &*ptr };
225
226 this.as_ref().parent()
227 }
228}
229
230impl Device {
231 extern "C" fn release(dev: *mut bindings::device) {
232 // SAFETY: By the type invariant `self.0.as_raw` is a pointer to the `struct device`
233 // embedded in `struct auxiliary_device`.
234 let adev = unsafe { container_of!(dev, bindings::auxiliary_device, dev) };
235
236 // SAFETY: `adev` points to the memory that has been allocated in `Registration::new`, via
237 // `KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)`.
238 let _ = unsafe { KBox::<Opaque<bindings::auxiliary_device>>::from_raw(adev.cast()) };
239 }
240}
241
242// SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
243// argument.
244kernel::impl_device_context_deref!(unsafe { Device });
245kernel::impl_device_context_into_aref!(Device);
246
247// SAFETY: Instances of `Device` are always reference-counted.
248unsafe impl crate::types::AlwaysRefCounted for Device {
249 fn inc_ref(&self) {
250 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
251 unsafe { bindings::get_device(self.as_ref().as_raw()) };
252 }
253
254 unsafe fn dec_ref(obj: NonNull<Self>) {
255 // CAST: `Self` a transparent wrapper of `bindings::auxiliary_device`.
256 let adev: *mut bindings::auxiliary_device = obj.cast().as_ptr();
257
258 // SAFETY: By the type invariant of `Self`, `adev` is a pointer to a valid
259 // `struct auxiliary_device`.
260 let dev = unsafe { addr_of_mut!((*adev).dev) };
261
262 // SAFETY: The safety requirements guarantee that the refcount is non-zero.
263 unsafe { bindings::put_device(dev) }
264 }
265}
266
267impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
268 fn as_ref(&self) -> &device::Device<Ctx> {
269 // SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
270 // `struct auxiliary_device`.
271 let dev = unsafe { addr_of_mut!((*self.as_raw()).dev) };
272
273 // SAFETY: `dev` points to a valid `struct device`.
274 unsafe { device::Device::from_raw(dev) }
275 }
276}
277
278// SAFETY: A `Device` is always reference-counted and can be released from any thread.
279unsafe impl Send for Device {}
280
281// SAFETY: `Device` can be shared among threads because all methods of `Device`
282// (i.e. `Device<Normal>) are thread safe.
283unsafe impl Sync for Device {}
284
285/// The registration of an auxiliary device.
286///
287/// This type represents the registration of a [`struct auxiliary_device`]. When an instance of this
288/// type is dropped, its respective auxiliary device will be unregistered from the system.
289///
290/// # Invariants
291///
292/// `self.0` always holds a valid pointer to an initialized and registered
293/// [`struct auxiliary_device`].
294pub struct Registration(NonNull<bindings::auxiliary_device>);
295
296impl Registration {
297 /// Create and register a new auxiliary device.
298 pub fn new(parent: &device::Device, name: &CStr, id: u32, modname: &CStr) -> Result<Self> {
299 let boxed = KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)?;
300 let adev = boxed.get();
301
302 // SAFETY: It's safe to set the fields of `struct auxiliary_device` on initialization.
303 unsafe {
304 (*adev).dev.parent = parent.as_raw();
305 (*adev).dev.release = Some(Device::release);
306 (*adev).name = name.as_char_ptr();
307 (*adev).id = id;
308 }
309
310 // SAFETY: `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`,
311 // which has not been initialized yet.
312 unsafe { bindings::auxiliary_device_init(adev) };
313
314 // Now that `adev` is initialized, leak the `Box`; the corresponding memory will be freed
315 // by `Device::release` when the last reference to the `struct auxiliary_device` is dropped.
316 let _ = KBox::into_raw(boxed);
317
318 // SAFETY:
319 // - `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`, which has
320 // been initialialized,
321 // - `modname.as_char_ptr()` is a NULL terminated string.
322 let ret = unsafe { bindings::__auxiliary_device_add(adev, modname.as_char_ptr()) };
323 if ret != 0 {
324 // SAFETY: `adev` is guaranteed to be a valid pointer to a `struct auxiliary_device`,
325 // which has been initialialized.
326 unsafe { bindings::auxiliary_device_uninit(adev) };
327
328 return Err(Error::from_errno(ret));
329 }
330
331 // SAFETY: `adev` is guaranteed to be non-null, since the `KBox` was allocated successfully.
332 //
333 // INVARIANT: The device will remain registered until `auxiliary_device_delete()` is called,
334 // which happens in `Self::drop()`.
335 Ok(Self(unsafe { NonNull::new_unchecked(adev) }))
336 }
337}
338
339impl Drop for Registration {
340 fn drop(&mut self) {
341 // SAFETY: By the type invariant of `Self`, `self.0.as_ptr()` is a valid registered
342 // `struct auxiliary_device`.
343 unsafe { bindings::auxiliary_device_delete(self.0.as_ptr()) };
344
345 // This drops the reference we acquired through `auxiliary_device_init()`.
346 //
347 // SAFETY: By the type invariant of `Self`, `self.0.as_ptr()` is a valid registered
348 // `struct auxiliary_device`.
349 unsafe { bindings::auxiliary_device_uninit(self.0.as_ptr()) };
350 }
351}
352
353// SAFETY: A `Registration` of a `struct auxiliary_device` can be released from any thread.
354unsafe impl Send for Registration {}
355
356// SAFETY: `Registration` does not expose any methods or fields that need synchronization.
357unsafe impl Sync for Registration {}