Skip to contentSkip to conversation

rust: Add Lock::from_raw() and expose Guard::new()

PATCH Applied Lyude Paul 5 participants 8 messages Nov 19, 2024 – Dec 24, 2024

Subsystems (3)
lore
Share & tools
lore

Lyude Paul

author reviewer
#0 lore raw

v4 cover rust: Add Lock::from_raw() and expose Guard::new()

This is the third version of a small patch series to introduce interfaces for working with locks that we've acquired from raw C pointers, something that is quite useful for bindings like the rust bindings - where there's a number of interfaces protected by BFLs, or which require the implementation of callbacks that are known to occur under lock.

Lyude Paul (2):
rust: sync: Add Lock::from_raw() for Lock<(), B>
rust: sync: Make Guard::new() public

 rust/kernel/sync/lock.rs | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

base-commit: b2603f8ac8217bc59f5c7f248ac248423b9b99cb

Signature · 1 line
2.47.0
author reviewer
#1 lore raw

PATCH v4 1/2 rust: sync: Add Lock::from_raw() for Lock<(), B>

The KMS bindings ( https://patchwork.freedesktop.org/series/131522/ ) 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 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.

---

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
V4:
* Documentation fixes from Boqun
* Reword commit message (Boqun)

---
 rust/kernel/sync/lock.rs | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
rust/kernel/sync/lock.rs +23 -0
index 6d3c8874eb26a..ea65f84b76f8e 100644
@@ -91,6 +91,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.
@@ -129,6 +130,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> {
Signature · 1 line
2.47.0
maintainer Reviewed-by on v4 1/2
#2 lore raw

Re: [PATCH v4 1/2] rust: sync: Add Lock::from_raw() for Lock<(), B>

Quoted 17 lines · Lyude Paul

The KMS bindings ( https://patchwork.freedesktop.org/series/131522/ ) 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 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.

Quoted 1 line
Reviewed-by on v4 1/2
#3 lore raw

RE: [PATCH v4 1/2] rust: sync: Add Lock::from_raw() for Lock<(), B>

In reply to Lyude Paul
Quoted 17 lines · Lyude Paul

The KMS bindings ( https://patchwork.freedesktop.org/series/131522/ ) 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 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.

Quoted 1 line
merge bot Applied
#4 lore raw

[tip: locking/core] rust: sync: Add Lock::from_raw() for Lock<(), B>

In reply to Lyude Paul
The following commit has been merged into the locking/core branch of tip:

The following commit has been merged into the locking/core branch of tip:

Commit-ID:     15abc88057eeec052aefde897df277eca2340ac6
Gitweb:        https://git.kernel.org/tip/15abc88057eeec052aefde897df277eca2340ac6
Author:        Lyude Paul <[email protected]>
AuthorDate:    Tue, 19 Nov 2024 18:11:03 -05:00
Committer:     Boqun Feng <[email protected]>
CommitterDate: Thu, 19 Dec 2024 14:04:42 -08:00

rust: sync: Add Lock::from_raw() for Lock<(), B>

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]

---
 rust/kernel/sync/lock.rs | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
rust/kernel/sync/lock.rs +23 -0
index 41dcdda..57dc2e9 100644
@@ -96,6 +96,7 @@ pub unsafe trait Backend {
 ///
 /// 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 @@ impl<T, B: Backend> Lock<T, B> {
     }
 }
 
+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> {
author reviewer
#5 lore raw

PATCH v4 2/2 rust: sync: Make Guard::new() public

In reply to Lyude Paul

Since we added a Lock::from_raw() function previously, it makes sense to also introduce an interface for creating a Guard from a reference to a Lock for instances where we've derived the Lock from a raw pointer and know that the lock is already acquired, something we do in the KMS API.

---
 rust/kernel/sync/lock.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
rust/kernel/sync/lock.rs +1 -1
index ea65f84b76f8e..139f17f2ec86b 100644
@@ -229,7 +229,7 @@ impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// # Safety
     ///
     /// The caller must ensure that it owns the lock.
-    pub(crate) unsafe fn new(lock: &'a Lock<T, B>, state: B::GuardState) -> Self {
+    pub unsafe fn new(lock: &'a Lock<T, B>, state: B::GuardState) -> Self {
         Self {
             lock,
             state,
Signature · 1 line
2.47.0
merge bot Applied
#6 lore raw

[tip: locking/core] rust: sync: Make Guard::new() public

The following commit has been merged into the locking/core branch of tip:

The following commit has been merged into the locking/core branch of tip:

Commit-ID:     daa03fe50ec376aeadd63a264c471c56af194e83
Gitweb:        https://git.kernel.org/tip/daa03fe50ec376aeadd63a264c471c56af194e83
Author:        Lyude Paul <[email protected]>
AuthorDate:    Tue, 19 Nov 2024 18:11:04 -05:00
Committer:     Boqun Feng <[email protected]>
CommitterDate: Thu, 19 Dec 2024 14:04:42 -08:00

rust: sync: Make Guard::new() public

Since we added a Lock::from_raw() function previously, it makes sense to also introduce an interface for creating a Guard from a reference to a Lock for instances where we've derived the Lock from a raw pointer and know that the lock is already acquired, there are such usages in KMS API.

[Boqun: Add backquotes to type names, reformat the commit log, reword a
bit on the usage of KMS API]

---
 rust/kernel/sync/lock.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
rust/kernel/sync/lock.rs +1 -1
index 57dc2e9..72dbf3f 100644
@@ -234,7 +234,7 @@ impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// # Safety
     ///
     /// The caller must ensure that it owns the lock.
-    pub(crate) unsafe fn new(lock: &'a Lock<T, B>, state: B::GuardState) -> Self {
+    pub unsafe fn new(lock: &'a Lock<T, B>, state: B::GuardState) -> Self {
         Self {
             lock,
             state,
#7 lore raw
In reply to Lyude Paul
Quoted 7 lines · Lyude Paul

This is the third version of a small patch series to introduce interfaces for working with locks that we've acquired from raw C pointers, something that is quite useful for bindings like the rust bindings - where there's a number of interfaces protected by BFLs, or which require the implementation of callbacks that are known to occur under lock.

Queued for future tests and reviews, thanks!

Regards,
Boqun

Quoted 12 lines

Lyude Paul (2):
rust: sync: Add Lock::from_raw() for Lock<(), B>
rust: sync: Make Guard::new() public

 rust/kernel/sync/lock.rs | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

base-commit: b2603f8ac8217bc59f5c7f248ac248423b9b99cb

Signature · 1 line
2.47.0