projects/linux·blob assoc-array-fixes · refs

326 lines · 12.6 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/// The bus independent adapter to match a drivers and a devices.
295///
296/// This trait should be implemented by the bus specific adapter, which represents the connection
297/// of a device and a driver.
298///
299/// It provides bus independent functions for device / driver interactions.
300pub trait Adapter {
301 /// The type holding driver private data about each device id supported by the driver.
302 type IdInfo: 'static;
303
304 /// The [`acpi::IdTable`] of the corresponding driver
305 fn acpi_id_table() -> Option<acpi::IdTable<Self::IdInfo>>;
306
307 /// The [`of::IdTable`] of the corresponding driver.
308 fn of_id_table() -> Option<of::IdTable<Self::IdInfo>>;
309
310 /// Returns the driver's private data from the matching entry of any of the ID tables, if any.
311 ///
312 /// If this returns `None`, it means that there is no match in any of the ID tables directly
313 /// associated with a [`device::Device`].
314 ///
315 /// # Safety
316 ///
317 /// The caller must ensure that the `dev` matched data is of type `Self::IdInfo`.
318 #[inline]
319 unsafe fn id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
320 // SAFETY: `dev` is guaranteed to be valid while it's alive, and so is `dev.as_raw()`.
321 let data = unsafe { bindings::device_get_match_data(dev.as_raw()) };
322
323 // SAFETY: Per safety requirement, `data` is of type `Self::IdInfo`.
324 unsafe { data.cast::<Self::IdInfo>().as_ref() }
325 }
326}