From 4ead6c37b04aa35943ea270f09db18ebb38e63ff Mon Sep 17 00:00:00 2001 From: Danilo Krummrich Date: Wed, 19 Jun 2024 15:39:17 +0200 Subject: [PATCH] device: rust: improve safety comments Improve the wording of safety comments to be more explicit about what exactly is guaranteed to be valid. Suggested-by: Benno Lossin Signed-off-by: Danilo Krummrich Link: https://lore.kernel.org/r/20240619133949.64638-1-dakr@redhat.com Signed-off-by: Greg Kroah-Hartman --- rust/kernel/device.rs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs index e445e87fb7d7..851018eef885 100644 --- a/rust/kernel/device.rs +++ b/rust/kernel/device.rs @@ -30,8 +30,10 @@ /// /// # Invariants /// -/// The pointer stored in `Self` is non-null and valid for the lifetime of the `ARef` instance. In -/// particular, the `ARef` instance owns an increment on the underlying object’s reference count. +/// A `Device` instance represents a valid `struct device` created by the C portion of the kernel. +/// +/// Instances of this type are always reference-counted, that is, a call to `get_device` ensures +/// that the allocation remains valid at least until the matching call to `put_device`. /// /// `bindings::device::release` is valid to be called from any thread, hence `ARef` can be /// dropped from any thread. @@ -58,7 +60,8 @@ pub unsafe fn from_raw(ptr: *mut bindings::device) -> ARef { // CAST: `Self` is a `repr(transparent)` wrapper around `bindings::device`. let ptr = ptr.cast::(); - // SAFETY: By the safety requirements, ptr is valid. + // SAFETY: `ptr` is valid by the safety requirements of this function. By the above call to + // `bindings::get_device` we also own a reference to the underlying `struct device`. unsafe { ARef::from_raw(ptr::NonNull::new_unchecked(ptr)) } }