Skip to contentSkip to conversation

rust: add safety comment in workqueue traits

PATCH Superseded Konstantin Andrikopoulos 3 participants 4 messages Nov 27, 2024 Rust

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 rust: add safety comment in workqueue traits

Add missing safety comments for the implementation of the unsafe traits WorkItemPointer and RawWorkItem for Arc<T> in workqueue.rs

---
 rust/kernel/workqueue.rs | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)
rust/kernel/workqueue.rs +16 -2
index 4d1d2062f6eb..fd3e97192ed8 100644
@@ -519,7 +519,15 @@ unsafe fn raw_get_work(ptr: *mut Self) -> *mut $crate::workqueue::Work<$work_typ
     impl{T} HasWork<Self> for ClosureWork<T> { self.work }
 }
 
-// SAFETY: TODO.
+// SAFETY: The `__enqueue` implementation in RawWorkItem uses a `work_struct` initialized with the
+// `run` method of this trait as the function pointer because:
+//   - `__enqueue` gets the `work_struct` from the `Work` field, using `T::raw_get_work`.
+//   - The only safe way to create a `Work` object is through `Work::new`.
+//   - `Work::new` makes sure that `T::Pointer::run` is passed to `init_work_with_key`.
+//   - Finally `Work` and `RawWorkItem` guarantee that the correct `Work` field
+//     will be used because of the ID const generic bound. This makes sure that `T::raw_get_work`
+//     uses the correct offset for the `Work` field, and `Work::new` picks the correct
+//     implementation of `WorkItemPointer` for `Arc<T>`.
 unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Arc<T>
 where
     T: WorkItem<ID, Pointer = Self>,
@@ -537,7 +545,13 @@ unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Arc<T>
     }
 }
 
-// SAFETY: TODO.
+// SAFETY: The `work_struct` raw pointer is guaranteed to be valid for the duration of the call to
+// the closure because we get it from an `Arc`, which means that the ref count will be at least 1,
+// and we don't drop the `Arc` ourselves. If `queue_work_on` returns true, it is further guaranteed
+// to be valid until a call to the function pointer in `work_struct` because we leak the memory it
+// points to, and only reclaim it if the closure returns false, or in `WorkItemPointer::run`, which
+// is what the function pointer in the `work_struct` must be pointing to, according to the safety
+// requirements of `WorkItemPointer`.
 unsafe impl<T, const ID: u64> RawWorkItem<ID> for Arc<T>
 where
     T: WorkItem<ID, Pointer = Self>,
Signature · 1 line
2.47.1
#1 lore raw
Quoted 4 lines · Konstantin Andrikopoulos

Add missing safety comments for the implementation of the unsafe traits WorkItemPointer and RawWorkItem for Arc<T> in workqueue.rs

The link tag should be grouped with other tags.

Quoted 5 lines

See [1] for example, the ordering of tags do matter. Your signed tag should be the last.

[1]: https://docs.kernel.org/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by

Quoted 30 lines
---
  rust/kernel/workqueue.rs | 18 ++++++++++++++++--
  1 file changed, 16 insertions(+), 2 deletions(-)
rust/kernel/workqueue.rs +9 -2
index 4d1d2062f6eb..fd3e97192ed8 100644
@@ -519,7 +519,15 @@ unsafe fn raw_get_work(ptr: *mut Self) -> *mut $crate::workqueue::Work<$work_typ
      impl{T} HasWork<Self> for ClosureWork<T> { self.work }
  }
 
-// SAFETY: TODO.
+// SAFETY: The `__enqueue` implementation in RawWorkItem uses a `work_struct` initialized with the
+// `run` method of this trait as the function pointer because:
+//   - `__enqueue` gets the `work_struct` from the `Work` field, using `T::raw_get_work`.
+//   - The only safe way to create a `Work` object is through `Work::new`.
+//   - `Work::new` makes sure that `T::Pointer::run` is passed to `init_work_with_key`.
+//   - Finally `Work` and `RawWorkItem` guarantee that the correct `Work` field
+//     will be used because of the ID const generic bound. This makes sure that `T::raw_get_work`
+//     uses the correct offset for the `Work` field, and `Work::new` picks the correct
+//     implementation of `WorkItemPointer` for `Arc<T>`.
  unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Arc<T>
  where
      T: WorkItem<ID, Pointer = Self>,
@@ -537,7 +545,13 @@ unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Arc<T>
      }
  }
 
-// SAFETY: TODO.

rust/kernel/workqueue.rs unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Arc<T> · line 557

Quoted 10 lines
rust/kernel/workqueue.rs +7 -0
+// SAFETY: The `work_struct` raw pointer is guaranteed to be valid for the duration of the call to
+// the closure because we get it from an `Arc`, which means that the ref count will be at least 1,
+// and we don't drop the `Arc` ourselves. If `queue_work_on` returns true, it is further guaranteed
+// to be valid until a call to the function pointer in `work_struct` because we leak the memory it
+// points to, and only reclaim it if the closure returns false, or in `WorkItemPointer::run`, which
+// is what the function pointer in the `work_struct` must be pointing to, according to the safety
+// requirements of `WorkItemPointer`.
  unsafe impl<T, const ID: u64> RawWorkItem<ID> for Arc<T>
  where
      T: WorkItem<ID, Pointer = Self>,

Thanks, for working on this!

Daniel

reviewer
#2 lore raw
Quoted 14 lines · Daniel Sedlak
Quoted 4 lines · Konstantin Andrikopoulos

Add missing safety comments for the implementation of the unsafe traits WorkItemPointer and RawWorkItem for Arc<T> in workqueue.rs

The link tag should be grouped with other tags.

Quoted 5 lines
Quoted 5 lines

See [1] for example, the ordering of tags do matter. Your signed tag should be the last.

[1]:
https://docs.kernel.org/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by

It should also cc Tejun who is listed as the maintainer of WORKQUEUE in the MAINTAINERS file.

Alice

reviewer Reviewed-by on v1 1/1
#3 lore raw
In reply to Konstantin Andrikopoulos
Quoted 10 lines · Konstantin Andrikopoulos

Add missing safety comments for the implementation of the unsafe traits WorkItemPointer and RawWorkItem for Arc<T> in workqueue.rs

Other than the tag ordering issue, this looks good to me.