1 // SPDX-License-Identifier: GPL-2.0
5 //! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
17 /// A reference-counted device.
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
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
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
37 /// A `Device` instance represents a valid `struct device` created by the C portion of the kernel.
39 /// Instances of this type are always reference-counted, that is, a call to `get_device` ensures
42 /// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be
45 pub struct Device(Opaque<bindings::device>);  struct
47 impl Device {  impl
48     /// Creates a new reference-counted abstraction instance of an existing `struct device` pointer.
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
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> {  in get_device()
63     /// Obtain the raw `struct device *`.
64     pub(crate) fn as_raw(&self) -> *mut bindings::device {  in as_raw()  argument
68     /// Convert a raw C `struct device` pointer to a `&'a Device`.
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
76     pub unsafe fn as_ref<'a>(ptr: *mut bindings::device) -> &'a Self {  in as_ref()
81     /// Prints an emergency-level message (level 0) prefixed with device information.
87         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.  in pr_emerg()
91     /// Prints an alert-level message (level 1) prefixed with device information.
97         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.  in pr_alert()
101     /// Prints a critical-level message (level 2) prefixed with device information.
107         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.  in pr_crit()
111     /// Prints an error-level message (level 3) prefixed with device information.
117         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.  in pr_err()
121     /// Prints a warning-level message (level 4) prefixed with device information.
127         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.  in pr_warn()
131     /// Prints a notice-level message (level 5) prefixed with device information.
137         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.  in pr_notice()
141     /// Prints an info-level message (level 6) prefixed with device information.
147         // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.  in pr_info()
151     /// Prints a debug-level message (level 7) prefixed with device information.
158             // SAFETY: `klevel` is null-terminated, uses one of the kernel constants.  in pr_dbg()
167     /// Callers must ensure that `klevel` is null-terminated; in particular, one of the
171         // SAFETY: `klevel` is null-terminated and one of the kernel constants. `self.as_raw`  in printk()
186     pub fn property_present(&self, name: &CStr) -> bool {  in property_present()
187         // SAFETY: By the invariant of `CStr`, `name` is null-terminated.  in property_present()
192 // SAFETY: Instances of `Device` are always reference-counted.
193 unsafe impl crate::types::AlwaysRefCounted for Device {  implementation
195         // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.  in inc_ref()
200         // SAFETY: The safety requirements guarantee that the refcount is non-zero.  in dec_ref()
205 // SAFETY: As by the type invariant `Device` can be sent to any thread.
206 unsafe impl Send for Device {}  implementation
208 // SAFETY: `Device` can be shared among threads because all immutable methods are protected by the
209 // synchronization in `struct device`.
210 unsafe impl Sync for Device {}  implementation
222 /// Prints an emergency-level message (level 0) prefixed with device information.
224 /// This level should be used if the system is unusable.
231 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
236 /// # use kernel::device::Device;
238 /// fn example(dev: &Device) {
247 /// Prints an alert-level message (level 1) prefixed with device information.
249 /// This level should be used if action must be taken immediately.
256 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
261 /// # use kernel::device::Device;
263 /// fn example(dev: &Device) {
272 /// Prints a critical-level message (level 2) prefixed with device information.
274 /// This level should be used in critical conditions.
281 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
286 /// # use kernel::device::Device;
288 /// fn example(dev: &Device) {
297 /// Prints an error-level message (level 3) prefixed with device information.
299 /// This level should be used in error conditions.
306 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
311 /// # use kernel::device::Device;
313 /// fn example(dev: &Device) {
322 /// Prints a warning-level message (level 4) prefixed with device information.
324 /// This level should be used in warning conditions.
331 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
336 /// # use kernel::device::Device;
338 /// fn example(dev: &Device) {
347 /// Prints a notice-level message (level 5) prefixed with device information.
349 /// This level should be used in normal but significant conditions.
356 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
361 /// # use kernel::device::Device;
363 /// fn example(dev: &Device) {
372 /// Prints an info-level message (level 6) prefixed with device information.
374 /// This level should be used for informational messages.
381 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
386 /// # use kernel::device::Device;
388 /// fn example(dev: &Device) {
397 /// Prints a debug-level message (level 7) prefixed with device information.
399 /// This level should be used for debug messages.
406 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
411 /// # use kernel::device::Device;
413 /// fn example(dev: &Device) {