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