rust/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
   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 }