Lines Matching +full:device +full:- +full:level
1 // SPDX-License-Identifier: GPL-2.0
5 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
19 /// The core representation of a device in the kernel's driver model.
21 /// This structure represents the Rust abstraction for a C `struct device`. A [`Device`] can either
22 /// exist as temporary reference (see also [`Device::from_raw`]), which is only valid within a
23 /// certain scope or as [`ARef<Device>`], owning a dedicated reference count.
25 /// # Device Types
27 /// A [`Device`] can represent either a bus device or a class device.
31 /// A bus device is a [`Device`] that is associated with a physical or virtual bus. Examples of
34 /// identifying information. Bus devices are visible in sysfs under `/sys/bus/<bus-name>/devices/`.
38 /// A class device is a [`Device`] that is associated with a logical category of functionality
41 /// userspace via entries in `/sys/class/<class-name>/`.
43 /// # Device Context
45 /// [`Device`] references are generic over a [`DeviceContext`], which represents the type state of
46 /// a [`Device`].
48 /// As the name indicates, this type state represents the context of the scope the [`Device`]
49 /// reference is valid in. For instance, the [`Bound`] context guarantees that the [`Device`] is
50 /// bound to a driver for the entire duration of the existence of a [`Device<Bound>`] reference.
54 /// Unless selected otherwise [`Device`] defaults to the [`Normal`] [`DeviceContext`], which by
57 /// It is always up to the caller of [`Device::from_raw`] to select the correct [`DeviceContext`]
58 /// type for the corresponding scope the [`Device`] reference is created in.
61 /// [bus devices](#bus-devices) only.
65 /// This section provides a guideline to implement bus specific devices, such as [`pci::Device`] or
66 /// [`platform::Device`].
68 /// A bus specific device should be defined as follows.
72 /// pub struct Device<Ctx: device::DeviceContext = device::Normal>(
78 /// Since devices are reference counted, [`AlwaysRefCounted`] should be implemented for `Device`
79 /// (i.e. `Device<Normal>`). Note that [`AlwaysRefCounted`] must not be implemented for any other
80 /// [`DeviceContext`], since all other device context types are only valid within a certain scope.
82 /// In order to be able to implement the [`DeviceContext`] dereference hierarchy, bus device
86 /// // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s
88 /// kernel::impl_device_context_deref!(unsafe { Device });
91 /// In order to convert from a any [`Device<Ctx>`] to [`ARef<Device>`], bus devices can implement
95 /// kernel::impl_device_context_into_aref!(Device);
99 /// easily derive a generic [`Device`] reference.
102 /// impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
103 /// fn as_ref(&self) -> &device::Device<Ctx> {
111 /// Class device implementations require less infrastructure and depend slightly more on the
114 /// An example implementation for a class device could look like this.
118 /// pub struct Device<T: class::Driver> {
124 /// This class device uses the sub-classing pattern to embed the driver's private data within the
125 /// allocation of the class device. For this to be possible the class device is generic over the
128 /// Just like any device, class devices are reference counted and should hence implement
129 /// [`AlwaysRefCounted`] for `Device`.
132 /// easily derive a generic [`Device`] reference.
135 /// impl<T: class::Driver> AsRef<device::Device> for Device<T> {
136 /// fn as_ref(&self) -> &device::Device {
142 /// An example for a class device implementation is
143 #[cfg_attr(CONFIG_DRM = "y", doc = "[`drm::Device`](kernel::drm::Device).")]
144 #[cfg_attr(not(CONFIG_DRM = "y"), doc = "`drm::Device`.")]
148 /// A `Device` instance represents a valid `struct device` created by the C portion of the kernel.
150 /// Instances of this type are always reference-counted, that is, a call to `get_device` ensures
153 /// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be
158 /// [`pci::Device`]: kernel::pci::Device
159 /// [`platform::Device`]: kernel::platform::Device
161 pub struct Device<Ctx: DeviceContext = Normal>(Opaque<bindings::device>, PhantomData<Ctx>); struct
163 impl Device { implementation
164 /// Creates a new reference-counted abstraction instance of an existing `struct device` pointer.
168 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
169 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
172 /// It must also be ensured that `bindings::device::release` can be called from any thread.
173 /// While not officially documented, this should be the case for any `struct device`.
174 pub unsafe fn get_device(ptr: *mut bindings::device) -> ARef<Self> { in get_device()
179 /// Convert a [`&Device`](Device) into a [`&Device<Bound>`](Device<Bound>).
183 /// The caller is responsible to ensure that the returned [`&Device<Bound>`](Device<Bound>)
184 /// only lives as long as it can be guaranteed that the [`Device`] is actually bound.
185 pub unsafe fn as_bound(&self) -> &Device<Bound> { in as_bound()
189 // returned reference only lives as long as the device is actually bound. in as_bound()
193 // - `ptr` comes from `from_ref(self)` above, hence it's guaranteed to be valid. in as_bound()
194 // - Any valid `Device` pointer is also a valid pointer for `Device<Bound>`. in as_bound()
199 impl Device<CoreInternal> { implementation
202 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in set_drvdata()
206 /// Take ownership of the private data stored in this [`Device`].
210 /// - Must only be called once after a preceding call to [`Device::set_drvdata`].
211 /// - The type `T` must match the type of the `ForeignOwnable` previously stored by
212 /// [`Device::set_drvdata`].
213 pub unsafe fn drvdata_obtain<T: ForeignOwnable>(&self) -> T { in drvdata_obtain()
214 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in drvdata_obtain()
218 // - By the safety requirements of this function, `ptr` comes from a previous call to in drvdata_obtain()
220 // - `dev_get_drvdata()` guarantees to return the same pointer given to `dev_set_drvdata()` in drvdata_obtain()
225 /// Borrow the driver's private data bound to this [`Device`].
229 /// - Must only be called after a preceding call to [`Device::set_drvdata`] and before
230 /// [`Device::drvdata_obtain`].
231 /// - The type `T` must match the type of the `ForeignOwnable` previously stored by
232 /// [`Device::set_drvdata`].
233 pub unsafe fn drvdata_borrow<T: ForeignOwnable>(&self) -> T::Borrowed<'_> { in drvdata_borrow()
234 // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`. in drvdata_borrow()
238 // - By the safety requirements of this function, `ptr` comes from a previous call to in drvdata_borrow()
240 // - `dev_get_drvdata()` guarantees to return the same pointer given to `dev_set_drvdata()` in drvdata_borrow()
246 impl<Ctx: DeviceContext> Device<Ctx> { implementation
247 /// Obtain the raw `struct device *`.
248 pub(crate) fn as_raw(&self) -> *mut bindings::device { in as_raw() argument
252 /// Returns a reference to the parent device, if any.
254 pub(crate) fn parent(&self) -> Option<&Device> { in parent() argument
256 // - By the type invariant `self.as_raw()` is always valid. in parent()
257 // - The parent device is only ever set at device creation. in parent()
264 // - Since `parent` is not NULL, it must be a valid pointer to a `struct device`. in parent()
265 // - `parent` is valid for the lifetime of `self`, since a `struct device` holds a in parent()
267 Some(unsafe { Device::from_raw(parent) }) in parent()
271 /// Convert a raw C `struct device` pointer to a `&'a Device`.
275 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
276 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
279 pub unsafe fn from_raw<'a>(ptr: *mut bindings::device) -> &'a Self { in from_raw()
284 /// Prints an emergency-level message (level 0) prefixed with device information.
290 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_emerg()
294 /// Prints an alert-level message (level 1) prefixed with device information.
300 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_alert()
304 /// Prints a critical-level message (level 2) prefixed with device information.
310 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_crit()
314 /// Prints an error-level message (level 3) prefixed with device information.
320 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_err()
324 /// Prints a warning-level message (level 4) prefixed with device information.
330 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_warn()
334 /// Prints a notice-level message (level 5) prefixed with device information.
340 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_notice()
344 /// Prints an info-level message (level 6) prefixed with device information.
350 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_info()
354 /// Prints a debug-level message (level 7) prefixed with device information.
361 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_dbg()
370 /// Callers must ensure that `klevel` is null-terminated; in particular, one of the
374 // SAFETY: `klevel` is null-terminated and one of the kernel constants. `self.as_raw` in printk()
388 /// Obtain the [`FwNode`](property::FwNode) corresponding to this [`Device`].
389 pub fn fwnode(&self) -> Option<&property::FwNode> { in fwnode()
404 // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
406 kernel::impl_device_context_deref!(unsafe { Device });
407 kernel::impl_device_context_into_aref!(Device);
409 // SAFETY: Instances of `Device` are always reference-counted.
410 unsafe impl crate::sync::aref::AlwaysRefCounted for Device { implementation
412 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero. in inc_ref()
417 // SAFETY: The safety requirements guarantee that the refcount is non-zero. in dec_ref()
422 // SAFETY: As by the type invariant `Device` can be sent to any thread.
423 unsafe impl Send for Device {} implementation
425 // SAFETY: `Device` can be shared among threads because all immutable methods are protected by the
426 // synchronization in `struct device`.
427 unsafe impl Sync for Device {} implementation
429 /// Marker trait for the context or scope of a bus specific device.
432 /// [`Device`].
434 /// The specific device context types are: [`CoreInternal`], [`Core`], [`Bound`] and [`Normal`].
438 /// [`Device<Core>`] can dereference to a [`Device<Bound>`].
442 /// - [`CoreInternal`] => [`Core`] => [`Bound`] => [`Normal`]
447 /// Note that the guarantee for a [`Device`] reference to have a certain [`DeviceContext`] comes
448 /// from the specific scope the [`Device`] reference is valid in.
453 /// The [`Normal`] context is the default [`DeviceContext`] of any [`Device`].
455 /// The normal context does not indicate any specific context. Any `Device<Ctx>` is also a valid
456 /// [`Device<Normal>`]. It is the only [`DeviceContext`] for which it is valid to implement
462 /// The [`Core`] context is the context of a bus specific device when it appears as argument of
465 /// The core context indicates that the [`Device<Core>`] reference's scope is limited to the bus
466 /// callback it appears in. It is intended to be used for synchronization purposes. Bus device
467 /// implementations can implement methods for [`Device<Core>`], such that they can only be called
478 /// This context mainly exists to share generic [`Device`] infrastructure that should only be called
482 /// The [`Bound`] context is the [`DeviceContext`] of a bus specific device when it is guaranteed to
485 /// The bound context indicates that for the entire duration of the lifetime of a [`Device<Bound>`]
486 /// reference, the [`Device`] is guaranteed to be bound to a driver.
488 /// Some APIs, such as [`dma::CoherentAllocation`] or [`Devres`] rely on the [`Device`] to be bound,
489 /// which can be proven with the [`Bound`] device context.
491 /// Any abstraction that can guarantee a scope where the corresponding bus device is bound, should
492 /// provide a [`Device<Bound>`] reference to its users for this scope. This allows users to benefit
493 /// from optimizations for accessing device resources, see also [`Devres::access`].
516 /// The type given as `$device` must be a transparent wrapper of a type that doesn't depend on the
517 /// generic argument of `$device`.
521 (unsafe { $device:ident, $src:ty => $dst:ty }) => {
522 impl ::core::ops::Deref for $device<$src> {
523 type Target = $device<$dst>;
525 fn deref(&self) -> &Self::Target {
528 // CAST: `$device<$src>` and `$device<$dst>` transparently wrap the same type by the
540 /// specific) device.
544 /// The type given as `$device` must be a transparent wrapper of a type that doesn't depend on the
545 /// generic argument of `$device`.
548 (unsafe { $device:ident }) => {
552 $device,
553 $crate::device::CoreInternal => $crate::device::Core
559 $device,
560 $crate::device::Core => $crate::device::Bound
566 $device,
567 $crate::device::Bound => $crate::device::Normal
575 ($src:ty, $device:tt) => {
576 impl ::core::convert::From<&$device<$src>> for $crate::sync::aref::ARef<$device> {
577 fn from(dev: &$device<$src>) -> Self {
584 /// Implement [`core::convert::From`], such that all `&Device<Ctx>` can be converted to an
585 /// `ARef<Device>`.
588 ($device:tt) => {
589 ::kernel::__impl_device_context_into_aref!($crate::device::CoreInternal, $device);
590 ::kernel::__impl_device_context_into_aref!($crate::device::Core, $device);
591 ::kernel::__impl_device_context_into_aref!($crate::device::Bound, $device);
605 /// Prints an emergency-level message (level 0) prefixed with device information.
607 /// This level should be used if the system is unusable.
614 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
615 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
620 /// # use kernel::device::Device;
622 /// fn example(dev: &Device) {
631 /// Prints an alert-level message (level 1) prefixed with device information.
633 /// This level should be used if action must be taken immediately.
640 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
641 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
646 /// # use kernel::device::Device;
648 /// fn example(dev: &Device) {
657 /// Prints a critical-level message (level 2) prefixed with device information.
659 /// This level should be used in critical conditions.
666 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
667 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
672 /// # use kernel::device::Device;
674 /// fn example(dev: &Device) {
683 /// Prints an error-level message (level 3) prefixed with device information.
685 /// This level should be used in error conditions.
692 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
693 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
698 /// # use kernel::device::Device;
700 /// fn example(dev: &Device) {
709 /// Prints a warning-level message (level 4) prefixed with device information.
711 /// This level should be used in warning conditions.
718 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
719 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
724 /// # use kernel::device::Device;
726 /// fn example(dev: &Device) {
735 /// Prints a notice-level message (level 5) prefixed with device information.
737 /// This level should be used in normal but significant conditions.
744 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
745 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
750 /// # use kernel::device::Device;
752 /// fn example(dev: &Device) {
761 /// Prints an info-level message (level 6) prefixed with device information.
763 /// This level should be used for informational messages.
770 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
771 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
776 /// # use kernel::device::Device;
778 /// fn example(dev: &Device) {
787 /// Prints a debug-level message (level 7) prefixed with device information.
789 /// This level should be used for debug messages.
796 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
797 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
802 /// # use kernel::device::Device;
804 /// fn example(dev: &Device) {