1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
// SPDX-License-Identifier: GPL-2.0
//! Generic devices that are part of the kernel's driver model.
//!
//! C header: [`include/linux/device.h`](../../../../include/linux/device.h)
use crate::{bindings, error::code::*, error::Error, error::Result, str::CStr};
use core::fmt;
/// A raw device.
///
/// # Safety
///
/// Implementers must ensure that the `*mut device` returned by [`RawDevice::raw_device`] is
/// related to `self`, that is, actions on it will affect `self`. For example, if one calls
/// `get_device`, then the refcount on the device represented by `self` will be incremented.
///
/// Additionally, implementers must ensure that the device is never renamed. Commit a5462516aa99
/// ("driver-core: document restrictions on device_rename()") has details on why `device_rename`
/// should not be used.
pub unsafe trait RawDevice {
/// Returns the raw `struct device` related to `self`.
fn raw_device(&self) -> *mut bindings::device;
/// Returns the name of the device.
fn name(&self) -> &CStr {
let ptr = self.raw_device();
// SAFETY: `ptr` is valid because `self` keeps it alive.
let name = unsafe { bindings::dev_name(ptr) };
// SAFETY: The name of the device remains valid while it is alive (because the device is
// never renamed, per the safety requirement of this trait). This is guaranteed to be the
// case because the reference to `self` outlives the one of the returned `CStr` (enforced
// by the compiler because of their lifetimes).
unsafe { CStr::from_char_ptr(name) }
}
/// Prints an emergency-level message (level 0) prefixed with device information.
///
/// More details are available from [`dev_emerg`].
///
/// [`dev_emerg`]: crate::dev_emerg
fn pr_emerg(&self, args: fmt::Arguments<'_>) {
// SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
unsafe { self.printk(bindings::KERN_EMERG, args) };
}
/// Prints an alert-level message (level 1) prefixed with device information.
///
/// More details are available from [`dev_alert`].
///
/// [`dev_alert`]: crate::dev_alert
fn pr_alert(&self, args: fmt::Arguments<'_>) {
// SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
unsafe { self.printk(bindings::KERN_ALERT, args) };
}
/// Prints a critical-level message (level 2) prefixed with device information.
///
/// More details are available from [`dev_crit`].
///
/// [`dev_crit`]: crate::dev_crit
fn pr_crit(&self, args: fmt::Arguments<'_>) {
// SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
unsafe { self.printk(bindings::KERN_CRIT, args) };
}
/// Prints an error-level message (level 3) prefixed with device information.
///
/// More details are available from [`dev_err`].
///
/// [`dev_err`]: crate::dev_err
fn pr_err(&self, args: fmt::Arguments<'_>) {
// SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
unsafe { self.printk(bindings::KERN_ERR, args) };
}
/// Prints a warning-level message (level 4) prefixed with device information.
///
/// More details are available from [`dev_warn`].
///
/// [`dev_warn`]: crate::dev_warn
fn pr_warn(&self, args: fmt::Arguments<'_>) {
// SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
unsafe { self.printk(bindings::KERN_WARNING, args) };
}
/// Prints a notice-level message (level 5) prefixed with device information.
///
/// More details are available from [`dev_notice`].
///
/// [`dev_notice`]: crate::dev_notice
fn pr_notice(&self, args: fmt::Arguments<'_>) {
// SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
unsafe { self.printk(bindings::KERN_NOTICE, args) };
}
/// Prints an info-level message (level 6) prefixed with device information.
///
/// More details are available from [`dev_info`].
///
/// [`dev_info`]: crate::dev_info
fn pr_info(&self, args: fmt::Arguments<'_>) {
// SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
unsafe { self.printk(bindings::KERN_INFO, args) };
}
/// Prints a debug-level message (level 7) prefixed with device information.
///
/// More details are available from [`dev_dbg`].
///
/// [`dev_dbg`]: crate::dev_dbg
fn pr_dbg(&self, args: fmt::Arguments<'_>) {
if cfg!(debug_assertions) {
// SAFETY: `klevel` is null-terminated, uses one of the kernel constants.
unsafe { self.printk(bindings::KERN_DEBUG, args) };
}
}
/// Prints the provided message to the console.
///
/// # Safety
///
/// Callers must ensure that `klevel` is null-terminated; in particular, one of the
/// `KERN_*`constants, for example, `KERN_CRIT`, `KERN_ALERT`, etc.
#[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
unsafe fn printk(&self, klevel: &[u8], msg: fmt::Arguments<'_>) {
// SAFETY: `klevel` is null-terminated and one of the kernel constants. `self.raw_device`
// is valid because `self` is valid. The "%pA" format string expects a pointer to
// `fmt::Arguments`, which is what we're passing as the last argument.
#[cfg(CONFIG_PRINTK)]
unsafe {
bindings::_dev_printk(
klevel as *const _ as *const core::ffi::c_char,
self.raw_device(),
crate::c_str!("%pA").as_char_ptr(),
&msg as *const _ as *const core::ffi::c_void,
)
};
}
}
/// A ref-counted device.
///
/// # Invariants
///
/// `ptr` is valid, non-null, and has a non-zero reference count. One of the references is owned by
/// `self`, and will be decremented when `self` is dropped.
pub struct Device {
pub(crate) ptr: *mut bindings::device,
}
// SAFETY: `Device` only holds a pointer to a C device, which is safe to be used from any thread.
unsafe impl Send for Device {}
// SAFETY: `Device` only holds a pointer to a C device, references to which are safe to be used
// from any thread.
unsafe impl Sync for Device {}
impl Device {
/// Creates a new device instance.
///
/// # Safety
///
/// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count.
pub unsafe fn new(ptr: *mut bindings::device) -> Self {
// SAFETY: By the safety requirements, ptr is valid and its refcounted will be incremented.
unsafe { bindings::get_device(ptr) };
// INVARIANT: The safety requirements satisfy all but one invariant, which is that `self`
// owns a reference. This is satisfied by the call to `get_device` above.
Self { ptr }
}
/// Creates a new device instance from an existing [`RawDevice`] instance.
pub fn from_dev(dev: &dyn RawDevice) -> Self {
// SAFETY: The requirements are satisfied by the existence of `RawDevice` and its safety
// requirements.
unsafe { Self::new(dev.raw_device()) }
}
}
// SAFETY: The device returned by `raw_device` is the one for which we hold a reference.
unsafe impl RawDevice for Device {
fn raw_device(&self) -> *mut bindings::device {
self.ptr
}
}
impl Drop for Device {
fn drop(&mut self) {
// SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
// relinquish it now.
unsafe { bindings::put_device(self.ptr) };
}
}
impl Clone for Device {
fn clone(&self) -> Self {
Self::from_dev(self)
}
}
|
