kernel/
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//! 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::{acpi, 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 [`acpi::IdTable`] of the corresponding driver
145    fn acpi_id_table() -> Option<acpi::IdTable<Self::IdInfo>>;
146
147    /// Returns the driver's private data from the matching entry in the [`acpi::IdTable`], if any.
148    ///
149    /// If this returns `None`, it means there is no match with an entry in the [`acpi::IdTable`].
150    fn acpi_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
151        #[cfg(not(CONFIG_ACPI))]
152        {
153            let _ = dev;
154            None
155        }
156
157        #[cfg(CONFIG_ACPI)]
158        {
159            let table = Self::acpi_id_table()?;
160
161            // SAFETY:
162            // - `table` has static lifetime, hence it's valid for read,
163            // - `dev` is guaranteed to be valid while it's alive, and so is `dev.as_raw()`.
164            let raw_id = unsafe { bindings::acpi_match_device(table.as_ptr(), dev.as_raw()) };
165
166            if raw_id.is_null() {
167                None
168            } else {
169                // SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct acpi_device_id`
170                // and does not add additional invariants, so it's safe to transmute.
171                let id = unsafe { &*raw_id.cast::<acpi::DeviceId>() };
172
173                Some(table.info(<acpi::DeviceId as crate::device_id::RawDeviceId>::index(id)))
174            }
175        }
176    }
177
178    /// The [`of::IdTable`] of the corresponding driver.
179    fn of_id_table() -> Option<of::IdTable<Self::IdInfo>>;
180
181    /// Returns the driver's private data from the matching entry in the [`of::IdTable`], if any.
182    ///
183    /// If this returns `None`, it means there is no match with an entry in the [`of::IdTable`].
184    fn of_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
185        #[cfg(not(CONFIG_OF))]
186        {
187            let _ = dev;
188            None
189        }
190
191        #[cfg(CONFIG_OF)]
192        {
193            let table = Self::of_id_table()?;
194
195            // SAFETY:
196            // - `table` has static lifetime, hence it's valid for read,
197            // - `dev` is guaranteed to be valid while it's alive, and so is `dev.as_raw()`.
198            let raw_id = unsafe { bindings::of_match_device(table.as_ptr(), dev.as_raw()) };
199
200            if raw_id.is_null() {
201                None
202            } else {
203                // SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct of_device_id`
204                // and does not add additional invariants, so it's safe to transmute.
205                let id = unsafe { &*raw_id.cast::<of::DeviceId>() };
206
207                Some(table.info(<of::DeviceId as crate::device_id::RawDeviceId>::index(id)))
208            }
209        }
210    }
211
212    /// Returns the driver's private data from the matching entry of any of the ID tables, if any.
213    ///
214    /// If this returns `None`, it means that there is no match in any of the ID tables directly
215    /// associated with a [`device::Device`].
216    fn id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> {
217        let id = Self::acpi_id_info(dev);
218        if id.is_some() {
219            return id;
220        }
221
222        let id = Self::of_id_info(dev);
223        if id.is_some() {
224            return id;
225        }
226
227        None
228    }
229}