The original implementation left a `SAFETY: TODO` comment on the
`WorkItemPointer` implementation for `Pin<KBox<T>>`. This patch documents
the safety requirements that make this implementation sound.

The safety argument follows the same structure as the `Arc<T>`
implementation and relies on three guarantees:
 `__enqueue` strips the `Pin` wrapper via `Pin::into_inner_unchecked`
and leaks the box via `KBox::into_raw`, producing `*mut T` whose
allocation remains live for the duration of the queued work;
`work_container_of` safely reverses the `raw_get_work` offset arithmetic to
recover the exact `*mut T` that `__enqueue` produced; and the workqueue
guarantees `run` is called exactly once, making `KBox::from_raw` sound.

Signed-off-by: Sagar Taunk <sagartaunk2@gmail.com>
---
 rust/kernel/workqueue.rs | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index 74c59f2b1c09..676ade0539e3 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -881,7 +881,15 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for Arc<T>
 {
 }
 
-// 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<T, ID>` field embedded in `T`,
+//     using `T::raw_get_work` on the pointer obtained from `KBox::into_raw`.
+//   - 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 the correct `Work` field is used
+//     because of the `ID` const generic bound, and `Work::new` picks the correct
+//     implementation of `WorkItemPointer` for `Pin<KBox<T>>`.
 unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Pin<KBox<T>>
 where
     T: WorkItem<ID, Pointer = Self>,
-- 
2.54.0

On Thu, Apr 30, 2026 at 12:49:28PM +0530, Sagar Taunk wrote:
> The original implementation left a `SAFETY: TODO` comment on the
> `WorkItemPointer` implementation for `Pin<KBox<T>>`. This patch documents
> the safety requirements that make this implementation sound.
> 
> The safety argument follows the same structure as the `Arc<T>`
> implementation and relies on three guarantees:
>  `__enqueue` strips the `Pin` wrapper via `Pin::into_inner_unchecked`
> and leaks the box via `KBox::into_raw`, producing `*mut T` whose
> allocation remains live for the duration of the queued work;
> `work_container_of` safely reverses the `raw_get_work` offset arithmetic to
> recover the exact `*mut T` that `__enqueue` produced; and the workqueue
> guarantees `run` is called exactly once, making `KBox::from_raw` sound.
> 
> Signed-off-by: Sagar Taunk <sagartaunk2@gmail.com>

Thanks

Reviewed-by: Alice Ryhl <aliceryhl@google.com>