Lines Matching defs:Device
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
38 /// A class device is a [`Device`] that is associated with a logical category of functionality
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.
65 /// This section provides a guideline to implement bus specific devices, such as [`pci::Device`] or
66 /// [`platform::Device`].
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
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> {
118 /// pub struct Device<T: class::Driver> {
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 {
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.
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>);
163 impl 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> {
194 // - Any valid `Device` pointer is also a valid pointer for `Device<Bound>`.
199 impl Device<CoreInternal> {
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`].
212 /// [`Device::set_drvdata`].
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`].
232 /// [`Device::set_drvdata`].
246 impl<Ctx: DeviceContext> Device<Ctx> {
271 /// Convert a raw C `struct device` pointer to a `&'a Device`.
388 /// Obtain the [`FwNode`](property::FwNode) corresponding to this [`Device`].
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 {
422 // SAFETY: As by the type invariant `Device` can be sent to any thread.
423 unsafe impl Send for Device {}
425 // SAFETY: `Device` can be shared among threads because all immutable methods are protected by the
427 unsafe impl Sync for Device {}
432 /// [`Device`].
438 /// [`Device<Core>`] can dereference to a [`Device<Bound>`].
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
465 /// The core context indicates that the [`Device<Core>`] reference's scope is limited to the bus
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
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,
492 /// provide a [`Device<Bound>`] reference to its users for this scope. This allows users to benefit
584 /// Implement [`core::convert::From`], such that all `&Device<Ctx>` can be converted to an
585 /// `ARef<Device>`.
620 /// # use kernel::device::Device;
622 /// fn example(dev: &Device) {
646 /// # use kernel::device::Device;
648 /// fn example(dev: &Device) {
672 /// # use kernel::device::Device;
674 /// fn example(dev: &Device) {
698 /// # use kernel::device::Device;
700 /// fn example(dev: &Device) {
724 /// # use kernel::device::Device;
726 /// fn example(dev: &Device) {
750 /// # use kernel::device::Device;
752 /// fn example(dev: &Device) {
776 /// # use kernel::device::Device;
778 /// fn example(dev: &Device) {
802 /// # use kernel::device::Device;
804 /// fn example(dev: &Device) {