Lines Matching +full:driver +full:- +full:specific
1 // SPDX-License-Identifier: GPL-2.0
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.
11 //! # Driver Trait
13 //! The main driver interface is defined by a bus specific driver trait. For instance:
16 //! pub trait Driver: Send {
17 //! /// The type holding information about each device ID supported by the driver.
20 //! /// The table of OF device ids supported by the driver.
23 //! /// The table of ACPI device ids supported by the driver.
26 //! /// Driver probe.
27 //! fn probe(dev: &Device<device::Core>, id_info: &Self::IdInfo) -> impl PinInit<Self, Error>;
29 //! /// Driver unbind (optional).
36 //! For specific examples see:
38 //! * [`platform::Driver`](kernel::platform::Driver)
41 doc = "* [`auxiliary::Driver`](kernel::auxiliary::Driver)"
43 #")]
45 //! The `probe()` callback should return a `impl PinInit<Self, Error>`, i.e. the driver's private
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
54 //! All driver callbacks should provide a [`Device<Core>`] reference (see also [`device::Core`]).
60 //! the [driver trait](#driver-trait).
63 //! pub struct Adapter<T: Driver>;
66 //! There's a common [`Adapter`] trait that can be implemented to inherit common driver
69 //! # Driver Registration
71 //! In order to register C driver types (such as `struct platform_driver`) the [adapter](#adapter)
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.
80 //! The generic driver infrastructure provides a helper for this with the [`module_driver`] macro.
106 /// Trait describing the layout of a specific device driver.
108 /// This trait describes the layout of a specific driver structure, such as `struct pci_driver` or
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`.
118 /// The specific driver type embedding a `struct device_driver`.
121 /// The type of the driver's device private data.
131 /// Amba, etc.) to provide the corresponding subsystem specific implementation to register /
132 /// unregister a driver of the particular type (`DriverType`).
143 /// Registers a driver.
153 ) -> Result; in register()
155 /// Unregisters a driver previously registered with [`RegistrationOps::register`].
164 /// A [`Registration`] is a generic type that represents the registration of some driver type (e.g.
167 /// `T::unregister` calls result in the subsystem specific registration calls.
169 ///Once the `Registration` structure is dropped, the driver is unregistered.
186 // SAFETY: The driver core only ever calls the post unbind callback with a valid pointer to in post_unbind_callback()
193 // driver's device private data. in post_unbind_callback()
195 // SAFETY: By the safety requirements of the `Driver` trait, `T::DriverData` is the in post_unbind_callback()
196 // driver's device private data type. in post_unbind_callback()
205 // - `drv.get()` yields a valid pointer to `Self::DriverType`. in callbacks_attach()
206 // - Adding `DEVICE_DRIVER_OFFSET` yields the address of the embedded `struct device_driver` in callbacks_attach()
207 // as guaranteed by the safety requirements of the `Driver` trait. in callbacks_attach()
218 pub fn new(name: &'static CStr, module: &'static ThisModule) -> impl PinInit<Self, Error> { in new()
220 reg <- Opaque::try_ffi_init(|ptr: *mut T::DriverType| { in new()
246 /// Declares a kernel module that exposes a single driver.
258 _driver: $crate::driver::Registration<Ops<$type>>,
264 ) -> impl ::pin_init::PinInit<Self, $crate::error::Error> {
266 _driver <- $crate::driver::Registration::new(
283 /// This trait should be implemented by the bus specific adapter, which represents the connection
284 /// of a device and a driver.
286 /// It provides bus independent functions for device / driver interactions.
288 /// The type holding driver private data about each device id supported by the driver.
291 /// The [`acpi::IdTable`] of the corresponding driver
292 fn acpi_id_table() -> Option<acpi::IdTable<Self::IdInfo>>; in acpi_id_table()
294 /// Returns the driver's private data from the matching entry in the [`acpi::IdTable`], if any.
297 fn acpi_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> { in acpi_id_info()
309 // - `table` has static lifetime, hence it's valid for read, in acpi_id_info()
310 // - `dev` is guaranteed to be valid while it's alive, and so is `dev.as_raw()`. in acpi_id_info()
325 /// The [`of::IdTable`] of the corresponding driver.
326 fn of_id_table() -> Option<of::IdTable<Self::IdInfo>>; in of_id_table()
328 /// Returns the driver's private data from the matching entry in the [`of::IdTable`], if any.
331 fn of_id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> { in of_id_info()
343 // - `table` has static lifetime, hence it's valid for read, in of_id_info()
344 // - `dev` is guaranteed to be valid while it's alive, and so is `dev.as_raw()`. in of_id_info()
363 /// Returns the driver's private data from the matching entry of any of the ID tables, if any.
367 fn id_info(dev: &device::Device) -> Option<&'static Self::IdInfo> { in id_info()