[PATCH] rust: types: improve `ForeignOwnable` documentation

[PATCH] rust: types: improve `ForeignOwnable` documentation

[Benno Lossin]

There are no guarantees for the pointer returned by `into_foreign`.
This is simply because there is no safety documentation stating any
guarantees. Therefore dereferencing and all other operations for that
pointer are not allowed in a general context (i.e. when the concrete
type implementing the trait is not known).
This might be confusing, therefore add normal documentation to state
that there are no guarantees given for the pointer.

Signed-off-by: Benno Lossin <benno.lossin@proton.me>
---
 rust/kernel/types.rs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index bd189d646adb..0306ec4010a7 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -26,7 +26,10 @@ pub trait ForeignOwnable: Sized {
 
     /// Converts a Rust-owned object to a foreign-owned one.
     ///
-    /// The foreign representation is a pointer to void.
+    /// The foreign representation is a pointer to void. There are no guarantees for this pointer.
+    /// For example, it might be invalid, dangling or pointing to uninitialized memory. Using it in
+    /// any way except for [`ForeignOwnable::from_foreign`], [`ForeignOwnable::borrow`],
+    /// [`ForeignOwnable::try_from_foreign`] can result in undefined behavior.
     fn into_foreign(self) -> *const core::ffi::c_void;
 
     /// Borrows a foreign-owned object.
-- 
2.44.0

Re: [PATCH] rust: types: improve `ForeignOwnable` documentation

[Alice Ryhl]

On Tue, Jul 30, 2024 at 8:23 PM Benno Lossin <benno.lossin@proton.me> wrote:
>
> There are no guarantees for the pointer returned by `into_foreign`.
> This is simply because there is no safety documentation stating any
> guarantees. Therefore dereferencing and all other operations for that
> pointer are not allowed in a general context (i.e. when the concrete
> type implementing the trait is not known).
> This might be confusing, therefore add normal documentation to state
> that there are no guarantees given for the pointer.
>
> Signed-off-by: Benno Lossin <benno.lossin@proton.me>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH] rust: types: improve `ForeignOwnable` documentation

[Miguel Ojeda]

On Tue, Jul 30, 2024 at 8:23 PM Benno Lossin <benno.lossin@proton.me> wrote:
>
> There are no guarantees for the pointer returned by `into_foreign`.
> This is simply because there is no safety documentation stating any
> guarantees. Therefore dereferencing and all other operations for that
> pointer are not allowed in a general context (i.e. when the concrete
> type implementing the trait is not known).
> This might be confusing, therefore add normal documentation to state
> that there are no guarantees given for the pointer.
>
> Signed-off-by: Benno Lossin <benno.lossin@proton.me>

Applied to `rust-next` -- thanks everyone!

Cheers,
Miguel