projects/linux·blob v6.16 · refs

188 lines · 7.2 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//! Each bus / subsystem is expected to implement [`RegistrationOps`], which allows drivers to
6//! register using the [`Registration`] class.
7
8use crate::error::{Error, Result};
9use crate::{device, of, str::CStr, try_pin_init, types::Opaque, ThisModule};
10use core::pin::Pin;
11use pin_init::{pin_data, pinned_drop, PinInit};
12
13/// The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform,
14/// Amba, etc.) to provide the corresponding subsystem specific implementation to register /
15/// unregister a driver of the particular type (`RegType`).
16///
17/// For instance, the PCI subsystem would set `RegType` to `bindings::pci_driver` and call
18/// `bindings::__pci_register_driver` from `RegistrationOps::register` and
19/// `bindings::pci_unregister_driver` from `RegistrationOps::unregister`.
20///
21/// # Safety
22///
23/// A call to [`RegistrationOps::unregister`] for a given instance of `RegType` is only valid if a
24/// preceding call to [`RegistrationOps::register`] has been successful.
25pub unsafe trait RegistrationOps {
26 /// The type that holds information about the registration. This is typically a struct defined
27 /// by the C portion of the kernel.
28 type RegType: Default;
29
30 /// Registers a driver.
31 ///
32 /// # Safety
33 ///
34 /// On success, `reg` must remain pinned and valid until the matching call to
35 /// [`RegistrationOps::unregister`].
36 unsafe fn register(
37 reg: &Opaque<Self::RegType>,
38 name: &'static CStr,
39 module: &'static ThisModule,
40 ) -> Result;
41
42 /// Unregisters a driver previously registered with [`RegistrationOps::register`].
43 ///
44 /// # Safety
45 ///
46 /// Must only be called after a preceding successful call to [`RegistrationOps::register`] for
47 /// the same `reg`.
48 unsafe fn unregister(reg: &Opaque<Self::RegType>);
49}
50
51/// A [`Registration`] is a generic type that represents the registration of some driver type (e.g.
52/// `bindings::pci_driver`). Therefore a [`Registration`] must be initialized with a type that
53/// implements the [`RegistrationOps`] trait, such that the generic `T::register` and
54/// `T::unregister` calls result in the subsystem specific registration calls.
55///
56///Once the `Registration` structure is dropped, the driver is unregistered.
57#[pin_data(PinnedDrop)]
58pub struct Registration<T: RegistrationOps> {
59 #[pin]
60 reg: Opaque<T::RegType>,
61}
62
63// SAFETY: `Registration` has no fields or methods accessible via `&Registration`, so it is safe to
64// share references to it with multiple threads as nothing can be done.
65unsafe impl<T: RegistrationOps> Sync for Registration<T> {}
66
67// SAFETY: Both registration and unregistration are implemented in C and safe to be performed from
68// any thread, so `Registration` is `Send`.
69unsafe impl<T: RegistrationOps> Send for Registration<T> {}
70
71impl<T: RegistrationOps> Registration<T> {
72 /// Creates a new instance of the registration object.
73 pub fn new(name: &'static CStr, module: &'static ThisModule) -> impl PinInit<Self, Error> {
74 try_pin_init!(Self {
75 reg <- Opaque::try_ffi_init(|ptr: *mut T::RegType| {
76 // SAFETY: `try_ffi_init` guarantees that `ptr` is valid for write.
77 unsafe { ptr.write(T::RegType::default()) };
78
79 // SAFETY: `try_ffi_init` guarantees that `ptr` is valid for write, and it has
80 // just been initialised above, so it's also valid for read.
81 let drv = unsafe { &*(ptr as *const Opaque<T::RegType>) };
82
83 // SAFETY: `drv` is guaranteed to be pinned until `T::unregister`.
84 unsafe { T::register(drv, name, module) }
85 }),
86 })
87 }
88}
89
90#[pinned_drop]
91impl<T: RegistrationOps> PinnedDrop for Registration<T> {
92 fn drop(self: Pin<&mut Self>) {
93 // SAFETY: The existence of `self` guarantees that `self.reg` has previously been
94 // successfully registered with `T::register`
95 unsafe { T::unregister(&self.reg) };
96 }
97}
98
99/// Declares a kernel module that exposes a single driver.
100///
101/// It is meant to be used as a helper by other subsystems so they can more easily expose their own
102/// macros.
103#[macro_export]
104macro_rules! module_driver {
105 (<$gen_type:ident>, $driver_ops:ty, { type: $type:ty, $($f:tt)* }) => {
106 type Ops<$gen_type> = $driver_ops;
107
108 #[$crate::prelude::pin_data]
109 struct DriverModule {
110 #[pin]
111 _driver: $crate::driver::Registration<Ops<$type>>,
112 }
113
114 impl $crate::InPlaceModule for DriverModule {
115 fn init(
116 module: &'static $crate::ThisModule
117 ) -> impl ::pin_init::PinInit<Self, $crate::error::Error> {
118 $crate::try_pin_init!(Self {
119 _driver <- $crate::driver::Registration::new(
120 <Self as $crate::ModuleMetadata>::NAME,
121 module,
122 ),
123 })
124 }
125 }
126
127 $crate::prelude::module! {
128 type: DriverModule,
129 $($f)*
130 }
131 }
132}
133
134/// The bus independent adapter to match a drivers and a devices.
135///
136/// This trait should be implemented by the bus specific adapter, which represents the connection
137/// of a device and a driver.
138///
139/// It provides bus independent functions for device / driver interactions.
140pub trait Adapter {
141 /// The type holding driver private data about each device id supported by the driver.
142 type IdInfo: 'static;
143
144 /// The [`of::IdTable`] of the corresponding driver.
145 fn of_id_table() -> Option<of::IdTable<Self::IdInfo>>;
146
147 /// Returns the driver's private data from the matching entry in the [`of::IdTable`], if any.
148 ///
149 /// If this returns `None`, it means there is no match with an entry in the [`of::IdTable`].
150 #[cfg(CONFIG_OF)]
151 fn of_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
152 let table = Self::of_id_table()?;
153
154 // SAFETY:
155 // - `table` has static lifetime, hence it's valid for read,
156 // - `dev` is guaranteed to be valid while it's alive, and so is `pdev.as_ref().as_raw()`.
157 let raw_id = unsafe { bindings::of_match_device(table.as_ptr(), dev.as_raw()) };
158
159 if raw_id.is_null() {
160 None
161 } else {
162 // SAFETY: `DeviceId` is a `#[repr(transparent)` wrapper of `struct of_device_id` and
163 // does not add additional invariants, so it's safe to transmute.
164 let id = unsafe { &*raw_id.cast::<of::DeviceId>() };
165
166 Some(table.info(<of::DeviceId as crate::device_id::RawDeviceId>::index(id)))
167 }
168 }
169
170 #[cfg(not(CONFIG_OF))]
171 #[allow(missing_docs)]
172 fn of_id_info(_dev: &device::Device) -> Option<&'static Self::IdInfo> {
173 None
174 }
175
176 /// Returns the driver's private data from the matching entry of any of the ID tables, if any.
177 ///
178 /// If this returns `None`, it means that there is no match in any of the ID tables directly
179 /// associated with a [`device::Device`].
180 fn id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
181 let id = Self::of_id_info(dev);
182 if id.is_some() {
183 return id;
184 }
185
186 None
187 }
188}