driver.rs

  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#![cfg_attr(
 40    CONFIG_AUXILIARY_BUS,
 41    doc = "* [`auxiliary::Driver`](kernel::auxiliary::Driver)"
 42)]
 43#![cfg_attr(CONFIG_PCI, doc = "* [`pci::Driver`](kernel::pci::Driver)")]
 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
 97use 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`.
117pub 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.
142pub 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)]
171pub 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.
178unsafe 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`.
182unsafe impl<T: RegistrationOps> Send for Registration<T> {}
183
184impl<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]
238impl<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]
251macro_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.
287pub 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}