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