projects/linux·blob v6.13 · refs

413 lines · 13.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::{fmt, ptr};
12
13#[cfg(CONFIG_PRINTK)]
14use crate::c_str;
15
16/// A reference-counted device.
17///
18/// This structure represents the Rust abstraction for a C `struct device`. This implementation
19/// abstracts the usage of an already existing C `struct device` within Rust code that we get
20/// passed from the C side.
21///
22/// An instance of this abstraction can be obtained temporarily or permanent.
23///
24/// A temporary one is bound to the lifetime of the C `struct device` pointer used for creation.
25/// A permanent instance is always reference-counted and hence not restricted by any lifetime
26/// boundaries.
27///
28/// For subsystems it is recommended to create a permanent instance to wrap into a subsystem
29/// specific device structure (e.g. `pci::Device`). This is useful for passing it to drivers in
30/// `T::probe()`, such that a driver can store the `ARef<Device>` (equivalent to storing a
31/// `struct device` pointer in a C driver) for arbitrary purposes, e.g. allocating DMA coherent
32/// memory.
33///
34/// # Invariants
35///
36/// A `Device` instance represents a valid `struct device` created by the C portion of the kernel.
37///
38/// Instances of this type are always reference-counted, that is, a call to `get_device` ensures
39/// that the allocation remains valid at least until the matching call to `put_device`.
40///
41/// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be
42/// dropped from any thread.
43#[repr(transparent)]
44pub struct Device(Opaque<bindings::device>);
45
46impl Device {
47 /// Creates a new reference-counted abstraction instance of an existing `struct device` pointer.
48 ///
49 /// # Safety
50 ///
51 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
52 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
53 /// can't drop to zero, for the duration of this function call.
54 ///
55 /// It must also be ensured that `bindings::device::release` can be called from any thread.
56 /// While not officially documented, this should be the case for any `struct device`.
57 pub unsafe fn get_device(ptr: *mut bindings::device) -> ARef<Self> {
58 // SAFETY: By the safety requirements ptr is valid
59 unsafe { Self::as_ref(ptr) }.into()
60 }
61
62 /// Obtain the raw `struct device *`.
63 pub(crate) fn as_raw(&self) -> *mut bindings::device {
64 self.0.get()
65 }
66
67 /// Convert a raw C `struct device` pointer to a `&'a Device`.
68 ///
69 /// # Safety
70 ///
71 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
72 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
73 /// can't drop to zero, for the duration of this function call and the entire duration when the
74 /// returned reference exists.
75 pub unsafe fn as_ref<'a>(ptr: *mut bindings::device) -> &'a Self {
76 // SAFETY: Guaranteed by the safety requirements of the function.
77 unsafe { &*ptr.cast() }
78 }
79
80 /// Prints an emergency-level message (level 0) prefixed with device information.
81 ///
82 /// More details are available from [`dev_emerg`].
83 ///
84 /// [`dev_emerg`]: crate::dev_emerg
85 pub fn pr_emerg(&self, args: fmt::Arguments<'_>) {
86 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
87 unsafe { self.printk(bindings::KERN_EMERG, args) };
88 }
89
90 /// Prints an alert-level message (level 1) prefixed with device information.
91 ///
92 /// More details are available from [`dev_alert`].
93 ///
94 /// [`dev_alert`]: crate::dev_alert
95 pub fn pr_alert(&self, args: fmt::Arguments<'_>) {
96 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
97 unsafe { self.printk(bindings::KERN_ALERT, args) };
98 }
99
100 /// Prints a critical-level message (level 2) prefixed with device information.
101 ///
102 /// More details are available from [`dev_crit`].
103 ///
104 /// [`dev_crit`]: crate::dev_crit
105 pub fn pr_crit(&self, args: fmt::Arguments<'_>) {
106 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
107 unsafe { self.printk(bindings::KERN_CRIT, args) };
108 }
109
110 /// Prints an error-level message (level 3) prefixed with device information.
111 ///
112 /// More details are available from [`dev_err`].
113 ///
114 /// [`dev_err`]: crate::dev_err
115 pub fn pr_err(&self, args: fmt::Arguments<'_>) {
116 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
117 unsafe { self.printk(bindings::KERN_ERR, args) };
118 }
119
120 /// Prints a warning-level message (level 4) prefixed with device information.
121 ///
122 /// More details are available from [`dev_warn`].
123 ///
124 /// [`dev_warn`]: crate::dev_warn
125 pub fn pr_warn(&self, args: fmt::Arguments<'_>) {
126 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
127 unsafe { self.printk(bindings::KERN_WARNING, args) };
128 }
129
130 /// Prints a notice-level message (level 5) prefixed with device information.
131 ///
132 /// More details are available from [`dev_notice`].
133 ///
134 /// [`dev_notice`]: crate::dev_notice
135 pub fn pr_notice(&self, args: fmt::Arguments<'_>) {
136 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
137 unsafe { self.printk(bindings::KERN_NOTICE, args) };
138 }
139
140 /// Prints an info-level message (level 6) prefixed with device information.
141 ///
142 /// More details are available from [`dev_info`].
143 ///
144 /// [`dev_info`]: crate::dev_info
145 pub fn pr_info(&self, args: fmt::Arguments<'_>) {
146 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
147 unsafe { self.printk(bindings::KERN_INFO, args) };
148 }
149
150 /// Prints a debug-level message (level 7) prefixed with device information.
151 ///
152 /// More details are available from [`dev_dbg`].
153 ///
154 /// [`dev_dbg`]: crate::dev_dbg
155 pub fn pr_dbg(&self, args: fmt::Arguments<'_>) {
156 if cfg!(debug_assertions) {
157 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
158 unsafe { self.printk(bindings::KERN_DEBUG, args) };
159 }
160 }
161
162 /// Prints the provided message to the console.
163 ///
164 /// # Safety
165 ///
166 /// Callers must ensure that `klevel` is null-terminated; in particular, one of the
167 /// `KERN_*`constants, for example, `KERN_CRIT`, `KERN_ALERT`, etc.
168 #[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
169 unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
170 // SAFETY: `klevel` is null-terminated and one of the kernel constants. `self.as_raw`
171 // is valid because `self` is valid. The "%pA" format string expects a pointer to
172 // `fmt::Arguments`, which is what we're passing as the last argument.
173 #[cfg(CONFIG_PRINTK)]
174 unsafe {
175 bindings::_dev_printk(
176 klevel as *const _ as *const core::ffi::c_char,
177 self.as_raw(),
178 c_str!("%pA").as_char_ptr(),
179 &msg as *const _ as *const core::ffi::c_void,
180 )
181 };
182 }
183}
184
185// SAFETY: Instances of `Device` are always reference-counted.
186unsafe impl crate::types::AlwaysRefCounted for Device {
187 fn inc_ref(&self) {
188 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
189 unsafe { bindings::get_device(self.as_raw()) };
190 }
191
192 unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
193 // SAFETY: The safety requirements guarantee that the refcount is non-zero.
194 unsafe { bindings::put_device(obj.cast().as_ptr()) }
195 }
196}
197
198// SAFETY: As by the type invariant `Device` can be sent to any thread.
199unsafe impl Send for Device {}
200
201// SAFETY: `Device` can be shared among threads because all immutable methods are protected by the
202// synchronization in `struct device`.
203unsafe impl Sync for Device {}
204
205#[doc(hidden)]
206#[macro_export]
207macro_rules! dev_printk {
208 ($method:ident, $dev:expr, $($f:tt)*) => {
209 {
210 ($dev).$method(core::format_args!($($f)*));
211 }
212 }
213}
214
215/// Prints an emergency-level message (level 0) prefixed with device information.
216///
217/// This level should be used if the system is unusable.
218///
219/// Equivalent to the kernel's `dev_emerg` macro.
220///
221/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
222/// [`core::fmt`] and `alloc::format!`.
223///
224/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
225///
226/// # Examples
227///
228/// ```
229/// # use kernel::device::Device;
230///
231/// fn example(dev: &Device) {
232/// dev_emerg!(dev, "hello {}\n", "there");
233/// }
234/// ```
235#[macro_export]
236macro_rules! dev_emerg {
237 ($($f:tt)*) => { $crate::dev_printk!(pr_emerg, $($f)*); }
238}
239
240/// Prints an alert-level message (level 1) prefixed with device information.
241///
242/// This level should be used if action must be taken immediately.
243///
244/// Equivalent to the kernel's `dev_alert` macro.
245///
246/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
247/// [`core::fmt`] and `alloc::format!`.
248///
249/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
250///
251/// # Examples
252///
253/// ```
254/// # use kernel::device::Device;
255///
256/// fn example(dev: &Device) {
257/// dev_alert!(dev, "hello {}\n", "there");
258/// }
259/// ```
260#[macro_export]
261macro_rules! dev_alert {
262 ($($f:tt)*) => { $crate::dev_printk!(pr_alert, $($f)*); }
263}
264
265/// Prints a critical-level message (level 2) prefixed with device information.
266///
267/// This level should be used in critical conditions.
268///
269/// Equivalent to the kernel's `dev_crit` macro.
270///
271/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
272/// [`core::fmt`] and `alloc::format!`.
273///
274/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
275///
276/// # Examples
277///
278/// ```
279/// # use kernel::device::Device;
280///
281/// fn example(dev: &Device) {
282/// dev_crit!(dev, "hello {}\n", "there");
283/// }
284/// ```
285#[macro_export]
286macro_rules! dev_crit {
287 ($($f:tt)*) => { $crate::dev_printk!(pr_crit, $($f)*); }
288}
289
290/// Prints an error-level message (level 3) prefixed with device information.
291///
292/// This level should be used in error conditions.
293///
294/// Equivalent to the kernel's `dev_err` macro.
295///
296/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
297/// [`core::fmt`] and `alloc::format!`.
298///
299/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
300///
301/// # Examples
302///
303/// ```
304/// # use kernel::device::Device;
305///
306/// fn example(dev: &Device) {
307/// dev_err!(dev, "hello {}\n", "there");
308/// }
309/// ```
310#[macro_export]
311macro_rules! dev_err {
312 ($($f:tt)*) => { $crate::dev_printk!(pr_err, $($f)*); }
313}
314
315/// Prints a warning-level message (level 4) prefixed with device information.
316///
317/// This level should be used in warning conditions.
318///
319/// Equivalent to the kernel's `dev_warn` macro.
320///
321/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
322/// [`core::fmt`] and `alloc::format!`.
323///
324/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
325///
326/// # Examples
327///
328/// ```
329/// # use kernel::device::Device;
330///
331/// fn example(dev: &Device) {
332/// dev_warn!(dev, "hello {}\n", "there");
333/// }
334/// ```
335#[macro_export]
336macro_rules! dev_warn {
337 ($($f:tt)*) => { $crate::dev_printk!(pr_warn, $($f)*); }
338}
339
340/// Prints a notice-level message (level 5) prefixed with device information.
341///
342/// This level should be used in normal but significant conditions.
343///
344/// Equivalent to the kernel's `dev_notice` macro.
345///
346/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
347/// [`core::fmt`] and `alloc::format!`.
348///
349/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
350///
351/// # Examples
352///
353/// ```
354/// # use kernel::device::Device;
355///
356/// fn example(dev: &Device) {
357/// dev_notice!(dev, "hello {}\n", "there");
358/// }
359/// ```
360#[macro_export]
361macro_rules! dev_notice {
362 ($($f:tt)*) => { $crate::dev_printk!(pr_notice, $($f)*); }
363}
364
365/// Prints an info-level message (level 6) prefixed with device information.
366///
367/// This level should be used for informational messages.
368///
369/// Equivalent to the kernel's `dev_info` macro.
370///
371/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
372/// [`core::fmt`] and `alloc::format!`.
373///
374/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
375///
376/// # Examples
377///
378/// ```
379/// # use kernel::device::Device;
380///
381/// fn example(dev: &Device) {
382/// dev_info!(dev, "hello {}\n", "there");
383/// }
384/// ```
385#[macro_export]
386macro_rules! dev_info {
387 ($($f:tt)*) => { $crate::dev_printk!(pr_info, $($f)*); }
388}
389
390/// Prints a debug-level message (level 7) prefixed with device information.
391///
392/// This level should be used for debug messages.
393///
394/// Equivalent to the kernel's `dev_dbg` macro, except that it doesn't support dynamic debug yet.
395///
396/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
397/// [`core::fmt`] and `alloc::format!`.
398///
399/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
400///
401/// # Examples
402///
403/// ```
404/// # use kernel::device::Device;
405///
406/// fn example(dev: &Device) {
407/// dev_dbg!(dev, "hello {}\n", "there");
408/// }
409/// ```
410#[macro_export]
411macro_rules! dev_dbg {
412 ($($f:tt)*) => { $crate::dev_printk!(pr_dbg, $($f)*); }
413}