projects/linux·blob v6.11 · refs

105 lines · 4.5 KiB

1// SPDX-License-Identifier: GPL-2.0
2
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 implementation
16/// abstracts the usage of an already existing C `struct device` within Rust code that we get
17/// 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 lifetime
23/// boundaries.
24///
25/// For subsystems it is recommended to create a permanent instance to wrap into a subsystem
26/// specific device structure (e.g. `pci::Device`). This is useful for passing it to drivers in
27/// `T::probe()`, such that a driver can store the `ARef<Device>` (equivalent to storing a
28/// `struct device` pointer in a C driver) for arbitrary purposes, e.g. allocating DMA coherent
29/// memory.
30///
31/// # Invariants
32///
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` ensures
36/// 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 be
39/// 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 /// # Safety
47 ///
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 to
50 /// 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 from_raw(ptr: *mut bindings::device) -> ARef<Self> {
55 // SAFETY: By the safety requirements, ptr is valid.
56 // Initially increase the reference count by one to compensate for the final decrement once
57 // this newly created `ARef<Device>` instance is dropped.
58 unsafe { bindings::get_device(ptr) };
59
60 // CAST: `Self` is a `repr(transparent)` wrapper around `bindings::device`.
61 let ptr = ptr.cast::<Self>();
62
63 // SAFETY: `ptr` is valid by the safety requirements of this function. By the above call to
64 // `bindings::get_device` we also own a reference to the underlying `struct device`.
65 unsafe { ARef::from_raw(ptr::NonNull::new_unchecked(ptr)) }
66 }
67
68 /// Obtain the raw `struct device *`.
69 pub(crate) fn as_raw(&self) -> *mut bindings::device {
70 self.0.get()
71 }
72
73 /// Convert a raw C `struct device` pointer to a `&'a Device`.
74 ///
75 /// # Safety
76 ///
77 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
78 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
79 /// can't drop to zero, for the duration of this function call and the entire duration when the
80 /// returned reference exists.
81 pub unsafe fn as_ref<'a>(ptr: *mut bindings::device) -> &'a Self {
82 // SAFETY: Guaranteed by the safety requirements of the function.
83 unsafe { &*ptr.cast() }
84 }
85}
86
87// SAFETY: Instances of `Device` are always reference-counted.
88unsafe impl crate::types::AlwaysRefCounted for Device {
89 fn inc_ref(&self) {
90 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
91 unsafe { bindings::get_device(self.as_raw()) };
92 }
93
94 unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
95 // SAFETY: The safety requirements guarantee that the refcount is non-zero.
96 unsafe { bindings::put_device(obj.cast().as_ptr()) }
97 }
98}
99
100// SAFETY: As by the type invariant `Device` can be sent to any thread.
101unsafe impl Send for Device {}
102
103// SAFETY: `Device` can be shared among threads because all immutable methods are protected by the
104// synchronization in `struct device`.
105unsafe impl Sync for Device {}