[PATCH] rust: revocable: clarify invariants in safety documentation

[Marcelo Moreira <marcelomoreira1905@gmail.com>]

Clarify the safety invariants for `Revocable<T>`, documenting that `data`
is only valid if `is_available` is `true`, and that access requires
holding the RCU read-side lock.

This helps developers understand when it is safe to access the wrapped
data and the role of RCU in ensuring memory safety.

This is part of issue #1160 ("correct safety comments and documentation
in revocable.rs"), reported by Miguel Ojeda and Benno Lossin.

Reported-by: Miguel Ojeda <ojeda@kernel.org>
Closes: https://github.com/Rust-for-Linux/linux/issues/1160
Reported-by: Benno Lossin <benno.lossin@proton.me>
Closes: https://github.com/Rust-for-Linux/linux/issues/1160
Tested-by: Marcelo Moreira <marcelomoreira1905@gmail.com>
Signed-off-by: Marcelo Moreira <marcelomoreira1905@gmail.com>
---
 rust/kernel/revocable.rs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/rust/kernel/revocable.rs b/rust/kernel/revocable.rs
index 1e5a9d25c21b..2da3e9460c07 100644
--- a/rust/kernel/revocable.rs
+++ b/rust/kernel/revocable.rs
@@ -61,6 +61,15 @@
 /// v.revoke();
 /// assert_eq!(add_two(&v), None);
 /// ```
+///
+/// # Invariants
+///
+/// - The wrapped object `data` is valid if and only if `is_available` is `true`.
+/// - Access to `data` must occur only while holding the RCU read-side lock (e.g., via
+///   [`Revocable::try_access`] or [`Revocable::try_access_with_guard`]).
+/// - Once `is_available` is set to `false`, further access to `data` is disallowed,
+///   and the object is dropped either after an RCU grace period (in [`revoke`]),
+///   or immediately (in [`revoke_nosync`]).
 #[pin_data(PinnedDrop)]
 pub struct Revocable<T> {
     is_available: AtomicBool,
-- 
2.49.0