[RFC 2/5] rust: sync: Add Lock::from_raw() for Lock<(), B>

[Boqun Feng <boqun.feng@gmail.com>]

From: Lyude Paul <lyude@redhat.com>

The KMS bindings [1] have a few bindings that require 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 initialized 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.

[Boqun: Use "Link:" instead of a URL and format the commit log]

Signed-off-by: Lyude Paul <lyude@redhat.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://patchwork.freedesktop.org/series/131522/ [1]
Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
Link: https://lore.kernel.org/r/20241119231146.2298971-2-lyude@redhat.com
---
 rust/kernel/sync/lock.rs | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index 41dcddac69e2..57dc2e90e504 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -96,6 +96,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.
@@ -134,6 +135,28 @@ 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`] during
+    /// the whole lifetime of `'a`.
+    ///
+    /// [`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.39.5 (Apple Git-154)