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 7 use crate::{ 8 bindings, 9 types::{ARef, Opaque}, 10 }; 11 use core::{fmt, ptr}; 12 13 #[cfg(CONFIG_PRINTK)] 14 use 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)] 44 pub struct Device(Opaque<bindings::device>); 45 46 impl 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. 186 unsafe 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. 199 unsafe 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`. 203 unsafe impl Sync for Device {} 204 205 #[doc(hidden)] 206 #[macro_export] 207 macro_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] 236 macro_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] 261 macro_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] 286 macro_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] 311 macro_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] 336 macro_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] 361 macro_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] 386 macro_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] 411 macro_rules! dev_dbg { 412 ($($f:tt)*) => { $crate::dev_printk!(pr_dbg, $($f)*); } 413 } 414