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    types::{ARef, ForeignOwnable, Opaque},
10};
11use core::{fmt, marker::PhantomData, ptr};
12
13#[cfg(CONFIG_PRINTK)]
14use crate::c_str;
15
16pub mod property;
17
18/// A reference-counted device.
19///
20/// This structure represents the Rust abstraction for a C `struct device`. This implementation
21/// abstracts the usage of an already existing C `struct device` within Rust code that we get
22/// passed from the C side.
23///
24/// An instance of this abstraction can be obtained temporarily or permanent.
25///
26/// A temporary one is bound to the lifetime of the C `struct device` pointer used for creation.
27/// A permanent instance is always reference-counted and hence not restricted by any lifetime
28/// boundaries.
29///
30/// For subsystems it is recommended to create a permanent instance to wrap into a subsystem
31/// specific device structure (e.g. `pci::Device`). This is useful for passing it to drivers in
32/// `T::probe()`, such that a driver can store the `ARef<Device>` (equivalent to storing a
33/// `struct device` pointer in a C driver) for arbitrary purposes, e.g. allocating DMA coherent
34/// memory.
35///
36/// # Invariants
37///
38/// A `Device` instance represents a valid `struct device` created by the C portion of the kernel.
39///
40/// Instances of this type are always reference-counted, that is, a call to `get_device` ensures
41/// that the allocation remains valid at least until the matching call to `put_device`.
42///
43/// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be
44/// dropped from any thread.
45#[repr(transparent)]
46pub struct Device<Ctx: DeviceContext = Normal>(Opaque<bindings::device>, PhantomData<Ctx>);
47
48impl Device {
49    /// Creates a new reference-counted abstraction instance of an existing `struct device` pointer.
50    ///
51    /// # Safety
52    ///
53    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
54    /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
55    /// can't drop to zero, for the duration of this function call.
56    ///
57    /// It must also be ensured that `bindings::device::release` can be called from any thread.
58    /// While not officially documented, this should be the case for any `struct device`.
59    pub unsafe fn get_device(ptr: *mut bindings::device) -> ARef<Self> {
60        // SAFETY: By the safety requirements ptr is valid
61        unsafe { Self::from_raw(ptr) }.into()
62    }
63
64    /// Convert a [`&Device`](Device) into a [`&Device<Bound>`](Device<Bound>).
65    ///
66    /// # Safety
67    ///
68    /// The caller is responsible to ensure that the returned [`&Device<Bound>`](Device<Bound>)
69    /// only lives as long as it can be guaranteed that the [`Device`] is actually bound.
70    pub unsafe fn as_bound(&self) -> &Device<Bound> {
71        let ptr = core::ptr::from_ref(self);
72
73        // CAST: By the safety requirements the caller is responsible to guarantee that the
74        // returned reference only lives as long as the device is actually bound.
75        let ptr = ptr.cast();
76
77        // SAFETY:
78        // - `ptr` comes from `from_ref(self)` above, hence it's guaranteed to be valid.
79        // - Any valid `Device` pointer is also a valid pointer for `Device<Bound>`.
80        unsafe { &*ptr }
81    }
82}
83
84impl Device<CoreInternal> {
85    /// Store a pointer to the bound driver's private data.
86    pub fn set_drvdata(&self, data: impl ForeignOwnable) {
87        // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`.
88        unsafe { bindings::dev_set_drvdata(self.as_raw(), data.into_foreign().cast()) }
89    }
90
91    /// Take ownership of the private data stored in this [`Device`].
92    ///
93    /// # Safety
94    ///
95    /// - Must only be called once after a preceding call to [`Device::set_drvdata`].
96    /// - The type `T` must match the type of the `ForeignOwnable` previously stored by
97    ///   [`Device::set_drvdata`].
98    pub unsafe fn drvdata_obtain<T: ForeignOwnable>(&self) -> T {
99        // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`.
100        let ptr = unsafe { bindings::dev_get_drvdata(self.as_raw()) };
101
102        // SAFETY:
103        // - By the safety requirements of this function, `ptr` comes from a previous call to
104        //   `into_foreign()`.
105        // - `dev_get_drvdata()` guarantees to return the same pointer given to `dev_set_drvdata()`
106        //   in `into_foreign()`.
107        unsafe { T::from_foreign(ptr.cast()) }
108    }
109
110    /// Borrow the driver's private data bound to this [`Device`].
111    ///
112    /// # Safety
113    ///
114    /// - Must only be called after a preceding call to [`Device::set_drvdata`] and before
115    ///   [`Device::drvdata_obtain`].
116    /// - The type `T` must match the type of the `ForeignOwnable` previously stored by
117    ///   [`Device::set_drvdata`].
118    pub unsafe fn drvdata_borrow<T: ForeignOwnable>(&self) -> T::Borrowed<'_> {
119        // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`.
120        let ptr = unsafe { bindings::dev_get_drvdata(self.as_raw()) };
121
122        // SAFETY:
123        // - By the safety requirements of this function, `ptr` comes from a previous call to
124        //   `into_foreign()`.
125        // - `dev_get_drvdata()` guarantees to return the same pointer given to `dev_set_drvdata()`
126        //   in `into_foreign()`.
127        unsafe { T::borrow(ptr.cast()) }
128    }
129}
130
131impl<Ctx: DeviceContext> Device<Ctx> {
132    /// Obtain the raw `struct device *`.
133    pub(crate) fn as_raw(&self) -> *mut bindings::device {
134        self.0.get()
135    }
136
137    /// Returns a reference to the parent device, if any.
138    #[cfg_attr(not(CONFIG_AUXILIARY_BUS), expect(dead_code))]
139    pub(crate) fn parent(&self) -> Option<&Self> {
140        // SAFETY:
141        // - By the type invariant `self.as_raw()` is always valid.
142        // - The parent device is only ever set at device creation.
143        let parent = unsafe { (*self.as_raw()).parent };
144
145        if parent.is_null() {
146            None
147        } else {
148            // SAFETY:
149            // - Since `parent` is not NULL, it must be a valid pointer to a `struct device`.
150            // - `parent` is valid for the lifetime of `self`, since a `struct device` holds a
151            //   reference count of its parent.
152            Some(unsafe { Self::from_raw(parent) })
153        }
154    }
155
156    /// Convert a raw C `struct device` pointer to a `&'a Device`.
157    ///
158    /// # Safety
159    ///
160    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
161    /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
162    /// can't drop to zero, for the duration of this function call and the entire duration when the
163    /// returned reference exists.
164    pub unsafe fn from_raw<'a>(ptr: *mut bindings::device) -> &'a Self {
165        // SAFETY: Guaranteed by the safety requirements of the function.
166        unsafe { &*ptr.cast() }
167    }
168
169    /// Prints an emergency-level message (level 0) prefixed with device information.
170    ///
171    /// More details are available from [`dev_emerg`].
172    ///
173    /// [`dev_emerg`]: crate::dev_emerg
174    pub fn pr_emerg(&self, args: fmt::Arguments<'_>) {
175        // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
176        unsafe { self.printk(bindings::KERN_EMERG, args) };
177    }
178
179    /// Prints an alert-level message (level 1) prefixed with device information.
180    ///
181    /// More details are available from [`dev_alert`].
182    ///
183    /// [`dev_alert`]: crate::dev_alert
184    pub fn pr_alert(&self, args: fmt::Arguments<'_>) {
185        // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
186        unsafe { self.printk(bindings::KERN_ALERT, args) };
187    }
188
189    /// Prints a critical-level message (level 2) prefixed with device information.
190    ///
191    /// More details are available from [`dev_crit`].
192    ///
193    /// [`dev_crit`]: crate::dev_crit
194    pub fn pr_crit(&self, args: fmt::Arguments<'_>) {
195        // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
196        unsafe { self.printk(bindings::KERN_CRIT, args) };
197    }
198
199    /// Prints an error-level message (level 3) prefixed with device information.
200    ///
201    /// More details are available from [`dev_err`].
202    ///
203    /// [`dev_err`]: crate::dev_err
204    pub fn pr_err(&self, args: fmt::Arguments<'_>) {
205        // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
206        unsafe { self.printk(bindings::KERN_ERR, args) };
207    }
208
209    /// Prints a warning-level message (level 4) prefixed with device information.
210    ///
211    /// More details are available from [`dev_warn`].
212    ///
213    /// [`dev_warn`]: crate::dev_warn
214    pub fn pr_warn(&self, args: fmt::Arguments<'_>) {
215        // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
216        unsafe { self.printk(bindings::KERN_WARNING, args) };
217    }
218
219    /// Prints a notice-level message (level 5) prefixed with device information.
220    ///
221    /// More details are available from [`dev_notice`].
222    ///
223    /// [`dev_notice`]: crate::dev_notice
224    pub fn pr_notice(&self, args: fmt::Arguments<'_>) {
225        // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
226        unsafe { self.printk(bindings::KERN_NOTICE, args) };
227    }
228
229    /// Prints an info-level message (level 6) prefixed with device information.
230    ///
231    /// More details are available from [`dev_info`].
232    ///
233    /// [`dev_info`]: crate::dev_info
234    pub fn pr_info(&self, args: fmt::Arguments<'_>) {
235        // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
236        unsafe { self.printk(bindings::KERN_INFO, args) };
237    }
238
239    /// Prints a debug-level message (level 7) prefixed with device information.
240    ///
241    /// More details are available from [`dev_dbg`].
242    ///
243    /// [`dev_dbg`]: crate::dev_dbg
244    pub fn pr_dbg(&self, args: fmt::Arguments<'_>) {
245        if cfg!(debug_assertions) {
246            // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
247            unsafe { self.printk(bindings::KERN_DEBUG, args) };
248        }
249    }
250
251    /// Prints the provided message to the console.
252    ///
253    /// # Safety
254    ///
255    /// Callers must ensure that `klevel` is null-terminated; in particular, one of the
256    /// `KERN_*`constants, for example, `KERN_CRIT`, `KERN_ALERT`, etc.
257    #[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
258    unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
259        // SAFETY: `klevel` is null-terminated and one of the kernel constants. `self.as_raw`
260        // is valid because `self` is valid. The "%pA" format string expects a pointer to
261        // `fmt::Arguments`, which is what we're passing as the last argument.
262        #[cfg(CONFIG_PRINTK)]
263        unsafe {
264            bindings::_dev_printk(
265                klevel.as_ptr().cast::<crate::ffi::c_char>(),
266                self.as_raw(),
267                c_str!("%pA").as_char_ptr(),
268                core::ptr::from_ref(&msg).cast::<crate::ffi::c_void>(),
269            )
270        };
271    }
272
273    /// Obtain the [`FwNode`](property::FwNode) corresponding to this [`Device`].
274    pub fn fwnode(&self) -> Option<&property::FwNode> {
275        // SAFETY: `self` is valid.
276        let fwnode_handle = unsafe { bindings::__dev_fwnode(self.as_raw()) };
277        if fwnode_handle.is_null() {
278            return None;
279        }
280        // SAFETY: `fwnode_handle` is valid. Its lifetime is tied to `&self`. We
281        // return a reference instead of an `ARef<FwNode>` because `dev_fwnode()`
282        // doesn't increment the refcount. It is safe to cast from a
283        // `struct fwnode_handle*` to a `*const FwNode` because `FwNode` is
284        // defined as a `#[repr(transparent)]` wrapper around `fwnode_handle`.
285        Some(unsafe { &*fwnode_handle.cast() })
286    }
287}
288
289// SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
290// argument.
291kernel::impl_device_context_deref!(unsafe { Device });
292kernel::impl_device_context_into_aref!(Device);
293
294// SAFETY: Instances of `Device` are always reference-counted.
295unsafe impl crate::types::AlwaysRefCounted for Device {
296    fn inc_ref(&self) {
297        // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
298        unsafe { bindings::get_device(self.as_raw()) };
299    }
300
301    unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
302        // SAFETY: The safety requirements guarantee that the refcount is non-zero.
303        unsafe { bindings::put_device(obj.cast().as_ptr()) }
304    }
305}
306
307// SAFETY: As by the type invariant `Device` can be sent to any thread.
308unsafe impl Send for Device {}
309
310// SAFETY: `Device` can be shared among threads because all immutable methods are protected by the
311// synchronization in `struct device`.
312unsafe impl Sync for Device {}
313
314/// Marker trait for the context of a bus specific device.
315///
316/// Some functions of a bus specific device should only be called from a certain context, i.e. bus
317/// callbacks, such as `probe()`.
318///
319/// This is the marker trait for structures representing the context of a bus specific device.
320pub trait DeviceContext: private::Sealed {}
321
322/// The [`Normal`] context is the context of a bus specific device when it is not an argument of
323/// any bus callback.
324pub struct Normal;
325
326/// The [`Core`] context is the context of a bus specific device when it is supplied as argument of
327/// any of the bus callbacks, such as `probe()`.
328pub struct Core;
329
330/// Semantically the same as [`Core`] but reserved for internal usage of the corresponding bus
331/// abstraction.
332pub struct CoreInternal;
333
334/// The [`Bound`] context is the context of a bus specific device reference when it is guaranteed to
335/// be bound for the duration of its lifetime.
336pub struct Bound;
337
338mod private {
339    pub trait Sealed {}
340
341    impl Sealed for super::Bound {}
342    impl Sealed for super::Core {}
343    impl Sealed for super::CoreInternal {}
344    impl Sealed for super::Normal {}
345}
346
347impl DeviceContext for Bound {}
348impl DeviceContext for Core {}
349impl DeviceContext for CoreInternal {}
350impl DeviceContext for Normal {}
351
352/// # Safety
353///
354/// The type given as `$device` must be a transparent wrapper of a type that doesn't depend on the
355/// generic argument of `$device`.
356#[doc(hidden)]
357#[macro_export]
358macro_rules! __impl_device_context_deref {
359    (unsafe { $device:ident, $src:ty => $dst:ty }) => {
360        impl ::core::ops::Deref for $device<$src> {
361            type Target = $device<$dst>;
362
363            fn deref(&self) -> &Self::Target {
364                let ptr: *const Self = self;
365
366                // CAST: `$device<$src>` and `$device<$dst>` transparently wrap the same type by the
367                // safety requirement of the macro.
368                let ptr = ptr.cast::<Self::Target>();
369
370                // SAFETY: `ptr` was derived from `&self`.
371                unsafe { &*ptr }
372            }
373        }
374    };
375}
376
377/// Implement [`core::ops::Deref`] traits for allowed [`DeviceContext`] conversions of a (bus
378/// specific) device.
379///
380/// # Safety
381///
382/// The type given as `$device` must be a transparent wrapper of a type that doesn't depend on the
383/// generic argument of `$device`.
384#[macro_export]
385macro_rules! impl_device_context_deref {
386    (unsafe { $device:ident }) => {
387        // SAFETY: This macro has the exact same safety requirement as
388        // `__impl_device_context_deref!`.
389        ::kernel::__impl_device_context_deref!(unsafe {
390            $device,
391            $crate::device::CoreInternal => $crate::device::Core
392        });
393
394        // SAFETY: This macro has the exact same safety requirement as
395        // `__impl_device_context_deref!`.
396        ::kernel::__impl_device_context_deref!(unsafe {
397            $device,
398            $crate::device::Core => $crate::device::Bound
399        });
400
401        // SAFETY: This macro has the exact same safety requirement as
402        // `__impl_device_context_deref!`.
403        ::kernel::__impl_device_context_deref!(unsafe {
404            $device,
405            $crate::device::Bound => $crate::device::Normal
406        });
407    };
408}
409
410#[doc(hidden)]
411#[macro_export]
412macro_rules! __impl_device_context_into_aref {
413    ($src:ty, $device:tt) => {
414        impl ::core::convert::From<&$device<$src>> for $crate::types::ARef<$device> {
415            fn from(dev: &$device<$src>) -> Self {
416                (&**dev).into()
417            }
418        }
419    };
420}
421
422/// Implement [`core::convert::From`], such that all `&Device<Ctx>` can be converted to an
423/// `ARef<Device>`.
424#[macro_export]
425macro_rules! impl_device_context_into_aref {
426    ($device:tt) => {
427        ::kernel::__impl_device_context_into_aref!($crate::device::CoreInternal, $device);
428        ::kernel::__impl_device_context_into_aref!($crate::device::Core, $device);
429        ::kernel::__impl_device_context_into_aref!($crate::device::Bound, $device);
430    };
431}
432
433#[doc(hidden)]
434#[macro_export]
435macro_rules! dev_printk {
436    ($method:ident, $dev:expr, $($f:tt)*) => {
437        {
438            ($dev).$method(::core::format_args!($($f)*));
439        }
440    }
441}
442
443/// Prints an emergency-level message (level 0) prefixed with device information.
444///
445/// This level should be used if the system is unusable.
446///
447/// Equivalent to the kernel's `dev_emerg` macro.
448///
449/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
450/// [`core::fmt`] and [`std::format!`].
451///
452/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
453/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
454///
455/// # Examples
456///
457/// ```
458/// # use kernel::device::Device;
459///
460/// fn example(dev: &Device) {
461///     dev_emerg!(dev, "hello {}\n", "there");
462/// }
463/// ```
464#[macro_export]
465macro_rules! dev_emerg {
466    ($($f:tt)*) => { $crate::dev_printk!(pr_emerg, $($f)*); }
467}
468
469/// Prints an alert-level message (level 1) prefixed with device information.
470///
471/// This level should be used if action must be taken immediately.
472///
473/// Equivalent to the kernel's `dev_alert` macro.
474///
475/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
476/// [`core::fmt`] and [`std::format!`].
477///
478/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
479/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
480///
481/// # Examples
482///
483/// ```
484/// # use kernel::device::Device;
485///
486/// fn example(dev: &Device) {
487///     dev_alert!(dev, "hello {}\n", "there");
488/// }
489/// ```
490#[macro_export]
491macro_rules! dev_alert {
492    ($($f:tt)*) => { $crate::dev_printk!(pr_alert, $($f)*); }
493}
494
495/// Prints a critical-level message (level 2) prefixed with device information.
496///
497/// This level should be used in critical conditions.
498///
499/// Equivalent to the kernel's `dev_crit` macro.
500///
501/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
502/// [`core::fmt`] and [`std::format!`].
503///
504/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
505/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
506///
507/// # Examples
508///
509/// ```
510/// # use kernel::device::Device;
511///
512/// fn example(dev: &Device) {
513///     dev_crit!(dev, "hello {}\n", "there");
514/// }
515/// ```
516#[macro_export]
517macro_rules! dev_crit {
518    ($($f:tt)*) => { $crate::dev_printk!(pr_crit, $($f)*); }
519}
520
521/// Prints an error-level message (level 3) prefixed with device information.
522///
523/// This level should be used in error conditions.
524///
525/// Equivalent to the kernel's `dev_err` macro.
526///
527/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
528/// [`core::fmt`] and [`std::format!`].
529///
530/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
531/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
532///
533/// # Examples
534///
535/// ```
536/// # use kernel::device::Device;
537///
538/// fn example(dev: &Device) {
539///     dev_err!(dev, "hello {}\n", "there");
540/// }
541/// ```
542#[macro_export]
543macro_rules! dev_err {
544    ($($f:tt)*) => { $crate::dev_printk!(pr_err, $($f)*); }
545}
546
547/// Prints a warning-level message (level 4) prefixed with device information.
548///
549/// This level should be used in warning conditions.
550///
551/// Equivalent to the kernel's `dev_warn` macro.
552///
553/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
554/// [`core::fmt`] and [`std::format!`].
555///
556/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
557/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
558///
559/// # Examples
560///
561/// ```
562/// # use kernel::device::Device;
563///
564/// fn example(dev: &Device) {
565///     dev_warn!(dev, "hello {}\n", "there");
566/// }
567/// ```
568#[macro_export]
569macro_rules! dev_warn {
570    ($($f:tt)*) => { $crate::dev_printk!(pr_warn, $($f)*); }
571}
572
573/// Prints a notice-level message (level 5) prefixed with device information.
574///
575/// This level should be used in normal but significant conditions.
576///
577/// Equivalent to the kernel's `dev_notice` macro.
578///
579/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
580/// [`core::fmt`] and [`std::format!`].
581///
582/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
583/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
584///
585/// # Examples
586///
587/// ```
588/// # use kernel::device::Device;
589///
590/// fn example(dev: &Device) {
591///     dev_notice!(dev, "hello {}\n", "there");
592/// }
593/// ```
594#[macro_export]
595macro_rules! dev_notice {
596    ($($f:tt)*) => { $crate::dev_printk!(pr_notice, $($f)*); }
597}
598
599/// Prints an info-level message (level 6) prefixed with device information.
600///
601/// This level should be used for informational messages.
602///
603/// Equivalent to the kernel's `dev_info` macro.
604///
605/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
606/// [`core::fmt`] and [`std::format!`].
607///
608/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
609/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
610///
611/// # Examples
612///
613/// ```
614/// # use kernel::device::Device;
615///
616/// fn example(dev: &Device) {
617///     dev_info!(dev, "hello {}\n", "there");
618/// }
619/// ```
620#[macro_export]
621macro_rules! dev_info {
622    ($($f:tt)*) => { $crate::dev_printk!(pr_info, $($f)*); }
623}
624
625/// Prints a debug-level message (level 7) prefixed with device information.
626///
627/// This level should be used for debug messages.
628///
629/// Equivalent to the kernel's `dev_dbg` macro, except that it doesn't support dynamic debug yet.
630///
631/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
632/// [`core::fmt`] and [`std::format!`].
633///
634/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
635/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
636///
637/// # Examples
638///
639/// ```
640/// # use kernel::device::Device;
641///
642/// fn example(dev: &Device) {
643///     dev_dbg!(dev, "hello {}\n", "there");
644/// }
645/// ```
646#[macro_export]
647macro_rules! dev_dbg {
648    ($($f:tt)*) => { $crate::dev_printk!(pr_dbg, $($f)*); }
649}