Re: [PATCH v2] rust: types: extend `Opaque` documentation

[Benno Lossin <benno.lossin@proton.me>]

On 02.10.24 07:03, Dirk Behme wrote:
> Update the `Opaque` documentation and add an example as proposed by
> Miguel Ojeda in [1]. The documentation update is mainly taken from
> Benno Lossin's description [2].
> 
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> Cc: Benno Lossin <benno.lossin@proton.me>
> Cc: Nell Shamrell-Harrington <nells@linux.microsoft.com>
> Link :https://rust-for-linux.zulipchat.com/#narrow/stream/291565-Help/topic/What.20to.20work.20on.20next.3F/near/467478085 [1]
> Link: https://rust-for-linux.zulipchat.com/#narrow/stream/291565-Help/topic/What.20to.20work.20on.20next.3F/near/470498289 [2]
> Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
> ---
> 
> Changes in v2: Correct typos and formatting. Drop non-camel-case.
>                Add SAFETY comment.
> 
>  rust/kernel/types.rs | 45 +++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 44 insertions(+), 1 deletion(-)
> 
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index 10e3b1a999f4c..5e96f2c46f9fd 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -290,7 +290,50 @@ fn drop(&mut self) {
> 
>  /// Stores an opaque value.
>  ///
> -/// This is meant to be used with FFI objects that are never interpreted by Rust code.
> +/// `Opaque<T>` is meant to be used with FFI objects that are never interpreted by Rust code.
> +///
> +/// It is used to wrap structs from the C side, like for example `Opaque<bindings::mutex>`.
> +/// It gets rid of all the usual assumptions that Rust has for a value:
> +///
> +/// * The value is allowed to be uninitialized (for example have invalid bit patterns: `3` for a `bool`).
> +/// * The value is allowed to be mutated, when a `&Opaque<T>` exists on the Rust side.
> +/// * No uniqueness for mutable references: it is fine to have multiple &mut `Opaque<T>` point to the same value.

The "`" should be in front of the "&mut".

> +/// * The value is not allowed to be shared with other threads (i.e. it is `!Sync`).
> +///
> +/// This has to be used for all values that the C side has access to, because it can't be ensured
> +/// that the C side is adhering to the usual constraints that Rust needs.
> +///
> +/// Using `Opaque<T>` allows to continue to use references on the Rust side even for values shared with C.

Miguel already mentioned this: could you add my Co-developed-by, since
most of this stuff is from me. Thanks!

---
Cheers,
Benno