summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBenno Lossin <benno.lossin@proton.me>2024-07-30 18:23:04 +0000
committerMiguel Ojeda <ojeda@kernel.org>2024-08-18 23:10:53 +0200
commit7adcdd572248591c3932e27d98b4a086662d5cbe (patch)
tree10d251f98c7c4514729bcb0e796c6addcafee712
parent6c2d0ad53b8ff25cb1a12570191576d834e9108d (diff)
rust: types: improve `ForeignOwnable` documentation
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> Link: https://lore.kernel.org/r/20240730182251.1466684-1-benno.lossin@proton.me Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
-rw-r--r--rust/kernel/types.rs5
1 files changed, 4 insertions, 1 deletions
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index 132ca1113083..ee7dd1f963ef 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -27,7 +27,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.