projects/linux·blob v7.2 · refs

441 lines · 17.0 KiB

1// SPDX-License-Identifier: GPL-2.0
2
3//! Generic support for drivers of different buses (e.g., PCI, Platform, Amba, etc.).
4//!
5//! This documentation describes how to implement a bus specific driver API and how to align it with
6//! the design of (bus specific) devices.
7//!
8//! Note: Readers are expected to know the content of the documentation of [`Device`] and
9//! [`DeviceContext`].
10//!
11//! # Driver Trait
12//!
13//! The main driver interface is defined by a bus specific driver trait. For instance:
14//!
15//! ```ignore
16//! pub trait Driver {
17//! /// The type holding information about each device ID supported by the driver.
18//! type IdInfo: 'static;
19//!
20//! /// The type of the driver's bus device private data.
21//! type Data<'bound>: Send + 'bound;
22//!
23//! /// The table of OF device ids supported by the driver.
24//! const OF_ID_TABLE: Option<of::IdTable<Self::IdInfo>> = None;
25//!
26//! /// The table of ACPI device ids supported by the driver.
27//! const ACPI_ID_TABLE: Option<acpi::IdTable<Self::IdInfo>> = None;
28//!
29//! /// Driver probe.
30//! fn probe<'bound>(
31//! dev: &'bound Device<device::Core<'_>>,
32//! id_info: &'bound Self::IdInfo,
33//! ) -> impl PinInit<Self::Data<'bound>, Error> + 'bound;
34//!
35//! /// Driver unbind (optional).
36//! fn unbind<'bound>(
37//! dev: &'bound Device<device::Core<'_>>,
38//! this: Pin<&Self::Data<'bound>>,
39//! ) {
40//! let _ = (dev, this);
41//! }
42//! }
43//! ```
44//!
45//! For specific examples see:
46//!
47//! * [`platform::Driver`](kernel::platform::Driver)
48#![cfg_attr(
49 CONFIG_AUXILIARY_BUS,
50 doc = "* [`auxiliary::Driver`](kernel::auxiliary::Driver)"
51)]
52#![cfg_attr(CONFIG_PCI, doc = "* [`pci::Driver`](kernel::pci::Driver)")]
53//!
54//! The `probe()` callback should return a
55//! `impl PinInit<Self::Data<'bound>, Error>`, i.e. the driver's private data. The bus
56//! abstraction should store the pointer in the corresponding bus device. The generic
57//! [`Device`] infrastructure provides common helpers for this purpose on its
58//! [`Device<CoreInternal>`] implementation.
59//!
60//! All driver callbacks should provide a reference to the driver's private data. Once the driver
61//! is unbound from the device, the bus abstraction should take back the ownership of the driver's
62//! private data from the corresponding [`Device`] and [`drop`] it.
63//!
64//! All driver callbacks should provide a [`Device<Core>`] reference (see also [`device::Core`]).
65//!
66//! # Adapter
67//!
68//! The adapter implementation of a bus represents the abstraction layer between the C bus
69//! callbacks and the Rust bus callbacks. It therefore has to be generic over an implementation of
70//! the [driver trait](#driver-trait).
71//!
72//! ```ignore
73//! pub struct Adapter<T: Driver>;
74//! ```
75//!
76//! There's a common [`Adapter`] trait that can be implemented to inherit common driver
77//! infrastructure, such as finding the ID info from an [`of::IdTable`] or [`acpi::IdTable`].
78//!
79//! # Driver Registration
80//!
81//! In order to register C driver types (such as `struct platform_driver`) the [adapter](#adapter)
82//! should implement the [`RegistrationOps`] trait.
83//!
84//! This trait implementation can be used to create the actual registration with the common
85//! [`Registration`] type.
86//!
87//! Typically, bus abstractions want to provide a bus specific `module_bus_driver!` macro, which
88//! creates a kernel module with exactly one [`Registration`] for the bus specific adapter.
89//!
90//! The generic driver infrastructure provides a helper for this with the [`module_driver`] macro.
91//!
92//! # Device IDs
93//!
94//! Besides the common device ID types, such as [`of::DeviceId`] and [`acpi::DeviceId`], most buses
95//! may need to implement their own device ID types.
96//!
97//! For this purpose the generic infrastructure in [`device_id`] should be used.
98//!
99//! [`Core`]: device::Core
100//! [`Device`]: device::Device
101//! [`Device<Core>`]: device::Device<device::Core>
102//! [`Device<CoreInternal>`]: device::Device<device::CoreInternal>
103//! [`DeviceContext`]: device::DeviceContext
104//! [`device_id`]: kernel::device_id
105//! [`module_driver`]: kernel::module_driver
106
107use crate::{
108 acpi,
109 device,
110 of,
111 prelude::*,
112 types::Opaque,
113 ThisModule, //
114};
115
116/// Trait describing the layout of a specific device driver.
117///
118/// This trait describes the layout of a specific driver structure, such as `struct pci_driver` or
119/// `struct platform_driver`.
120///
121/// # Safety
122///
123/// Implementors must guarantee that:
124/// - `DriverType` is `repr(C)`,
125/// - `DriverData` is the type of the driver's device private data.
126/// - `DriverType` embeds a valid `struct device_driver` at byte offset `DEVICE_DRIVER_OFFSET`.
127pub unsafe trait DriverLayout {
128 /// The specific driver type embedding a `struct device_driver`.
129 type DriverType: Default;
130
131 /// The type of the driver's bus device private data.
132 type DriverData<'bound>;
133
134 /// Byte offset of the embedded `struct device_driver` within `DriverType`.
135 ///
136 /// This must correspond exactly to the location of the embedded `struct device_driver` field.
137 const DEVICE_DRIVER_OFFSET: usize;
138}
139
140/// The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform,
141/// Amba, etc.) to provide the corresponding subsystem specific implementation to register /
142/// unregister a driver of the particular type (`DriverType`).
143///
144/// For instance, the PCI subsystem would set `DriverType` to `bindings::pci_driver` and call
145/// `bindings::__pci_register_driver` from `RegistrationOps::register` and
146/// `bindings::pci_unregister_driver` from `RegistrationOps::unregister`.
147///
148/// # Safety
149///
150/// A call to [`RegistrationOps::unregister`] for a given instance of `DriverType` is only valid if
151/// a preceding call to [`RegistrationOps::register`] has been successful.
152pub unsafe trait RegistrationOps: DriverLayout {
153 /// Registers a driver.
154 ///
155 /// # Safety
156 ///
157 /// On success, `reg` must remain pinned and valid until the matching call to
158 /// [`RegistrationOps::unregister`].
159 unsafe fn register(
160 reg: &Opaque<Self::DriverType>,
161 name: &'static CStr,
162 module: &'static ThisModule,
163 ) -> Result;
164
165 /// Unregisters a driver previously registered with [`RegistrationOps::register`].
166 ///
167 /// # Safety
168 ///
169 /// Must only be called after a preceding successful call to [`RegistrationOps::register`] for
170 /// the same `reg`.
171 unsafe fn unregister(reg: &Opaque<Self::DriverType>);
172}
173
174/// A [`Registration`] is a generic type that represents the registration of some driver type (e.g.
175/// `bindings::pci_driver`). Therefore a [`Registration`] must be initialized with a type that
176/// implements the [`RegistrationOps`] trait, such that the generic `T::register` and
177/// `T::unregister` calls result in the subsystem specific registration calls.
178///
179///Once the `Registration` structure is dropped, the driver is unregistered.
180#[pin_data(PinnedDrop)]
181pub struct Registration<T: RegistrationOps> {
182 #[pin]
183 reg: Opaque<T::DriverType>,
184}
185
186// SAFETY: `Registration` has no fields or methods accessible via `&Registration`, so it is safe to
187// share references to it with multiple threads as nothing can be done.
188unsafe impl<T: RegistrationOps> Sync for Registration<T> {}
189
190// SAFETY: Both registration and unregistration are implemented in C and safe to be performed from
191// any thread, so `Registration` is `Send`.
192unsafe impl<T: RegistrationOps> Send for Registration<T> {}
193
194impl<T: RegistrationOps> Registration<T> {
195 extern "C" fn post_unbind_callback(dev: *mut bindings::device) {
196 // SAFETY: The driver core only ever calls the post unbind callback with a valid pointer to
197 // a `struct device`.
198 //
199 // INVARIANT: `dev` is valid for the duration of the `post_unbind_callback()`.
200 let dev = unsafe { &*dev.cast::<device::Device<device::CoreInternal<'_>>>() };
201
202 // `remove()` has been completed at this point; devres resources are still valid and will
203 // be released after the driver's bus device private data is dropped.
204 //
205 // SAFETY: By the safety requirements of the `Driver` trait, `T::DriverData` is the
206 // driver's bus device private data type.
207 drop(unsafe { dev.drvdata_obtain::<T::DriverData<'_>>() });
208 }
209
210 /// Attach generic `struct device_driver` callbacks.
211 fn callbacks_attach(drv: &Opaque<T::DriverType>) {
212 let ptr = drv.get().cast::<u8>();
213
214 // SAFETY:
215 // - `drv.get()` yields a valid pointer to `Self::DriverType`.
216 // - Adding `DEVICE_DRIVER_OFFSET` yields the address of the embedded `struct device_driver`
217 // as guaranteed by the safety requirements of the `Driver` trait.
218 let base = unsafe { ptr.add(T::DEVICE_DRIVER_OFFSET) };
219
220 // CAST: `base` points to the offset of the embedded `struct device_driver`.
221 let base = base.cast::<bindings::device_driver>();
222
223 // SAFETY: It is safe to set the fields of `struct device_driver` on initialization.
224 unsafe { (*base).p_cb.post_unbind_rust = Some(Self::post_unbind_callback) };
225 }
226
227 /// Creates a new instance of the registration object.
228 pub fn new(name: &'static CStr, module: &'static ThisModule) -> impl PinInit<Self, Error>
229 where
230 T: 'static,
231 {
232 try_pin_init!(Self {
233 reg <- Opaque::try_ffi_init(|ptr: *mut T::DriverType| {
234 // SAFETY: `try_ffi_init` guarantees that `ptr` is valid for write.
235 unsafe { ptr.write(T::DriverType::default()) };
236
237 // SAFETY: `try_ffi_init` guarantees that `ptr` is valid for write, and it has
238 // just been initialised above, so it's also valid for read.
239 let drv = unsafe { &*(ptr as *const Opaque<T::DriverType>) };
240
241 Self::callbacks_attach(drv);
242
243 // SAFETY: `drv` is guaranteed to be pinned until `T::unregister`.
244 unsafe { T::register(drv, name, module) }
245 }),
246 })
247 }
248}
249
250#[pinned_drop]
251impl<T: RegistrationOps> PinnedDrop for Registration<T> {
252 fn drop(self: Pin<&mut Self>) {
253 // SAFETY: The existence of `self` guarantees that `self.reg` has previously been
254 // successfully registered with `T::register`
255 unsafe { T::unregister(&self.reg) };
256 }
257}
258
259/// Declares a kernel module that exposes a single driver.
260///
261/// It is meant to be used as a helper by other subsystems so they can more easily expose their own
262/// macros.
263#[macro_export]
264macro_rules! module_driver {
265 (<$gen_type:ident>, $driver_ops:ty, { type: $type:ty, $($f:tt)* }) => {
266 type Ops<$gen_type> = $driver_ops;
267
268 #[$crate::prelude::pin_data]
269 struct DriverModule {
270 #[pin]
271 _driver: $crate::driver::Registration<Ops<$type>>,
272 }
273
274 impl $crate::InPlaceModule for DriverModule {
275 fn init(
276 module: &'static $crate::ThisModule
277 ) -> impl ::pin_init::PinInit<Self, $crate::error::Error> {
278 $crate::try_pin_init!(Self {
279 _driver <- $crate::driver::Registration::new(
280 <Self as $crate::ModuleMetadata>::NAME,
281 module,
282 ),
283 })
284 }
285 }
286
287 $crate::prelude::module! {
288 type: DriverModule,
289 $($f)*
290 }
291 }
292}
293
294// Calling the FFI function directly from the `Adapter` impl may result in it being called
295// directly from driver modules. This happens since the Rust compiler will use monomorphisation, so
296// it might happen that functions are instantiated within the calling driver module. For now, work
297// around this with `#[inline(never)]` helpers.
298//
299// TODO: Remove once a more generic solution has been implemented. For instance, we may be able to
300// leverage `bindgen` to take care of this depending on whether a symbol is (already) exported.
301#[inline(never)]
302#[allow(clippy::missing_safety_doc)]
303#[allow(dead_code)]
304#[must_use]
305unsafe fn acpi_of_match_device(
306 adev: *const bindings::acpi_device,
307 of_match_table: *const bindings::of_device_id,
308 of_id: *mut *const bindings::of_device_id,
309) -> bool {
310 // SAFETY: Safety requirements are the same as `bindings::acpi_of_match_device`.
311 unsafe { bindings::acpi_of_match_device(adev, of_match_table, of_id) }
312}
313
314/// The bus independent adapter to match a drivers and a devices.
315///
316/// This trait should be implemented by the bus specific adapter, which represents the connection
317/// of a device and a driver.
318///
319/// It provides bus independent functions for device / driver interactions.
320pub trait Adapter {
321 /// The type holding driver private data about each device id supported by the driver.
322 type IdInfo: 'static;
323
324 /// The [`acpi::IdTable`] of the corresponding driver
325 fn acpi_id_table() -> Option<acpi::IdTable<Self::IdInfo>>;
326
327 /// Returns the driver's private data from the matching entry in the [`acpi::IdTable`], if any.
328 ///
329 /// If this returns `None`, it means there is no match with an entry in the [`acpi::IdTable`].
330 fn acpi_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
331 #[cfg(not(CONFIG_ACPI))]
332 {
333 let _ = dev;
334 None
335 }
336
337 #[cfg(CONFIG_ACPI)]
338 {
339 let table = Self::acpi_id_table()?;
340
341 // SAFETY:
342 // - `table` has static lifetime, hence it's valid for read,
343 // - `dev` is guaranteed to be valid while it's alive, and so is `dev.as_raw()`.
344 let raw_id = unsafe { bindings::acpi_match_device(table.as_ptr(), dev.as_raw()) };
345
346 if raw_id.is_null() {
347 None
348 } else {
349 // SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct acpi_device_id`
350 // and does not add additional invariants, so it's safe to transmute.
351 let id = unsafe { &*raw_id.cast::<acpi::DeviceId>() };
352
353 Some(table.info(<acpi::DeviceId as crate::device_id::RawDeviceIdIndex>::index(id)))
354 }
355 }
356 }
357
358 /// The [`of::IdTable`] of the corresponding driver.
359 fn of_id_table() -> Option<of::IdTable<Self::IdInfo>>;
360
361 /// Returns the driver's private data from the matching entry in the [`of::IdTable`], if any.
362 ///
363 /// If this returns `None`, it means there is no match with an entry in the [`of::IdTable`].
364 fn of_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
365 let table = Self::of_id_table()?;
366
367 #[cfg(not(any(CONFIG_OF, CONFIG_ACPI)))]
368 {
369 let _ = (dev, table);
370 }
371
372 #[cfg(CONFIG_OF)]
373 {
374 // SAFETY:
375 // - `table` has static lifetime, hence it's valid for read,
376 // - `dev` is guaranteed to be valid while it's alive, and so is `dev.as_raw()`.
377 let raw_id = unsafe { bindings::of_match_device(table.as_ptr(), dev.as_raw()) };
378
379 if !raw_id.is_null() {
380 // SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct of_device_id`
381 // and does not add additional invariants, so it's safe to transmute.
382 let id = unsafe { &*raw_id.cast::<of::DeviceId>() };
383
384 return Some(table.info(
385 <of::DeviceId as crate::device_id::RawDeviceIdIndex>::index(id),
386 ));
387 }
388 }
389
390 #[cfg(CONFIG_ACPI)]
391 {
392 use core::ptr;
393 use device::property::FwNode;
394
395 let mut raw_id = ptr::null();
396
397 let fwnode = dev.fwnode().map_or(ptr::null_mut(), FwNode::as_raw);
398
399 // SAFETY: `fwnode` is a pointer to a valid `fwnode_handle`. A null pointer will be
400 // passed through the function.
401 let adev = unsafe { bindings::to_acpi_device_node(fwnode) };
402
403 // SAFETY:
404 // - `adev` is a valid pointer to `acpi_device` or is null. It is guaranteed to be
405 // valid as long as `dev` is alive.
406 // - `table` has static lifetime, hence it's valid for read.
407 if unsafe { acpi_of_match_device(adev, table.as_ptr(), &raw mut raw_id) } {
408 // SAFETY:
409 // - the function returns true, therefore `raw_id` has been set to a pointer to a
410 // valid `of_device_id`.
411 // - `DeviceId` is a `#[repr(transparent)]` wrapper of `struct of_device_id`
412 // and does not add additional invariants, so it's safe to transmute.
413 let id = unsafe { &*raw_id.cast::<of::DeviceId>() };
414
415 return Some(table.info(
416 <of::DeviceId as crate::device_id::RawDeviceIdIndex>::index(id),
417 ));
418 }
419 }
420
421 None
422 }
423
424 /// Returns the driver's private data from the matching entry of any of the ID tables, if any.
425 ///
426 /// If this returns `None`, it means that there is no match in any of the ID tables directly
427 /// associated with a [`device::Device`].
428 fn id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
429 let id = Self::acpi_id_info(dev);
430 if id.is_some() {
431 return id;
432 }
433
434 let id = Self::of_id_info(dev);
435 if id.is_some() {
436 return id;
437 }
438
439 None
440 }
441}