Lines Matching +full:reference +full:- +full:sync
1 // SPDX-License-Identifier: GPL-2.0
11 sync::aref::ARef,
27 /// exist as temporary reference (see also [`Device::from_raw`]), which is only valid within a
28 /// certain scope or as [`ARef<Device>`], owning a dedicated reference count.
39 /// identifying information. Bus devices are visible in sysfs under `/sys/bus/<bus-name>/devices/`.
46 /// userspace via entries in `/sys/class/<class-name>/`.
54 /// reference is valid in. For instance, the [`Bound`] context guarantees that the [`Device`] is
55 /// bound to a driver for the entire duration of the existence of a [`Device<Bound>`] reference.
64 /// type for the corresponding scope the [`Device`] reference is created in.
67 /// [bus devices](#bus-devices) only.
85 /// Since devices are reference counted, [`AlwaysRefCounted`] should be implemented for `Device`
106 /// easily derive a generic [`Device`] reference.
110 /// fn as_ref(&self) -> &device::Device<Ctx> {
131 /// This class device uses the sub-classing pattern to embed the driver's private data within the
135 /// Just like any device, class devices are reference counted and should hence implement
139 /// easily derive a generic [`Device`] reference.
143 /// fn as_ref(&self) -> &device::Device {
157 /// Instances of this type are always reference-counted, that is, a call to `get_device` ensures
163 /// [`AlwaysRefCounted`]: kernel::sync::aref::AlwaysRefCounted
170 /// Creates a new reference-counted abstraction instance of an existing `struct device` pointer.
174 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
175 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
180 pub unsafe fn get_device(ptr: *mut bindings::device) -> ARef<Self> { in get_device()
191 pub unsafe fn as_bound(&self) -> &Device<Bound> { in as_bound()
195 // returned reference only lives as long as the device is actually bound. in as_bound()
199 // - `ptr` comes from `from_ref(self)` above, hence it's guaranteed to be valid. in as_bound()
200 // - Any valid `Device` pointer is also a valid pointer for `Device<Bound>`. in as_bound()
207 pub fn set_drvdata<T>(&self, data: impl PinInit<T, Error>) -> Result { in set_drvdata()
220 /// - The type `T` must match the type of the `ForeignOwnable` previously stored by
222 pub(crate) unsafe fn drvdata_obtain<T>(&self) -> Option<Pin<KBox<T>>> { in drvdata_obtain()
234 // - If `ptr` is not NULL, it comes from a previous call to `into_foreign()`. in drvdata_obtain()
235 // - `dev_get_drvdata()` guarantees to return the same pointer given to `dev_set_drvdata()` in drvdata_obtain()
246 /// - Must only be called after a preceding call to [`Device::set_drvdata`] and before the
248 /// - The type `T` must match the type of the `ForeignOwnable` previously stored by
250 pub unsafe fn drvdata_borrow<T>(&self) -> Pin<&T> { in drvdata_borrow()
255 // - By the safety requirements of this function, `ptr` comes from a previous call to in drvdata_borrow()
257 // - `dev_get_drvdata()` guarantees to return the same pointer given to `dev_set_drvdata()` in drvdata_borrow()
265 pub(crate) fn as_raw(&self) -> *mut bindings::device { in as_raw()
269 /// Returns a reference to the parent device, if any.
271 pub(crate) fn parent(&self) -> Option<&Device> { in parent()
273 // - By the type invariant `self.as_raw()` is always valid. in parent()
274 // - The parent device is only ever set at device creation. in parent()
281 // - Since `parent` is not NULL, it must be a valid pointer to a `struct device`. in parent()
282 // - `parent` is valid for the lifetime of `self`, since a `struct device` holds a in parent()
283 // reference count of its parent. in parent()
292 /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
293 /// i.e. it must be ensured that the reference count of the C `struct device` `ptr` points to
295 /// returned reference exists.
296 pub unsafe fn from_raw<'a>(ptr: *mut bindings::device) -> &'a Self { in from_raw()
301 /// Prints an emergency-level message (level 0) prefixed with device information.
307 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_emerg()
311 /// Prints an alert-level message (level 1) prefixed with device information.
317 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_alert()
321 /// Prints a critical-level message (level 2) prefixed with device information.
327 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_crit()
331 /// Prints an error-level message (level 3) prefixed with device information.
337 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_err()
341 /// Prints a warning-level message (level 4) prefixed with device information.
347 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_warn()
351 /// Prints a notice-level message (level 5) prefixed with device information.
357 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_notice()
361 /// Prints an info-level message (level 6) prefixed with device information.
367 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_info()
371 /// Prints a debug-level message (level 7) prefixed with device information.
378 // SAFETY: `klevel` is null-terminated, uses one of the kernel constants. in pr_dbg()
387 /// Callers must ensure that `klevel` is null-terminated; in particular, one of the
391 // SAFETY: `klevel` is null-terminated and one of the kernel constants. `self.as_raw` in printk()
406 pub fn fwnode(&self) -> Option<&property::FwNode> { in fwnode()
413 // return a reference instead of an `ARef<FwNode>` because `dev_fwnode()` in fwnode()
425 pub fn name(&self) -> &CStr { in name()
437 // SAFETY: Instances of `Device` are always reference-counted.
438 unsafe impl crate::sync::aref::AlwaysRefCounted for Device {
440 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero. in inc_ref()
445 // SAFETY: The safety requirements guarantee that the refcount is non-zero. in dec_ref()
455 unsafe impl Sync for Device {}
457 // SAFETY: Same as `Device<Normal>` -- the underlying `struct device` is the same; `Bound` is a
458 // zero-sized type-state marker that does not affect thread safety.
459 unsafe impl Sync for Device<Bound> {}
475 /// - [`CoreInternal`] => [`Core`] => [`Bound`] => [`Normal`]
476 /// - [`BoundInternal`] => [`Bound`] => [`Normal`]
485 /// Note that the guarantee for a [`Device`] reference to have a certain [`DeviceContext`] comes
486 /// from the specific scope the [`Device`] reference is valid in.
497 /// [`AlwaysRefCounted`]: kernel::sync::aref::AlwaysRefCounted
503 /// The core context indicates that the [`Device<Core>`] reference's scope is limited to the bus
511 pub struct Core<'a>(PhantomData<fn(&'a ()) -> &'a ()>);
524 pub struct CoreInternal<'a>(PhantomData<fn(&'a ()) -> &'a ()>);
542 /// reference, the [`Device`] is guaranteed to be bound to a driver.
548 /// provide a [`Device<Bound>`] reference to its users for this scope. This allows users to benefit
572 /// Marker trait for [`DeviceContext`] types that have internal bound-level access.
584 fn as_ref(&self) -> &Device<Ctx> { in as_ref()
606 /// Convert a reference to [`Device`] into `Self`.
611 unsafe fn from_device(dev: &Device<Ctx>) -> &Self in from_device()
616 // SAFETY: `raw - Self::OFFSET` is guaranteed by the safety requirements in from_device()
633 fn deref(&self) -> &Self::Target {
649 fn deref(&self) -> &Self::Target {
707 impl<$lt> ::core::convert::From<&$device<$src>> for $crate::sync::aref::ARef<$device> {
708 fn from(dev: &$device<$src>) -> Self {
714 impl ::core::convert::From<&$device<$src>> for $crate::sync::aref::ARef<$device> {
715 fn from(dev: &$device<$src>) -> Self {
746 /// Prints an emergency-level message (level 0) prefixed with device information.
755 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
756 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
772 /// Prints an alert-level message (level 1) prefixed with device information.
781 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
782 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
798 /// Prints a critical-level message (level 2) prefixed with device information.
807 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
808 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
824 /// Prints an error-level message (level 3) prefixed with device information.
833 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
834 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
850 /// Prints a warning-level message (level 4) prefixed with device information.
859 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
860 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
876 /// Prints a notice-level message (level 5) prefixed with device information.
885 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
886 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
902 /// Prints an info-level message (level 6) prefixed with device information.
911 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
912 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
928 /// Prints a debug-level message (level 7) prefixed with device information.
937 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
938 /// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html