Struct kernel::device::Device

pub struct Device(/* private fields */);

A reference-counted device.

This structure represents the Rust abstraction for a C struct device. This implementation abstracts the usage of an already existing C struct device within Rust code that we get passed from the C side.

An instance of this abstraction can be obtained temporarily or permanent.

A temporary one is bound to the lifetime of the C struct device pointer used for creation. A permanent instance is always reference-counted and hence not restricted by any lifetime boundaries.

For subsystems it is recommended to create a permanent instance to wrap into a subsystem specific device structure (e.g. pci::Device). This is useful for passing it to drivers in T::probe(), such that a driver can store the ARef<Device> (equivalent to storing a struct device pointer in a C driver) for arbitrary purposes, e.g. allocating DMA coherent memory.

Invariants

A Device instance represents a valid struct device created by the C portion of the kernel.

Instances of this type are always reference-counted, that is, a call to get_device ensures that the allocation remains valid at least until the matching call to put_device.

bindings::device::release is valid to be called from any thread, hence ARef<Device> can be dropped from any thread.

Implementations

impl Device

pub unsafe fn from_raw(ptr: *mut device) -> ARef<Self>

Creates a new reference-counted abstraction instance of an existing struct device pointer.

Safety

Callers must ensure that ptr is valid, non-null, and has a non-zero reference count, i.e. it must be ensured that the reference count of the C struct device ptr points to can’t drop to zero, for the duration of this function call.

It must also be ensured that bindings::device::release can be called from any thread. While not officially documented, this should be the case for any struct device.

pub unsafe fn as_ref<'a>(ptr: *mut device) -> &'a Self

Convert a raw C struct device pointer to a &'a Device.

Safety

Callers must ensure that ptr is valid, non-null, and has a non-zero reference count, i.e. it must be ensured that the reference count of the C struct device ptr points to can’t drop to zero, for the duration of this function call and the entire duration when the returned reference exists.

Trait Implementations

impl AlwaysRefCounted for Device

fn inc_ref(&self)

Increments the reference count on the object.

unsafe fn dec_ref(obj: NonNull<Self>)

Decrements the reference count on the object.

impl Send for Device

impl Sync for Device