rust: revocable: document why &T is not used in RevocableGuard

When a reference appears in a function argument, the reference is
assumed to be valid for the entire duration of that function call; this
is called a stack protector [1]. Because of that, custom pointer types
whose destructor may invalidate the pointee (i.e. they are more similar
to Box<T> than &T) cannot internally use a reference, and must instead
use a raw pointer.

This issue is something that is often missed during unsafe review. For
examples, see [2] and [3]. To ensure that people don't try to simplify
RevocableGuard by changing the raw pointer to a reference, add a comment
to that effect.

Link: https://perso.crans.org/vanille/treebor/protectors.html [1]
Link: https://users.rust-lang.org/t/unsafe-code-review-semi-owning-weak-rwlock-t-guard/95706 [2]
Link: https://lore.kernel.org/all/[email protected]/ [3]
Signed-off-by: Alice Ryhl <[email protected]>
Reviewed-by: Benno Lossin <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
[ Adjusted title. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>

Author: Darksonn

rust/kernel/revocable.rs

@@ -231,6 +231,10 @@ impl<T> PinnedDrop for Revocable<T> {
 ///
 /// The RCU read-side lock is held while the guard is alive.
 pub struct RevocableGuard<'a, T> {
+    // This can't use the `&'a T` type because references that appear in function arguments must
+    // not become dangling during the execution of the function, which can happen if the
+    // `RevocableGuard` is passed as a function argument and then dropped during execution of the
+    // function.
     data_ref: *const T,
     _rcu_guard: rcu::Guard,
     _p: PhantomData<&'a ()>,