97 lines · rust
1// SPDX-License-Identifier: GPL-2.02 3//! Generic devices that are part of the kernel's driver model.4//!5//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)6 7use crate::{8 bindings,9 types::{ARef, Opaque},10};11use core::ptr;12 13/// A reference-counted device.14///15/// This structure represents the Rust abstraction for a C `struct device`. This implementation16/// abstracts the usage of an already existing C `struct device` within Rust code that we get17/// passed from the C side.18///19/// An instance of this abstraction can be obtained temporarily or permanent.20///21/// A temporary one is bound to the lifetime of the C `struct device` pointer used for creation.22/// A permanent instance is always reference-counted and hence not restricted by any lifetime23/// boundaries.24///25/// For subsystems it is recommended to create a permanent instance to wrap into a subsystem26/// specific device structure (e.g. `pci::Device`). This is useful for passing it to drivers in27/// `T::probe()`, such that a driver can store the `ARef<Device>` (equivalent to storing a28/// `struct device` pointer in a C driver) for arbitrary purposes, e.g. allocating DMA coherent29/// memory.30///31/// # Invariants32///33/// A `Device` instance represents a valid `struct device` created by the C portion of the kernel.34///35/// Instances of this type are always reference-counted, that is, a call to `get_device` ensures36/// that the allocation remains valid at least until the matching call to `put_device`.37///38/// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be39/// dropped from any thread.40#[repr(transparent)]41pub struct Device(Opaque<bindings::device>);42 43impl Device {44 /// Creates a new reference-counted abstraction instance of an existing `struct device` pointer.45 ///46 /// # Safety47 ///48 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,49 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to50 /// can't drop to zero, for the duration of this function call.51 ///52 /// It must also be ensured that `bindings::device::release` can be called from any thread.53 /// While not officially documented, this should be the case for any `struct device`.54 pub unsafe fn get_device(ptr: *mut bindings::device) -> ARef<Self> {55 // SAFETY: By the safety requirements ptr is valid56 unsafe { Self::as_ref(ptr) }.into()57 }58 59 /// Obtain the raw `struct device *`.60 pub(crate) fn as_raw(&self) -> *mut bindings::device {61 self.0.get()62 }63 64 /// Convert a raw C `struct device` pointer to a `&'a Device`.65 ///66 /// # Safety67 ///68 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,69 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to70 /// can't drop to zero, for the duration of this function call and the entire duration when the71 /// returned reference exists.72 pub unsafe fn as_ref<'a>(ptr: *mut bindings::device) -> &'a Self {73 // SAFETY: Guaranteed by the safety requirements of the function.74 unsafe { &*ptr.cast() }75 }76}77 78// SAFETY: Instances of `Device` are always reference-counted.79unsafe impl crate::types::AlwaysRefCounted for Device {80 fn inc_ref(&self) {81 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.82 unsafe { bindings::get_device(self.as_raw()) };83 }84 85 unsafe fn dec_ref(obj: ptr::NonNull<Self>) {86 // SAFETY: The safety requirements guarantee that the refcount is non-zero.87 unsafe { bindings::put_device(obj.cast().as_ptr()) }88 }89}90 91// SAFETY: As by the type invariant `Device` can be sent to any thread.92unsafe impl Send for Device {}93 94// SAFETY: `Device` can be shared among threads because all immutable methods are protected by the95// synchronization in `struct device`.96unsafe impl Sync for Device {}97