A few of the APIs I've been writing bindings for (KMS in particular) rely
on the user manually acquiring specific locks before calling certain
functions. At the moment though, the only way of acquiring these locks in
bindings is to simply call the C locking functions directly - since said
locks are not acquired on the rust side of things.

However - if we add `#[repr(C)]` to `Lock<(), B>`, then given `()` is a ZST
- `Lock<(), B>` becomes equivalent in data layout to its inner `B::State`
type. Since locks in C don't have data explicitly associated with them
anyway, we can take advantage of this to add a `Lock::from_raw()` function
that can translate a raw pointer to `B::State` into its proper `Lock<(),
B>` equivalent. This lets us simply acquire a reference to the lock in
question and work with it like it was initialized on the rust side of
things, allowing us to use less unsafe code to implement bindings with lock
requirements.

Signed-off-by: Lyude Paul <lyude@redhat.com>

---

V2:
* Don't implement this for all ZST types, just implement it for ()
V3:
* Get rid of some unused imports
* Make sure that we run rustfmt

Signed-off-by: Lyude Paul <lyude@redhat.com>
---
 rust/kernel/sync/lock.rs | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index 90cc5416529bd..c7b0c6351f793 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -88,6 +88,7 @@ unsafe fn relock(ptr: *mut Self::State, guard_state: &mut Self::GuardState) {
 ///
 /// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock
 /// [`Backend`] specified as the generic parameter `B`.
+#[repr(C)]
 #[pin_data]
 pub struct Lock<T: ?Sized, B: Backend> {
     /// The kernel lock object.
@@ -126,6 +127,27 @@ pub fn new(t: T, name: &'static CStr, key: &'static LockClassKey) -> impl PinIni
     }
 }
 
+impl<B: Backend> Lock<(), B> {
+    /// Constructs a [`Lock`] from a raw pointer.
+    ///
+    /// This can be useful for interacting with a lock which was initialised outside of rust.
+    ///
+    /// # Safety
+    ///
+    /// The caller promises that `ptr` points to a valid initialised instance of [`State`].
+    ///
+    /// [`State`]: Backend::State
+    pub unsafe fn from_raw<'a>(ptr: *mut B::State) -> &'a Self {
+        // SAFETY:
+        // * By the safety contract `ptr` must point to a valid initialised instance of `B::State`
+        // * Since the lock data type is `()` which is a ZST, `state` is the only non-ZST member of
+        //   the struct
+        // * Combined with `#[repr(C)]`, this guarantees `Self` has an equivalent data layout to
+        //   `B::State`.
+        unsafe { &*ptr.cast() }
+    }
+}
+
 impl<T: ?Sized, B: Backend> Lock<T, B> {
     /// Acquires the lock and gives the caller access to the data protected by it.
     pub fn lock(&self) -> Guard<'_, T, B> {
-- 
2.47.0

Hi Lyude,

On Thu, Oct 31, 2024 at 07:08:44PM -0400, Lyude Paul wrote:
> A few of the APIs I've been writing bindings for (KMS in particular) rely
> on the user manually acquiring specific locks before calling certain
> functions. At the moment though, the only way of acquiring these locks in

Could you reword this in a more abstract/object way, like: KMS (probably
a link to you RFC patchset) has a few bindings that require manually
acquire specific locks before calling certain functions.

> bindings is to simply call the C locking functions directly - since said
> locks are not acquired on the rust side of things.
> 
> However - if we add `#[repr(C)]` to `Lock<(), B>`, then given `()` is a ZST
> - `Lock<(), B>` becomes equivalent in data layout to its inner `B::State`
> type. Since locks in C don't have data explicitly associated with them
> anyway, we can take advantage of this to add a `Lock::from_raw()` function
> that can translate a raw pointer to `B::State` into its proper `Lock<(),
> B>` equivalent. This lets us simply acquire a reference to the lock in
> question and work with it like it was initialized on the rust side of
> things, allowing us to use less unsafe code to implement bindings with lock
> requirements.
> 
> Signed-off-by: Lyude Paul <lyude@redhat.com>
> 
> ---
> 
> V2:
> * Don't implement this for all ZST types, just implement it for ()
> V3:
> * Get rid of some unused imports
> * Make sure that we run rustfmt
> 
> Signed-off-by: Lyude Paul <lyude@redhat.com>
> ---
>  rust/kernel/sync/lock.rs | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
> 
> diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> index 90cc5416529bd..c7b0c6351f793 100644
> --- a/rust/kernel/sync/lock.rs
> +++ b/rust/kernel/sync/lock.rs
> @@ -88,6 +88,7 @@ unsafe fn relock(ptr: *mut Self::State, guard_state: &mut Self::GuardState) {
>  ///
>  /// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock
>  /// [`Backend`] specified as the generic parameter `B`.
> +#[repr(C)]
>  #[pin_data]
>  pub struct Lock<T: ?Sized, B: Backend> {
>      /// The kernel lock object.
> @@ -126,6 +127,27 @@ pub fn new(t: T, name: &'static CStr, key: &'static LockClassKey) -> impl PinIni
>      }
>  }
>  
> +impl<B: Backend> Lock<(), B> {
> +    /// Constructs a [`Lock`] from a raw pointer.
> +    ///
> +    /// This can be useful for interacting with a lock which was initialised outside of rust.

s/rust/Rust

> +    ///
> +    /// # Safety
> +    ///
> +    /// The caller promises that `ptr` points to a valid initialised instance of [`State`].

Please add "during the whole lifetime of `'a`" or something similar.

> +    ///
> +    /// [`State`]: Backend::State
> +    pub unsafe fn from_raw<'a>(ptr: *mut B::State) -> &'a Self {
> +        // SAFETY:
> +        // * By the safety contract `ptr` must point to a valid initialised instance of `B::State`
> +        // * Since the lock data type is `()` which is a ZST, `state` is the only non-ZST member of
> +        //   the struct
> +        // * Combined with `#[repr(C)]`, this guarantees `Self` has an equivalent data layout to
> +        //   `B::State`.

Please use '-' instead of '*' for listing to stay consistent with other
part of the file.

Regards,
Boqun

> +        unsafe { &*ptr.cast() }
> +    }
> +}
> +
>  impl<T: ?Sized, B: Backend> Lock<T, B> {
>      /// Acquires the lock and gives the caller access to the data protected by it.
>      pub fn lock(&self) -> Guard<'_, T, B> {
> -- 
> 2.47.0
>