Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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 <benno.lossin@proton.me>
Signed-off-by: Danilo Krummrich <dakr@redhat.com>
Link: https://lore.kernel.org/r/20240619133949.64638-1-dakr@redhat.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
Danilo Krummrich
and committed by
Greg Kroah-Hartman
4ead6c37
892fb846
+6
-3
+6
-3
rust/kernel/device.rs
+6
-3
rust/kernel/device.rs
···
30
30
///
31
31
/// # Invariants
32
32
///
33
-
/// The pointer stored in `Self` is non-null and valid for the lifetime of the `ARef` instance. In
34
-
/// particular, the `ARef` instance owns an increment on the underlying object’s reference count.
33
+
/// A `Device` instance represents a valid `struct device` created by the C portion of the kernel.
34
+
///
35
+
/// Instances of this type are always reference-counted, that is, a call to `get_device` ensures
36
+
/// that the allocation remains valid at least until the matching call to `put_device`.
35
37
///
36
38
/// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be
37
39
/// dropped from any thread.
···
60
58
// CAST: `Self` is a `repr(transparent)` wrapper around `bindings::device`.
61
59
let ptr = ptr.cast::<Self>();
62
60
63
-
// SAFETY: By the safety requirements, ptr is valid.
61
+
// SAFETY: `ptr` is valid by the safety requirements of this function. By the above call to
62
+
// `bindings::get_device` we also own a reference to the underlying `struct device`.
64
63
unsafe { ARef::from_raw(ptr::NonNull::new_unchecked(ptr)) }
65
64
}
66
65