On Tue Jun 10, 2025 at 1:30 PM CEST, Andreas Hindborg wrote:
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index 22985b6f6982..0ccef6b5a20a 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -21,15 +21,11 @@
> ///
> /// # Safety
> ///
> -/// Implementers must ensure that [`into_foreign`] returns a pointer which meets the alignment
> -/// requirements of [`PointedTo`].
> -///
> -/// [`into_foreign`]: Self::into_foreign
> -/// [`PointedTo`]: Self::PointedTo
> +/// Implementers must ensure that [`Self::into_foreign`] returns pointers aligned to
> +/// [`Self::FOREIGN_ALIGN`].
> pub unsafe trait ForeignOwnable: Sized {
> - /// Type used when the value is foreign-owned. In practical terms only defines the alignment of
> - /// the pointer.
> - type PointedTo;
> + /// The alignment of pointers returned by `into_foreign`.
> + const FOREIGN_ALIGN: usize;
>
> /// Type used to immutably borrow a value that is currently foreign-owned.
> type Borrowed<'a>;
> @@ -39,18 +35,20 @@ pub unsafe trait ForeignOwnable: Sized {
>
> /// Converts a Rust-owned object to a foreign-owned one.
> ///
> + /// The foreign representation is a pointer to void. Aside from the guarantees listed below,
I feel like this reads better:
s/guarantees/ones/
> + /// there are no other guarantees for this pointer. For example, it might be invalid, dangling
We should also mention that it could be null. (or is that assumption
wrong?)
---
Cheers,
Benno
> + /// or pointing to uninitialized memory. Using it in any way except for [`from_foreign`],
> + /// [`try_from_foreign`], [`borrow`], or [`borrow_mut`] can result in undefined behavior.
> + ///
> /// # Guarantees
> ///
> - /// The return value is guaranteed to be well-aligned, but there are no other guarantees for
> - /// this pointer. For example, it might be null, dangling, or point to uninitialized memory.
> - /// Using it in any way except for [`ForeignOwnable::from_foreign`], [`ForeignOwnable::borrow`],
> - /// [`ForeignOwnable::try_from_foreign`] can result in undefined behavior.
> + /// - Minimum alignment of returned pointer is [`Self::FOREIGN_ALIGN`].
> ///
> /// [`from_foreign`]: Self::from_foreign
> /// [`try_from_foreign`]: Self::try_from_foreign
> /// [`borrow`]: Self::borrow
> /// [`borrow_mut`]: Self::borrow_mut
> - fn into_foreign(self) -> *mut Self::PointedTo;
> + fn into_foreign(self) -> *mut crate::ffi::c_void;
>
> /// Converts a foreign-owned object back to a Rust-owned one.
> ///
