[PATCH] rust: workqueue: document SAFETY for `RawWorkItem` impl on `Pin<KBox<T>>`

[PATCH] rust: workqueue: document SAFETY for `RawWorkItem` impl on `Pin<KBox<T>>`

[Sagar Taunk]

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

The `work_struct` raw pointer is valid for the duration of the closure
call because it comes from a `KBox<T>` allocation that is not dropped by
`__enqueue` itself. Since `Pin<KBox<T>>` requires exclusive ownership, the
work item cannot already be queued, so `queue_work_on` always returns true
and the pointer remains valid until `WorkItemPointer::run` is called, where
it is reclaimed via `KBox::from_raw`.

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

diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index 676ade0539e3..7554601cb968 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -910,7 +910,14 @@ unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Pin<KBox<T>>
     }
 }
 
-// SAFETY: TODO.
+// SAFETY: The `work_struct` raw pointer is guaranteed to be valid for the duration of the call to
+// the closure because it comes from a `KBox<T>` which guarantees a valid heap allocation,
+// and we don't drop the allocation ourselves. 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.
+// Since `Pin<KBox<T>>` requires exclusive ownership, the work item cannot already be queued,
+// so `queue_work_on` always returns true, and we only reclaim the pointer 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 Pin<KBox<T>>
 where
     T: WorkItem<ID, Pointer = Self>,
-- 
2.54.0