Lines Matching full:device
5 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
28 /// The core representation of a device in the kernel's driver model.
30 /// This structure represents the Rust abstraction for a C `struct device`. A [`Device`] can either
31 /// exist as temporary reference (see also [`Device::from_raw`]), which is only valid within a
32 /// certain scope or as [`ARef<Device>`], owning a dedicated reference count.
34 /// # Device Types
36 /// A [`Device`] can represent either a bus device or a class device.
40 /// A bus device is a [`Device`] that is associated with a physical or virtual bus. Examples of
47 /// A class device is a [`Device`] that is associated with a logical category of functionality
52 /// # Device Context
54 /// [`Device`] references are generic over a [`DeviceContext`], which represents the type state of
55 /// a [`Device`].
57 /// As the name indicates, this type state represents the context of the scope the [`Device`]
58 /// reference is valid in. For instance, the [`Bound`] context guarantees that the [`Device`] is
59 /// bound to a driver for the entire duration of the existence of a [`Device<Bound>`] reference.
63 /// Unless selected otherwise [`Device`] defaults to the [`Normal`] [`DeviceContext`], which by
66 /// It is always up to the caller of [`Device::from_raw`] to select the correct [`DeviceContext`]
67 /// type for the corresponding scope the [`Device`] reference is created in.
75 #[cfg_attr(CONFIG_PCI, doc = "* [`pci::Device`](kernel::pci::Device)")]
76 /// * [`platform::Device`]
78 /// A bus specific device should be defined as follows.
82 /// pub struct Device<Ctx: device::DeviceContext = device::Normal>(
88 /// Since devices are reference counted, [`AlwaysRefCounted`] should be implemented for `Device`
89 /// (i.e. `Device<Normal>`). Note that [`AlwaysRefCounted`] must not be implemented for any other
90 /// [`DeviceContext`], since all other device context types are only valid within a certain scope.
92 /// In order to be able to implement the [`DeviceContext`] dereference hierarchy, bus device
96 /// // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s
98 /// kernel::impl_device_context_deref!(unsafe { Device });
101 /// In order to convert from a any [`Device<Ctx>`] to [`ARef<Device>`], bus devices can implement
105 /// kernel::impl_device_context_into_aref!(Device);
109 /// easily derive a generic [`Device`] reference.
112 /// impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
113 /// fn as_ref(&self) -> &device::Device<Ctx> {
121 /// Class device implementations require less infrastructure and depend slightly more on the
124 /// An example implementation for a class device could look like this.
128 /// pub struct Device<T: class::Driver> {
134 /// This class device uses the sub-classing pattern to embed the driver's private data within the
135 /// allocation of the class device. For this to be possible the class device is generic over the
138 /// Just like any device, class devices are reference counted and should hence implement
139 /// [`AlwaysRefCounted`] for `Device`.
142 /// easily derive a generic [`Device`] reference.
145 /// impl<T: class::Driver> AsRef<device::Device> for Device<T> {
146 /// fn as_ref(&self) -> &device::Device {
152 /// An example for a class device implementation is
153 #[cfg_attr(CONFIG_DRM = "y", doc = "[`drm::Device`](kernel::drm::Device).")]
154 #[cfg_attr(not(CONFIG_DRM = "y"), doc = "`drm::Device`.")]
158 /// A `Device` instance represents a valid `struct device` created by the C portion of the kernel.
163 /// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be
168 /// [`platform::Device`]: kernel::platform::Device
170 pub struct Device<Ctx: DeviceContext = Normal>(Opaque<bindings::device>, PhantomData<Ctx>); struct
172 impl Device { impl
173 /// Creates a new reference-counted abstraction instance of an existing `struct device` pointer.
178 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
181 /// It must also be ensured that `bindings::device::release` can be called from any thread.
182 /// While not officially documented, this should be the case for any `struct device`.
183 pub unsafe fn get_device(ptr: *mut bindings::device) -> ARef<Self> { in get_device()
188 /// Convert a [`&Device`](Device) into a [`&Device<Bound>`](Device<Bound>).
192 /// The caller is responsible to ensure that the returned [`&Device<Bound>`](Device<Bound>)
193 /// only lives as long as it can be guaranteed that the [`Device`] is actually bound.
194 pub unsafe fn as_bound(&self) -> &Device<Bound> { in as_bound()
198 // returned reference only lives as long as the device is actually bound. in as_bound()
203 // - Any valid `Device` pointer is also a valid pointer for `Device<Bound>`. in as_bound()
208 impl Device<CoreInternal> { implementation
210 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in set_type_id()
213 // SAFETY: For a bound device (implied by the `CoreInternal` device context), `private` is in set_type_id()
229 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in set_drvdata()
236 /// Take ownership of the private data stored in this [`Device`].
241 /// [`Device::set_drvdata`].
243 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in drvdata_obtain()
246 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in drvdata_obtain()
260 /// Borrow the driver's private data bound to this [`Device`].
264 /// - Must only be called after a preceding call to [`Device::set_drvdata`] and before the
265 /// device is fully unbound.
267 /// [`Device::set_drvdata`].
275 impl Device<Bound> { implementation
276 /// Borrow the driver's private data bound to this [`Device`].
280 /// - Must only be called after a preceding call to [`Device::set_drvdata`] and before
281 /// the device is fully unbound.
283 /// [`Device::set_drvdata`].
285 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in drvdata_unchecked()
297 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in match_type_id()
300 // SAFETY: For a bound device, `private` is guaranteed to be a valid pointer to a in match_type_id()
306 // - A bound device guarantees that `driver_type` contains a valid `TypeId` value. in match_type_id()
321 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in drvdata()
336 impl<Ctx: DeviceContext> Device<Ctx> { impl
337 /// Obtain the raw `struct device *`.
338 pub(crate) fn as_raw(&self) -> *mut bindings::device { in as_raw() argument
342 /// Returns a reference to the parent device, if any.
344 pub(crate) fn parent(&self) -> Option<&Device> { in parent() argument
347 // - The parent device is only ever set at device creation. in parent()
354 // - Since `parent` is not NULL, it must be a valid pointer to a `struct device`. in parent()
355 // - `parent` is valid for the lifetime of `self`, since a `struct device` holds a in parent()
357 Some(unsafe { Device::from_raw(parent) }) in parent()
361 /// Convert a raw C `struct device` pointer to a `&'a Device`.
366 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
369 pub unsafe fn from_raw<'a>(ptr: *mut bindings::device) -> &'a Self { in from_raw()
374 /// Prints an emergency-level message (level 0) prefixed with device information.
384 /// Prints an alert-level message (level 1) prefixed with device information.
394 /// Prints a critical-level message (level 2) prefixed with device information.
404 /// Prints an error-level message (level 3) prefixed with device information.
414 /// Prints a warning-level message (level 4) prefixed with device information.
424 /// Prints a notice-level message (level 5) prefixed with device information.
434 /// Prints an info-level message (level 6) prefixed with device information.
444 /// Prints a debug-level message (level 7) prefixed with device information.
478 /// Obtain the [`FwNode`](property::FwNode) corresponding to this [`Device`].
494 // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
496 kernel::impl_device_context_deref!(unsafe { Device });
497 kernel::impl_device_context_into_aref!(Device);
499 // SAFETY: Instances of `Device` are always reference-counted.
500 unsafe impl crate::sync::aref::AlwaysRefCounted for Device { implementation
512 // SAFETY: As by the type invariant `Device` can be sent to any thread.
513 unsafe impl Send for Device {} implementation
515 // SAFETY: `Device` can be shared among threads because all immutable methods are protected by the
516 // synchronization in `struct device`.
517 unsafe impl Sync for Device {} implementation
519 /// Marker trait for the context or scope of a bus specific device.
522 /// [`Device`].
524 /// The specific device context types are: [`CoreInternal`], [`Core`], [`Bound`] and [`Normal`].
528 /// [`Device<Core>`] can dereference to a [`Device<Bound>`].
537 /// Note that the guarantee for a [`Device`] reference to have a certain [`DeviceContext`] comes
538 /// from the specific scope the [`Device`] reference is valid in.
543 /// The [`Normal`] context is the default [`DeviceContext`] of any [`Device`].
545 /// The normal context does not indicate any specific context. Any `Device<Ctx>` is also a valid
546 /// [`Device<Normal>`]. It is the only [`DeviceContext`] for which it is valid to implement
552 /// The [`Core`] context is the context of a bus specific device when it appears as argument of
555 /// The core context indicates that the [`Device<Core>`] reference's scope is limited to the bus
556 /// callback it appears in. It is intended to be used for synchronization purposes. Bus device
557 /// implementations can implement methods for [`Device<Core>`], such that they can only be called
568 /// This context mainly exists to share generic [`Device`] infrastructure that should only be called
572 /// The [`Bound`] context is the [`DeviceContext`] of a bus specific device when it is guaranteed to
575 /// The bound context indicates that for the entire duration of the lifetime of a [`Device<Bound>`]
576 /// reference, the [`Device`] is guaranteed to be bound to a driver.
578 /// Some APIs, such as [`dma::CoherentAllocation`] or [`Devres`] rely on the [`Device`] to be bound,
579 /// which can be proven with the [`Bound`] device context.
581 /// Any abstraction that can guarantee a scope where the corresponding bus device is bound, should
582 /// provide a [`Device<Bound>`] reference to its users for this scope. This allows users to benefit
583 /// from optimizations for accessing device resources, see also [`Devres::access`].
604 impl<Ctx: DeviceContext> AsRef<Device<Ctx>> for Device<Ctx> { implementation
606 fn as_ref(&self) -> &Device<Ctx> { in as_ref()
611 /// Convert device references to bus device references.
613 /// Bus devices can implement this trait to allow abstractions to provide the bus device in
614 /// class device callbacks.
616 /// This must not be used by drivers and is intended for bus and class device abstractions only.
620 /// `AsBusDevice::OFFSET` must be the offset of the embedded base `struct device` field within a
621 /// bus device structure.
622 pub unsafe trait AsBusDevice<Ctx: DeviceContext>: AsRef<Device<Ctx>> {
623 /// The relative offset to the device field.
628 /// Convert a reference to [`Device`] into `Self`.
633 unsafe fn from_device(dev: &Device<Ctx>) -> &Self in from_device()
646 /// The type given as `$device` must be a transparent wrapper of a type that doesn't depend on the
647 /// generic argument of `$device`.
651 (unsafe { $device:ident, $src:ty => $dst:ty }) => {
652 impl ::core::ops::Deref for $device<$src> {
653 type Target = $device<$dst>;
658 // CAST: `$device<$src>` and `$device<$dst>` transparently wrap the same type by the
670 /// specific) device.
674 /// The type given as `$device` must be a transparent wrapper of a type that doesn't depend on the
675 /// generic argument of `$device`.
678 (unsafe { $device:ident }) => {
682 $device,
683 $crate::device::CoreInternal => $crate::device::Core
689 $device,
690 $crate::device::Core => $crate::device::Bound
696 $device,
697 $crate::device::Bound => $crate::device::Normal
705 ($src:ty, $device:tt) => {
706 impl ::core::convert::From<&$device<$src>> for $crate::sync::aref::ARef<$device> {
707 fn from(dev: &$device<$src>) -> Self {
714 /// Implement [`core::convert::From`], such that all `&Device<Ctx>` can be converted to an
715 /// `ARef<Device>`.
718 ($device:tt) => {
719 ::kernel::__impl_device_context_into_aref!($crate::device::CoreInternal, $device);
720 ::kernel::__impl_device_context_into_aref!($crate::device::Core, $device);
721 ::kernel::__impl_device_context_into_aref!($crate::device::Bound, $device);
730 $crate::device::Device::$method($dev.as_ref(), $crate::prelude::fmt!($($f)*))
735 /// Prints an emergency-level message (level 0) prefixed with device information.
750 /// # use kernel::device::Device;
752 /// fn example(dev: &Device) {
761 /// Prints an alert-level message (level 1) prefixed with device information.
776 /// # use kernel::device::Device;
778 /// fn example(dev: &Device) {
787 /// Prints a critical-level message (level 2) prefixed with device information.
802 /// # use kernel::device::Device;
804 /// fn example(dev: &Device) {
813 /// Prints an error-level message (level 3) prefixed with device information.
828 /// # use kernel::device::Device;
830 /// fn example(dev: &Device) {
839 /// Prints a warning-level message (level 4) prefixed with device information.
854 /// # use kernel::device::Device;
856 /// fn example(dev: &Device) {
865 /// Prints a notice-level message (level 5) prefixed with device information.
880 /// # use kernel::device::Device;
882 /// fn example(dev: &Device) {
891 /// Prints an info-level message (level 6) prefixed with device information.
906 /// # use kernel::device::Device;
908 /// fn example(dev: &Device) {
917 /// Prints a debug-level message (level 7) prefixed with device information.
932 /// # use kernel::device::Device;
934 /// fn example(dev: &Device) {