* [PATCH v4 1/5] rust: workqueue: support stack-allocated work items
2026-11-19 14:12 [PATCH v4 0/5] workqueue: OwnedQueue and ScopedWork Alice Ryhl
@ 2026-11-19 14:12 ` Alice Ryhl
2026-11-19 14:37 ` Gary Guo
2026-11-19 14:12 ` [PATCH v4 2/5] rust: workqueue: restrict delayed work to global wqs Alice Ryhl
` (3 subsequent siblings)
4 siblings, 1 reply; 9+ messages in thread
From: Alice Ryhl @ 2026-11-19 14:12 UTC (permalink / raw)
To: Tejun Heo, Lai Jiangshan, Danilo Krummrich
Cc: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Daniel Almeida,
Tamir Duberstein, Alexandre Courbot, Onur Özkan,
John Hubbard, Philipp Stanner, rust-for-linux, linux-kernel,
driver-core, Alice Ryhl
Pass `object_is_on_stack(work)` to `__init_work()` in
`rust_helper_init_work_with_key()` instead of taking an explicit
`onstack` parameter, and call `destroy_work_on_stack()` when `Work` is
dropped. This ensures `CONFIG_DEBUG_OBJECTS_WORK` properly tracks and
cleans up stack-allocated work items without requiring separate
constructors.
Fixes: 7324b88975c5 ("rust: workqueue: add helper for defining work_struct fields")
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
rust/helpers/workqueue.c | 9 +++++++--
rust/kernel/workqueue.rs | 13 ++++++++++---
2 files changed, 17 insertions(+), 5 deletions(-)
diff --git a/rust/helpers/workqueue.c b/rust/helpers/workqueue.c
index ce1c3a5b2150..337382acfbf5 100644
--- a/rust/helpers/workqueue.c
+++ b/rust/helpers/workqueue.c
@@ -1,16 +1,21 @@
// SPDX-License-Identifier: GPL-2.0
+#include <linux/sched/task_stack.h>
#include <linux/workqueue.h>
__rust_helper void rust_helper_init_work_with_key(struct work_struct *work,
work_func_t func,
- bool onstack,
const char *name,
struct lock_class_key *key)
{
- __init_work(work, onstack);
+ __init_work(work, object_is_on_stack(work));
work->data = (atomic_long_t)WORK_DATA_INIT();
lockdep_init_map(&work->lockdep_map, name, key, 0);
INIT_LIST_HEAD(&work->entry);
work->func = func;
}
+
+__rust_helper void rust_helper_destroy_work_on_stack(struct work_struct *work)
+{
+ destroy_work_on_stack(work);
+}
diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index a872f9fffb90..6eb6c40138f2 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -481,7 +481,7 @@ pub trait WorkItem<const ID: u64 = 0> {
/// This is a helper type used to associate a `work_struct` with the [`WorkItem`] that uses it.
///
/// [`run`]: WorkItemPointer::run
-#[pin_data]
+#[pin_data(PinnedDrop)]
#[repr(transparent)]
pub struct Work<T: ?Sized, const ID: u64 = 0> {
#[pin]
@@ -513,7 +513,6 @@ pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit
bindings::init_work_with_key(
slot,
Some(T::Pointer::run),
- false,
name.as_char_ptr(),
key.as_ptr(),
)
@@ -539,6 +538,15 @@ pub unsafe fn raw_get(ptr: *const Self) -> *mut bindings::work_struct {
}
}
+#[pinned_drop]
+impl<T: ?Sized, const ID: u64> PinnedDrop for Work<T, ID> {
+ fn drop(self: Pin<&mut Self>) {
+ // SAFETY: `self.work.get()` points to a valid `work_struct` initialized in `Work::new`,
+ // and the work item is not currently queued because `Self` is being dropped.
+ unsafe { bindings::destroy_work_on_stack(self.work.get()) }
+ }
+}
+
/// Declares that a type contains a [`Work<T, ID>`].
///
/// The intended way of using this trait is via the [`impl_has_work!`] macro. You can use the macro
@@ -686,7 +694,6 @@ pub fn new(
bindings::init_work_with_key(
core::ptr::addr_of_mut!((*slot).work),
Some(T::Pointer::run),
- false,
work_name.as_char_ptr(),
work_key.as_ptr(),
)
--
2.56.1.708.g77570a6a1d-goog
^ permalink raw reply [flat|nested] 9+ messages in thread* Re: [PATCH v4 1/5] rust: workqueue: support stack-allocated work items
2026-11-19 14:12 ` [PATCH v4 1/5] rust: workqueue: support stack-allocated work items Alice Ryhl
@ 2026-11-19 14:37 ` Gary Guo
2026-11-19 15:17 ` Alice Ryhl
0 siblings, 1 reply; 9+ messages in thread
From: Gary Guo @ 2026-11-19 14:37 UTC (permalink / raw)
To: Alice Ryhl, Tejun Heo, Lai Jiangshan, Danilo Krummrich
Cc: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Daniel Almeida,
Tamir Duberstein, Alexandre Courbot, Onur Özkan,
John Hubbard, Philipp Stanner, rust-for-linux, linux-kernel,
driver-core
On Thu Nov 19, 2026 at 2:12 PM GMT, Alice Ryhl wrote:
> Pass `object_is_on_stack(work)` to `__init_work()` in
> `rust_helper_init_work_with_key()` instead of taking an explicit
> `onstack` parameter, and call `destroy_work_on_stack()` when `Work` is
> dropped. This ensures `CONFIG_DEBUG_OBJECTS_WORK` properly tracks and
> cleans up stack-allocated work items without requiring separate
> constructors.
>
> Fixes: 7324b88975c5 ("rust: workqueue: add helper for defining work_struct fields")
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>
> ---
> rust/helpers/workqueue.c | 9 +++++++--
> rust/kernel/workqueue.rs | 13 ++++++++++---
> 2 files changed, 17 insertions(+), 5 deletions(-)
>
> diff --git a/rust/helpers/workqueue.c b/rust/helpers/workqueue.c
> index ce1c3a5b2150..337382acfbf5 100644
> --- a/rust/helpers/workqueue.c
> +++ b/rust/helpers/workqueue.c
> @@ -1,16 +1,21 @@
> // SPDX-License-Identifier: GPL-2.0
>
> +#include <linux/sched/task_stack.h>
> #include <linux/workqueue.h>
>
> __rust_helper void rust_helper_init_work_with_key(struct work_struct *work,
> work_func_t func,
> - bool onstack,
> const char *name,
> struct lock_class_key *key)
> {
> - __init_work(work, onstack);
> + __init_work(work, object_is_on_stack(work));
Is this fully optimized out if !CONFIG_DEBUG_OBJECTS_WORK?
Best,
Gary
> work->data = (atomic_long_t)WORK_DATA_INIT();
> lockdep_init_map(&work->lockdep_map, name, key, 0);
> INIT_LIST_HEAD(&work->entry);
> work->func = func;
> }
> +
> +__rust_helper void rust_helper_destroy_work_on_stack(struct work_struct *work)
> +{
> + destroy_work_on_stack(work);
> +}
> diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
> index a872f9fffb90..6eb6c40138f2 100644
> --- a/rust/kernel/workqueue.rs
> +++ b/rust/kernel/workqueue.rs
> @@ -481,7 +481,7 @@ pub trait WorkItem<const ID: u64 = 0> {
> /// This is a helper type used to associate a `work_struct` with the [`WorkItem`] that uses it.
> ///
> /// [`run`]: WorkItemPointer::run
> -#[pin_data]
> +#[pin_data(PinnedDrop)]
> #[repr(transparent)]
> pub struct Work<T: ?Sized, const ID: u64 = 0> {
> #[pin]
> @@ -513,7 +513,6 @@ pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit
> bindings::init_work_with_key(
> slot,
> Some(T::Pointer::run),
> - false,
> name.as_char_ptr(),
> key.as_ptr(),
> )
> @@ -539,6 +538,15 @@ pub unsafe fn raw_get(ptr: *const Self) -> *mut bindings::work_struct {
> }
> }
>
> +#[pinned_drop]
> +impl<T: ?Sized, const ID: u64> PinnedDrop for Work<T, ID> {
> + fn drop(self: Pin<&mut Self>) {
> + // SAFETY: `self.work.get()` points to a valid `work_struct` initialized in `Work::new`,
> + // and the work item is not currently queued because `Self` is being dropped.
> + unsafe { bindings::destroy_work_on_stack(self.work.get()) }
> + }
> +}
> +
> /// Declares that a type contains a [`Work<T, ID>`].
> ///
> /// The intended way of using this trait is via the [`impl_has_work!`] macro. You can use the macro
> @@ -686,7 +694,6 @@ pub fn new(
> bindings::init_work_with_key(
> core::ptr::addr_of_mut!((*slot).work),
> Some(T::Pointer::run),
> - false,
> work_name.as_char_ptr(),
> work_key.as_ptr(),
> )
^ permalink raw reply [flat|nested] 9+ messages in thread* Re: [PATCH v4 1/5] rust: workqueue: support stack-allocated work items
2026-11-19 14:37 ` Gary Guo
@ 2026-11-19 15:17 ` Alice Ryhl
0 siblings, 0 replies; 9+ messages in thread
From: Alice Ryhl @ 2026-11-19 15:17 UTC (permalink / raw)
To: Gary Guo
Cc: Alice Ryhl, Tejun Heo, Lai Jiangshan, Danilo Krummrich,
Miguel Ojeda, Boqun Feng, Björn Roy Baron, Benno Lossin,
Andreas Hindborg, Trevor Gross, Daniel Almeida, Tamir Duberstein,
Alexandre Courbot, Onur Özkan, John Hubbard,
Philipp Stanner, rust-for-linux, linux-kernel, driver-core
On Thu, Nov 19, 2026 at 02:37:17PM +0000, Gary Guo wrote:
> On Thu Nov 19, 2026 at 2:12 PM GMT, Alice Ryhl wrote:
> > __rust_helper void rust_helper_init_work_with_key(struct work_struct *work,
> > work_func_t func,
> > - bool onstack,
> > const char *name,
> > struct lock_class_key *key)
> > {
> > - __init_work(work, onstack);
> > + __init_work(work, object_is_on_stack(work));
>
> Is this fully optimized out if !CONFIG_DEBUG_OBJECTS_WORK?
Yes, on normal architectures (checked x86_64 and arm64 with Clang and
GCC): `get_current()` omits `volatile` and `current->stack` is a plain
load, so DCE removes all of `object_is_on_stack(work)` once the empty
`__init_work()` stub is inlined.
The one exception is `ARCH=um` with `CONFIG_SMP=y`, where `get_current()`
calls an external `uml_curr_cpu()` function without `__attribute_const__`
(and under `CONFIG_RUST_INLINE_HELPERS`, the dead `mrs`/`movq %gs:...`
inline asm stays in `helpers.bc` until backend codegen drops it). I can
wrap it in `if (IS_ENABLED(CONFIG_DEBUG_OBJECTS_WORK))` if I send a v5.
Alice
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v4 2/5] rust: workqueue: restrict delayed work to global wqs
2026-11-19 14:12 [PATCH v4 0/5] workqueue: OwnedQueue and ScopedWork Alice Ryhl
2026-11-19 14:12 ` [PATCH v4 1/5] rust: workqueue: support stack-allocated work items Alice Ryhl
@ 2026-11-19 14:12 ` Alice Ryhl
2026-11-19 14:12 ` [PATCH v4 3/5] rust: workqueue: create workqueue subdirectory Alice Ryhl
` (2 subsequent siblings)
4 siblings, 0 replies; 9+ messages in thread
From: Alice Ryhl @ 2026-11-19 14:12 UTC (permalink / raw)
To: Tejun Heo, Lai Jiangshan, Danilo Krummrich
Cc: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Daniel Almeida,
Tamir Duberstein, Alexandre Courbot, Onur Özkan,
John Hubbard, Philipp Stanner, rust-for-linux, linux-kernel,
driver-core, Alice Ryhl, stable
When a workqueue is shut down, delayed work that is pending but not
scheduled does not get properly cleaned up, so it's not safe to use
`enqueue_delayed` on a workqueue that might be destroyed. To fix this,
restricted `enqueue_delayed` to static queues.
This may be fixed in the future by an approach along the lines of [1].
Cc: stable@vger.kernel.org
Fixes: 7c098cd5eaae ("workqueue: rust: add delayed work items")
Reviewed-by: John Hubbard <jhubbard@nvidia.com>
Reviewed-by: Danilo Krummrich <dakr@kernel.org>
Reviewed-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Link: https://lore.kernel.org/r/20250423-destroy-workqueue-flush-v1-1-3d74820780a5@google.com [1]
Signed-off-by: Alice Ryhl <aliceryhl@google.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 6eb6c40138f2..5ef807ed6a33 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -302,8 +302,15 @@ pub fn enqueue<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput
///
/// This may fail if the work item is already enqueued in a workqueue.
///
+ /// This is only valid for global workqueues (with static lifetimes) because those are the only
+ /// ones that outlive all possible delayed work items.
+ ///
/// The work item will be submitted using `WORK_CPU_UNBOUND`.
- pub fn enqueue_delayed<W, const ID: u64>(&self, w: W, delay: Jiffies) -> W::EnqueueOutput
+ pub fn enqueue_delayed<W, const ID: u64>(
+ &'static self,
+ w: W,
+ delay: Jiffies,
+ ) -> W::EnqueueOutput
where
W: RawDelayedWorkItem<ID> + Send + 'static,
{
--
2.56.1.708.g77570a6a1d-goog
^ permalink raw reply [flat|nested] 9+ messages in thread* [PATCH v4 3/5] rust: workqueue: create workqueue subdirectory
2026-11-19 14:12 [PATCH v4 0/5] workqueue: OwnedQueue and ScopedWork Alice Ryhl
2026-11-19 14:12 ` [PATCH v4 1/5] rust: workqueue: support stack-allocated work items Alice Ryhl
2026-11-19 14:12 ` [PATCH v4 2/5] rust: workqueue: restrict delayed work to global wqs Alice Ryhl
@ 2026-11-19 14:12 ` Alice Ryhl
2026-11-19 14:37 ` Gary Guo
2026-11-19 14:12 ` [PATCH v4 4/5] rust: workqueue: add creation of workqueues Alice Ryhl
2026-11-19 14:12 ` [PATCH v4 5/5] rust: workqueue: add ScopedWork for non-'static work items Alice Ryhl
4 siblings, 1 reply; 9+ messages in thread
From: Alice Ryhl @ 2026-11-19 14:12 UTC (permalink / raw)
To: Tejun Heo, Lai Jiangshan, Danilo Krummrich
Cc: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Daniel Almeida,
Tamir Duberstein, Alexandre Courbot, Onur Özkan,
John Hubbard, Philipp Stanner, rust-for-linux, linux-kernel,
driver-core, Alice Ryhl
The following patch will implement a workqueue builder in a separate
file. To prepare for that, create a rust/kernel/workqueue subdirectory
and move the existing file.
Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Reviewed-by: Philipp Stanner <phasta@kernel.org>
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
MAINTAINERS | 1 +
rust/kernel/{workqueue.rs => workqueue/mod.rs} | 0
2 files changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index ccbcdc0799b9..9d5e2278f1f6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -30299,6 +30299,7 @@ F: Documentation/core-api/workqueue.rst
F: include/linux/workqueue.h
F: kernel/workqueue.c
F: kernel/workqueue_internal.h
+F: rust/kernel/workqueue/
WWAN DRIVERS
M: Loic Poulain <loic.poulain@oss.qualcomm.com>
diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue/mod.rs
similarity index 100%
rename from rust/kernel/workqueue.rs
rename to rust/kernel/workqueue/mod.rs
--
2.56.1.708.g77570a6a1d-goog
^ permalink raw reply [flat|nested] 9+ messages in thread* Re: [PATCH v4 3/5] rust: workqueue: create workqueue subdirectory
2026-11-19 14:12 ` [PATCH v4 3/5] rust: workqueue: create workqueue subdirectory Alice Ryhl
@ 2026-11-19 14:37 ` Gary Guo
0 siblings, 0 replies; 9+ messages in thread
From: Gary Guo @ 2026-11-19 14:37 UTC (permalink / raw)
To: Alice Ryhl, Tejun Heo, Lai Jiangshan, Danilo Krummrich
Cc: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Daniel Almeida,
Tamir Duberstein, Alexandre Courbot, Onur Özkan,
John Hubbard, Philipp Stanner, rust-for-linux, linux-kernel,
driver-core
On Thu Nov 19, 2026 at 2:12 PM GMT, Alice Ryhl wrote:
> The following patch will implement a workqueue builder in a separate
> file. To prepare for that, create a rust/kernel/workqueue subdirectory
> and move the existing file.
>
> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
> Reviewed-by: Philipp Stanner <phasta@kernel.org>
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Gary Guo <gary@garyguo.net>
> ---
> MAINTAINERS | 1 +
> rust/kernel/{workqueue.rs => workqueue/mod.rs} | 0
> 2 files changed, 1 insertion(+)
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v4 4/5] rust: workqueue: add creation of workqueues
2026-11-19 14:12 [PATCH v4 0/5] workqueue: OwnedQueue and ScopedWork Alice Ryhl
` (2 preceding siblings ...)
2026-11-19 14:12 ` [PATCH v4 3/5] rust: workqueue: create workqueue subdirectory Alice Ryhl
@ 2026-11-19 14:12 ` Alice Ryhl
2026-11-19 14:12 ` [PATCH v4 5/5] rust: workqueue: add ScopedWork for non-'static work items Alice Ryhl
4 siblings, 0 replies; 9+ messages in thread
From: Alice Ryhl @ 2026-11-19 14:12 UTC (permalink / raw)
To: Tejun Heo, Lai Jiangshan, Danilo Krummrich
Cc: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Daniel Almeida,
Tamir Duberstein, Alexandre Courbot, Onur Özkan,
John Hubbard, Philipp Stanner, rust-for-linux, linux-kernel,
driver-core, Alice Ryhl
Creating workqueues is needed by various GPU drivers. Not only does it
give you better control over execution, it also allows devices to ensure
that all tasks have exited before the device is unbound (or similar) by
running the workqueue destructor.
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Co-developed-by: Danilo Krummrich <dakr@kernel.org>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
rust/helpers/workqueue.c | 7 +
rust/kernel/workqueue/builder.rs | 370 +++++++++++++++++++++++++++++++++++++++
rust/kernel/workqueue/mod.rs | 51 +++++-
3 files changed, 425 insertions(+), 3 deletions(-)
diff --git a/rust/helpers/workqueue.c b/rust/helpers/workqueue.c
index 337382acfbf5..7699dcdd5e05 100644
--- a/rust/helpers/workqueue.c
+++ b/rust/helpers/workqueue.c
@@ -19,3 +19,10 @@ __rust_helper void rust_helper_destroy_work_on_stack(struct work_struct *work)
{
destroy_work_on_stack(work);
}
+
+__rust_helper
+struct workqueue_struct *rust_helper_alloc_workqueue(const char *fmt, unsigned int flags,
+ int max_active, const void *data)
+{
+ return alloc_workqueue(fmt, flags, max_active, data);
+}
diff --git a/rust/kernel/workqueue/builder.rs b/rust/kernel/workqueue/builder.rs
new file mode 100644
index 000000000000..d253c2f8ed4a
--- /dev/null
+++ b/rust/kernel/workqueue/builder.rs
@@ -0,0 +1,370 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Workqueue builders.
+
+use kernel::{
+ alloc::AllocError,
+ prelude::*,
+ workqueue::{
+ OwnedQueue, //
+ Queue,
+ }, //
+};
+
+use core::{
+ marker::PhantomData,
+ ptr::{
+ self,
+ NonNull, //
+ },
+};
+
+/// Workqueue builder.
+///
+/// A valid combination of workqueue flags contains one of the base flags (`WQ_UNBOUND`, `WQ_BH`,
+/// or `WQ_PERCPU`) and a combination of modifier flags that are compatible with the selected base
+/// flag.
+///
+/// For details, please refer to `Documentation/core-api/workqueue.rst`.
+pub struct Builder<Kind> {
+ flags: bindings::wq_flags,
+ max_active: i32,
+ _kind: PhantomData<Kind>,
+}
+
+pub enum TypeUnbound {}
+pub enum TypePercpu {}
+pub enum TypePowerEfficient {}
+pub enum TypeBH {}
+pub enum TypeOrdered {}
+
+/// Entry-points to the builder API.
+impl Queue {
+ /// Build a workqueue whose work may execute on any cpu.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_unbound().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from unbound wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_UNBOUND")]
+ pub fn new_unbound() -> Builder<TypeUnbound> {
+ Builder {
+ flags: bindings::wq_flags_WQ_UNBOUND,
+ max_active: 0,
+ _kind: PhantomData,
+ }
+ }
+
+ /// Build a workqueue whose work items are bound to the CPU they are queued on.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_percpu().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from percpu wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_PERCPU")]
+ pub fn new_percpu() -> Builder<TypePercpu> {
+ Builder {
+ flags: bindings::wq_flags_WQ_PERCPU,
+ max_active: 0,
+ _kind: PhantomData,
+ }
+ }
+
+ /// Build a power-efficient workqueue.
+ ///
+ /// A power-efficient workqueue is per-CPU by default, but becomes unbound when the
+ /// `workqueue.power_efficient` kernel parameter is set.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_power_efficient().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from power-efficient wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_POWER_EFFICIENT")]
+ pub fn new_power_efficient() -> Builder<TypePowerEfficient> {
+ Builder {
+ flags: bindings::wq_flags_WQ_PERCPU | bindings::wq_flags_WQ_POWER_EFFICIENT,
+ max_active: 0,
+ _kind: PhantomData,
+ }
+ }
+
+ /// Build a single-threaded workqueue that executes jobs in order.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_ordered().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from ordered wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "alloc_ordered_workqueue")]
+ #[doc(alias = "__WQ_ORDERED")]
+ pub fn new_ordered() -> Builder<TypeOrdered> {
+ Builder {
+ flags: bindings::wq_flags_WQ_UNBOUND | bindings::wq_flags___WQ_ORDERED,
+ max_active: 1,
+ _kind: PhantomData,
+ }
+ }
+
+ /// Build a workqueue that executes in bottom-half (softirq) context.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_bh().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from BH wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_BH")]
+ pub fn new_bh() -> Builder<TypeBH> {
+ Builder {
+ flags: bindings::wq_flags_WQ_PERCPU | bindings::wq_flags_WQ_BH,
+ max_active: 0,
+ _kind: PhantomData,
+ }
+ }
+}
+
+/// Options that may be used with all workqueue types.
+impl<Kind> Builder<Kind> {
+ /// Mark this workqueue high priority.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_unbound().highpri().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from highpri wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_HIGHPRI")]
+ pub fn highpri(mut self) -> Self {
+ self.flags |= bindings::wq_flags_WQ_HIGHPRI;
+ self
+ }
+
+ /// Creates the workqueue.
+ ///
+ /// The provided name is used verbatim as the workqueue name.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// // create an unbound workqueue registered with sysfs
+ /// let wq = Queue::new_unbound().sysfs().build(c"my-wq")?;
+ ///
+ /// // spawn a work item on it
+ /// wq.try_spawn(
+ /// GFP_KERNEL,
+ /// || pr_warn!("Printing from my-wq"),
+ /// )?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "alloc_workqueue")]
+ pub fn build(self, name: &CStr) -> Result<OwnedQueue, AllocError> {
+ // SAFETY:
+ // * c"%s" is compatible with passing the name as a c-string.
+ // * the builder only permits valid flag combinations
+ let ptr = unsafe {
+ bindings::alloc_workqueue(
+ c"%s".as_char_ptr(),
+ self.flags,
+ self.max_active,
+ name.as_char_ptr().cast::<c_void>(),
+ )
+ };
+
+ // INVARIANT: We successfully created the workqueue, so we can return ownership to the
+ // caller.
+ Ok(OwnedQueue {
+ queue: NonNull::new(ptr).ok_or(AllocError)?.cast(),
+ })
+ }
+
+ /// Creates the workqueue.
+ ///
+ /// # Examples
+ ///
+ /// This example shows how to pass a Rust string formatter to the workqueue name, creating
+ /// workqueues with names such as `my-wq-1` and `my-wq-2`.
+ ///
+ /// ```
+ /// use kernel::workqueue::{Queue, OwnedQueue};
+ ///
+ /// fn my_wq(num: u32) -> Result<OwnedQueue> {
+ /// // create a percpu workqueue called my-wq-{num}
+ /// let wq = Queue::new_percpu().build_fmt(fmt!("my-wq-{num}"))?;
+ /// Ok(wq)
+ /// }
+ /// ```
+ #[inline]
+ pub fn build_fmt(self, name: kernel::fmt::Arguments<'_>) -> Result<OwnedQueue, AllocError> {
+ // SAFETY:
+ // * c"%pA" is compatible with passing an `Arguments` pointer.
+ // * the builder only permits valid flag combinations
+ let ptr = unsafe {
+ bindings::alloc_workqueue(
+ c"%pA".as_char_ptr(),
+ self.flags,
+ self.max_active,
+ ptr::from_ref(&name).cast::<c_void>(),
+ )
+ };
+
+ // INVARIANT: We successfully created the workqueue, so we can return ownership to the
+ // caller.
+ Ok(OwnedQueue {
+ queue: NonNull::new(ptr).ok_or(AllocError)?.cast(),
+ })
+ }
+}
+
+/// Indicates that this workqueue is threaded.
+pub trait TypeThreaded {}
+impl TypeThreaded for TypeUnbound {}
+impl TypeThreaded for TypePercpu {}
+impl TypeThreaded for TypePowerEfficient {}
+
+/// Options that are not available on BH or ordered workqueues.
+impl<Kind: TypeThreaded> Builder<Kind> {
+ /// Set the maximum number of concurrently executing work items.
+ ///
+ /// For percpu workqueues this is per-CPU. If not set, a default value of
+ /// `WQ_DFL_ACTIVE` is used. The maximum value is `WQ_MAX_ACTIVE`.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_unbound().max_active(16).build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from wq with max_active=16"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ pub fn max_active(mut self, max_active: u32) -> Self {
+ // If provided `max_active` is greater than `i32::MAX`, then we need to trigger the C-side
+ // comparison with `WQ_MAX_ACTIVE`, which we can do by clamping to `i32::MAX`.
+ self.max_active = i32::try_from(max_active).unwrap_or(i32::MAX);
+ self
+ }
+
+ /// Mark this workqueue as cpu intensive.
+ ///
+ /// Work items will not contribute to the concurrency level, preventing
+ /// them from stalling other work items in the same per-CPU worker pool.
+ /// This is meaningless for unbound workqueues.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_unbound().cpu_intensive().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from cpu-intensive wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_CPU_INTENSIVE")]
+ pub fn cpu_intensive(mut self) -> Self {
+ self.flags |= bindings::wq_flags_WQ_CPU_INTENSIVE;
+ self
+ }
+}
+
+/// Indicates that this workqueue runs in a normal context (as opposed to softirq context).
+pub trait TypeNormal {}
+impl TypeNormal for TypeUnbound {}
+impl TypeNormal for TypePercpu {}
+impl TypeNormal for TypePowerEfficient {}
+impl TypeNormal for TypeOrdered {}
+
+/// Options that are not available on BH workqueues.
+impl<Kind: TypeNormal> Builder<Kind> {
+ /// Make this workqueue visible in sysfs.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_unbound().sysfs().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from sysfs wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_SYSFS")]
+ pub fn sysfs(mut self) -> Self {
+ self.flags |= bindings::wq_flags_WQ_SYSFS;
+ self
+ }
+
+ /// Allow this workqueue to be frozen during suspend.
+ ///
+ /// Work items on the workqueue are drained and no new work items start
+ /// execution until thawed.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_unbound().freezable().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from freezable wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_FREEZABLE")]
+ pub fn freezable(mut self) -> Self {
+ self.flags |= bindings::wq_flags_WQ_FREEZABLE;
+ self
+ }
+
+ /// This workqueue may be used during memory reclaim.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::workqueue::Queue;
+ ///
+ /// let wq = Queue::new_unbound().mem_reclaim().build(c"my-wq")?;
+ /// wq.try_spawn(GFP_KERNEL, || pr_info!("Hello from mem_reclaim wq"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ #[doc(alias = "WQ_MEM_RECLAIM")]
+ pub fn mem_reclaim(mut self) -> Self {
+ self.flags |= bindings::wq_flags_WQ_MEM_RECLAIM;
+ self
+ }
+}
diff --git a/rust/kernel/workqueue/mod.rs b/rust/kernel/workqueue/mod.rs
index 5ef807ed6a33..4f334dbf256a 100644
--- a/rust/kernel/workqueue/mod.rs
+++ b/rust/kernel/workqueue/mod.rs
@@ -186,7 +186,10 @@
//! C header: [`include/linux/workqueue.h`](srctree/include/linux/workqueue.h)
use crate::{
- alloc::{AllocError, Flags},
+ alloc::{
+ self,
+ AllocError, //
+ },
container_of,
prelude::*,
sync::{
@@ -200,7 +203,14 @@
time::Jiffies,
types::Opaque,
};
-use core::{marker::PhantomData, ptr::NonNull};
+use core::{
+ marker::PhantomData,
+ ops::Deref,
+ ptr::NonNull, //
+};
+
+mod builder;
+pub use self::builder::Builder;
/// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
#[macro_export]
@@ -346,7 +356,7 @@ pub fn enqueue_delayed<W, const ID: u64>(
/// This method can fail because it allocates memory to store the work item.
pub fn try_spawn<T: 'static + Send + FnOnce()>(
&self,
- flags: Flags,
+ flags: alloc::Flags,
func: T,
) -> Result<(), AllocError> {
let init = pin_init!(ClosureWork {
@@ -359,6 +369,41 @@ pub fn try_spawn<T: 'static + Send + FnOnce()>(
}
}
+/// An owned kernel work queue.
+///
+/// Dropping a workqueue blocks on all pending work.
+///
+/// # Invariants
+///
+/// `queue` points at a valid workqueue that is owned by this `OwnedQueue`.
+pub struct OwnedQueue {
+ queue: NonNull<Queue>,
+}
+
+// SAFETY: `OwnedQueue` uniquely owns a valid `Queue`, which is `Send + Sync`.
+unsafe impl Send for OwnedQueue {}
+// SAFETY: `&OwnedQueue` only provides `&Queue` (via `Deref`), which is safe to share.
+unsafe impl Sync for OwnedQueue {}
+
+impl Deref for OwnedQueue {
+ type Target = Queue;
+ #[inline]
+ fn deref(&self) -> &Queue {
+ // SAFETY: By the type invariants, this pointer references a valid queue.
+ unsafe { &*self.queue.as_ptr() }
+ }
+}
+
+impl Drop for OwnedQueue {
+ #[inline]
+ fn drop(&mut self) {
+ // SAFETY: This `OwnedQueue` owns a valid workqueue, so we can destroy it. There is no
+ // delayed work scheduled on this queue that may attempt to use it after this call, as
+ // scheduling delayed work requires a 'static reference.
+ unsafe { bindings::destroy_workqueue(self.queue.as_ptr().cast()) }
+ }
+}
+
/// A helper type used in [`try_spawn`].
///
/// [`try_spawn`]: Queue::try_spawn
--
2.56.1.708.g77570a6a1d-goog
^ permalink raw reply [flat|nested] 9+ messages in thread* [PATCH v4 5/5] rust: workqueue: add ScopedWork for non-'static work items
2026-11-19 14:12 [PATCH v4 0/5] workqueue: OwnedQueue and ScopedWork Alice Ryhl
` (3 preceding siblings ...)
2026-11-19 14:12 ` [PATCH v4 4/5] rust: workqueue: add creation of workqueues Alice Ryhl
@ 2026-11-19 14:12 ` Alice Ryhl
4 siblings, 0 replies; 9+ messages in thread
From: Alice Ryhl @ 2026-11-19 14:12 UTC (permalink / raw)
To: Tejun Heo, Lai Jiangshan, Danilo Krummrich
Cc: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Trevor Gross, Daniel Almeida,
Tamir Duberstein, Alexandre Courbot, Onur Özkan,
John Hubbard, Philipp Stanner, rust-for-linux, linux-kernel,
driver-core, Alice Ryhl
From: Danilo Krummrich <dakr@kernel.org>
Add ScopedWork<'wq, T>, a work item wrapper bound to a specific
&'wq Queue whose destructor calls cancel_work_sync(), allowing T to
carry non-'static lifetimes. Ownership of the data is not transferred to
the workqueue; instead, the synchronous cancellation on drop guarantees
the work function is not running when the data is freed.
Each ScopedWork<'wq, T> is bound to a single Queue at construction and
enqueued via ScopedWork::enqueue() to uphold the non-reentrance
conditions documented in Documentation/core-api/workqueue.rst: queuing
an in-flight work item onto a different workqueue violates those
conditions, in which case cancel_work_sync() only waits for execution on
the last queued workqueue and may return while an earlier execution is
still running.
Because the cancellation guarantee only holds if the destructor runs
before the bound Queue or any lifetime in T expires, ScopedWork::new()
(and thus new_scoped_work!) is unsafe and requires that the resulting
value is never forgotten and is dropped before 'wq or T's lifetimes end.
In return, ScopedWork::enqueue() is a safe method.
ScopedWork does not use the Work/WorkItem machinery: it embeds the
work_struct directly and registers its own C callback, which recovers
the &ScopedWork<'_, T> via container_of!() and passes it to
ScopedWorkItem::run(). The work_struct, queue pointer, and user data
live in a private Inner<T> that is wrapped in Opaque as a whole, so that
the &mut Self held by the destructor while cancel_work_sync() waits does
not claim uniqueness over memory (including padding) that a worker
thread may still be reading through &ScopedWork<'_, T>.
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
Co-developed-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
rust/kernel/workqueue/mod.rs | 13 ++
rust/kernel/workqueue/scoped.rs | 410 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 423 insertions(+)
diff --git a/rust/kernel/workqueue/mod.rs b/rust/kernel/workqueue/mod.rs
index 4f334dbf256a..d80fced7f333 100644
--- a/rust/kernel/workqueue/mod.rs
+++ b/rust/kernel/workqueue/mod.rs
@@ -212,6 +212,13 @@
mod builder;
pub use self::builder::Builder;
+mod scoped;
+pub use self::scoped::{
+ new_scoped_work,
+ ScopedWork,
+ ScopedWorkItem, //
+};
+
/// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
#[macro_export]
macro_rules! new_work {
@@ -275,6 +282,12 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::workqueue_struct) -> &'a Queue
unsafe { &*ptr.cast::<Queue>() }
}
+ /// Obtain the raw `struct workqueue_struct` pointer.
+ #[inline]
+ pub fn as_raw(&self) -> *mut bindings::workqueue_struct {
+ self.0.get()
+ }
+
/// Enqueues a work item.
///
/// This may fail if the work item is already enqueued in a workqueue.
diff --git a/rust/kernel/workqueue/scoped.rs b/rust/kernel/workqueue/scoped.rs
new file mode 100644
index 000000000000..1f8c060241d6
--- /dev/null
+++ b/rust/kernel/workqueue/scoped.rs
@@ -0,0 +1,410 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Scoped work items.
+//!
+//! Provides [`ScopedWork`] for work items that may borrow data with some non-`'static` lifetime.
+//!
+//! Unlike [`Work`]-based items, ownership of a [`ScopedWork`] is not transferred to
+//! the workqueue. Instead, its destructor calls `cancel_work_sync()`, which guarantees that the
+//! work function is not running (and will not run) once the destructor returns. This is what
+//! allows the inner data to carry non-`'static` lifetimes.
+//!
+//! Creating a [`ScopedWork`] is `unsafe`, because the above guarantee only holds if the destructor
+//! actually runs: the value must not be forgotten, and must be dropped before the bound [`Queue`]
+//! or any lifetime in the inner data expires. Once created, a [`ScopedWork`] can be enqueued onto
+//! its bound workqueue using the safe [`ScopedWork::enqueue`].
+//!
+//! # Examples
+//!
+//! ```
+//! use kernel::workqueue::{
+//! new_scoped_work,
+//! Queue,
+//! ScopedWork,
+//! ScopedWorkItem,
+//! };
+//!
+//! struct MyWork<'a> {
+//! value: &'a u32,
+//! }
+//!
+//! impl ScopedWorkItem for MyWork<'_> {
+//! fn run(work: &ScopedWork<'_, Self>) {
+//! pr_info!("value = {}\n", work.value);
+//! }
+//! }
+//!
+//! let queue = Queue::new_unbound().build(c"my-wq")?;
+//! let value = 42;
+//!
+//! // Define `my_work` outside the `unsafe` block.
+//! let my_work = MyWork { value: &value };
+//! let work = KBox::pin_init(
+//! // SAFETY: `work` is not forgotten and is dropped before `queue` and `value`.
+//! unsafe { new_scoped_work!(&queue, "MyWork", my_work) },
+//! GFP_KERNEL,
+//! )?;
+//!
+//! work.enqueue();
+//!
+//! // Dropping `work` calls `cancel_work_sync()`, ensuring the work item has finished or been
+//! // cancelled before `value` and `queue` are dropped.
+//! drop(work);
+//! # Ok::<(), Error>(())
+//! ```
+
+use crate::{
+ bindings,
+ container_of,
+ prelude::*,
+ sync::LockClassKey,
+ types::Opaque, //
+};
+
+use super::Queue;
+#[cfg(doc)]
+use super::Work;
+
+use pin_init::Wrapper;
+
+use core::{
+ marker::PhantomData,
+ ops::Deref,
+ ptr::NonNull, //
+};
+
+/// Trait for types that can be used as scoped work items.
+///
+/// Implementers define the work function that executes when the item is dequeued by a workqueue
+/// thread. Because `&Self` is shared with the workqueue worker thread while the work item is
+/// executing, implementers must be [`Sync`].
+///
+/// The callback receives a reference to the containing [`ScopedWork`], which provides access to
+/// the inner data via [`Deref`] and can be re-enqueued from within the work function using
+/// [`ScopedWork::enqueue`].
+pub trait ScopedWorkItem: Sized + Sync {
+ /// Called when the work item is executed.
+ fn run(work: &ScopedWork<'_, Self>);
+}
+
+/// The payload of a [`ScopedWork`].
+///
+/// # Invariants
+///
+/// - `queue` points to the valid [`Queue`] bound to the enclosing [`ScopedWork`].
+/// - `work` is an initialized `work_struct` whose work function is [`ScopedWork::run`] and is only
+/// ever enqueued onto `queue`.
+/// - An `Inner<T>` only ever exists inside a [`ScopedWork<'_, T>`].
+#[pin_data]
+struct Inner<T: ScopedWorkItem> {
+ queue: NonNull<Queue>,
+ #[pin]
+ work: Opaque<bindings::work_struct>,
+ #[pin]
+ data: T,
+}
+
+/// A scoped work item that cancels synchronously on drop.
+///
+/// `ScopedWork<'wq, T>` is bound to a single [`Queue`] with lifetime `'wq` and contains a
+/// `work_struct` and the user data `T`. Its destructor calls `cancel_work_sync()`, guaranteeing
+/// the work function is not running when the data is dropped.
+///
+/// This allows `T` to carry non-`'static` lifetimes.
+///
+/// Construct via [`new_scoped_work!`], which returns an `impl PinInit` suitable for embedding
+/// in-place inside other pinned structs. Because the soundness of [`ScopedWork::enqueue`] relies
+/// on the destructor running before the memory is reused or `'wq` or any lifetime in `T` expires,
+/// [`ScopedWork::new`] is `unsafe`.
+///
+/// # Examples
+///
+/// Self-re-enqueueing from within the work function:
+///
+/// ```
+/// use kernel::sync::atomic::{Atomic, Relaxed};
+/// use kernel::sync::Completion;
+/// use kernel::workqueue::{new_scoped_work, Queue, ScopedWork, ScopedWorkItem};
+///
+/// #[pin_data]
+/// struct RequeueWork<'a> {
+/// counter: &'a Atomic<u32>,
+/// #[pin]
+/// done: Completion,
+/// }
+///
+/// impl ScopedWorkItem for RequeueWork<'_> {
+/// fn run(work: &ScopedWork<'_, Self>) {
+/// if work.counter.fetch_add(1, Relaxed) < 2 {
+/// work.enqueue();
+/// } else {
+/// work.done.complete_all();
+/// }
+/// }
+/// }
+///
+/// let queue = Queue::new_ordered().build(c"requeue_wq")?;
+/// let counter = Atomic::new(0u32);
+/// let counter_ref = &counter;
+///
+/// // Define `requeue` outside the `unsafe` block.
+/// let requeue = pin_init!(RequeueWork {
+/// counter: counter_ref,
+/// done <- Completion::new(),
+/// });
+/// let work = KBox::pin_init(
+/// // SAFETY: `work` is not forgotten and is dropped before `queue` and `counter`.
+/// unsafe { new_scoped_work!(&queue, "RequeueWork", requeue) },
+/// GFP_KERNEL,
+/// )?;
+///
+/// work.enqueue();
+/// work.done.wait_for_completion();
+/// drop(work);
+///
+/// assert_eq!(counter.load(Relaxed), 3);
+/// # Ok::<(), Error>(())
+/// ```
+#[pin_data(PinnedDrop)]
+#[repr(transparent)]
+pub struct ScopedWork<'wq, T: ScopedWorkItem> {
+ /// The whole payload is wrapped in [`Opaque`] on purpose: while the destructor waits in
+ /// `cancel_work_sync()`, a worker thread may still be executing [`ScopedWorkItem::run`] with a
+ /// shared reference to this value (and e.g. calling [`ScopedWork::enqueue`]), concurrently with
+ /// the `&mut Self` held by `drop`. [`Opaque`] opts out of the uniqueness guarantee of that
+ /// `&mut`. Wrapping individual fields would not be enough, since the `&mut Self` would still
+ /// claim exclusive access to `queue` and the padding bytes.
+ ///
+ /// # Invariants
+ ///
+ /// - `inner` is always initialized.
+ /// - The `queue` field inside `inner` points to the [`Queue`] bound to this `ScopedWork`,
+ /// which remains valid for `'wq`.
+ #[pin]
+ inner: Opaque<Inner<T>>,
+ _wq: PhantomData<&'wq Queue>,
+}
+
+// SAFETY: A `&ScopedWork<'_, T>` only hands out `&T` (via `Deref`, where `T: Sync` via
+// `ScopedWorkItem`), `&Queue` (via `queue()`, where `Queue: Sync`), and accesses the
+// `work_struct` only through the thread-safe C workqueue API.
+unsafe impl<T: ScopedWorkItem> Sync for ScopedWork<'_, T> {}
+
+// SAFETY: `Queue: Sync`, and the `work_struct` is only ever accessed through the
+// thread-safe C workqueue API. Moving `ScopedWork` transfers ownership of `T` (so `T` may
+// be dropped on the destination thread), which requires `T: Send`, while a worker thread
+// may concurrently access `&T` in `ScopedWork::run`, which is sound because
+// `T: ScopedWorkItem` implies `T: Sync`.
+unsafe impl<T: ScopedWorkItem + Send> Send for ScopedWork<'_, T> {}
+
+impl<T: ScopedWorkItem> Deref for ScopedWork<'_, T> {
+ type Target = T;
+
+ #[inline]
+ fn deref(&self) -> &T {
+ // SAFETY: `inner` is always initialized (type invariant), and `data` is only ever accessed
+ // through shared references.
+ unsafe { &(*self.inner.get()).data }
+ }
+}
+
+impl<'wq, T: ScopedWorkItem> ScopedWork<'wq, T> {
+ /// Creates a pin-initializer for a new scoped work item bound to `queue`.
+ ///
+ /// Use [`new_scoped_work!`] to automatically provide the lock class key.
+ ///
+ /// # Safety
+ ///
+ /// The caller must ensure that the destructor of the initialized `ScopedWork<'wq, T>` runs
+ /// before the memory it lives in is reused and before `'wq` or any lifetime in `T` expires.
+ /// In particular, the value must not be leaked, e.g. via [`core::mem::forget`] or by leaking
+ /// the allocation that contains it.
+ #[inline]
+ pub unsafe fn new<E>(
+ queue: &'wq Queue,
+ name: &'static CStr,
+ key: Pin<&'static LockClassKey>,
+ init: impl PinInit<T, E>,
+ ) -> impl PinInit<Self, E> {
+ // INVARIANT: `inner` is initialized with a legal value of type `Inner<T>`, whose `queue`
+ // points to `queue: &'wq Queue` (valid for `'wq`).
+ try_pin_init!(Self {
+ // INVARIANT:
+ // - `queue` points to the valid `Queue` bound to this `ScopedWork`.
+ // - `work` is initialized via `init_work_with_key` with `Self::run` as the work
+ // function and is only ever enqueued onto `queue`.
+ // - This `Inner<T>` is constructed directly inside `ScopedWork<'wq, T>`.
+ inner <- Opaque::pin_init(try_pin_init!(Inner::<T> {
+ queue: NonNull::from(queue),
+ // Initialize `data` first so that `init_work_with_key` is not called if `init`
+ // fails.
+ data <- init,
+ work <- Opaque::try_ffi_init(|slot| {
+ // SAFETY: `slot` is a valid pointer to uninitialized memory for a
+ // `work_struct`, and `Self::run` is a valid work function for a `work_struct`
+ // embedded in an `Inner<T>` that is embedded in a `ScopedWork<'wq, T>`.
+ unsafe {
+ bindings::init_work_with_key(
+ slot,
+ Some(Self::run),
+ name.as_char_ptr(),
+ key.as_ptr(),
+ )
+ };
+ Ok::<(), E>(())
+ }),
+ }? E)),
+ _wq: PhantomData,
+ }? E)
+ }
+
+ /// Returns the workqueue this work item is bound to.
+ #[inline]
+ pub fn queue(&self) -> &'wq Queue {
+ // SAFETY: `inner` is always initialized (type invariant), `queue` is never mutated
+ // after initialization, and the safety contract of `ScopedWork::new` ensures `'wq` has
+ // not expired while `self` is alive.
+ unsafe { (*self.inner.get()).queue.as_ref() }
+ }
+
+ /// Enqueues this work item on its bound workqueue.
+ ///
+ /// Returns `false` if the work item is already pending on the workqueue.
+ ///
+ /// The work item will be submitted using `WORK_CPU_UNBOUND`.
+ #[inline]
+ pub fn enqueue(&self) -> bool {
+ // SAFETY:
+ // - `self.queue().as_raw()` is a valid `workqueue_struct` pointer because `'wq` has
+ // not expired (by the safety contract of `ScopedWork::new`).
+ // - `self.raw_work()` is a valid `work_struct` initialized with `Self::run` (type
+ // invariant).
+ // - Because `self` is only ever enqueued onto `self.queue()` and never migrated across
+ // workqueues, `cancel_work_sync()` in `PinnedDrop::drop` is guaranteed to wait for
+ // any running execution of `Self::run` to complete before `drop` returns; and
+ // `ScopedWork::new` guarantees `drop` runs before the backing memory is reused or
+ // `'wq` or any lifetime in `T` expires.
+ // - `T: ScopedWorkItem` guarantees `T: Sync`, so sharing `&T` with the worker thread is
+ // sound.
+ unsafe {
+ bindings::queue_work_on(
+ bindings::wq_misc_consts_WORK_CPU_UNBOUND as ffi::c_int,
+ self.queue().as_raw(),
+ self.raw_work(),
+ )
+ }
+ }
+
+ /// Returns a raw pointer to the `work_struct`.
+ #[inline]
+ fn raw_work(&self) -> *mut bindings::work_struct {
+ // SAFETY: `inner` is always initialized (type invariant).
+ unsafe { Opaque::cast_into(&raw const (*self.inner.get()).work) }
+ }
+
+ /// The work function registered with the C workqueue.
+ ///
+ /// # Safety
+ ///
+ /// `ptr` must point to the `work` field of the `Inner<T>` of a live `ScopedWork<'wq, T>`.
+ unsafe extern "C" fn run(ptr: *mut bindings::work_struct) {
+ // SAFETY: `Opaque<T>` is `#[repr(transparent)]`, and by the safety requirements `ptr`
+ // points to the `work` field of an `Inner<T>`.
+ let inner =
+ unsafe { container_of!(ptr.cast::<Opaque<bindings::work_struct>>(), Inner<T>, work) };
+
+ // SAFETY: `Inner<T>` only ever exists inside a `ScopedWork<'wq, T>` (type invariant), and
+ // both `Opaque` and `ScopedWork` are `#[repr(transparent)]`, so `inner` is also a valid
+ // pointer to the containing `ScopedWork<'wq, T>`. By the safety requirements it is live;
+ // its destructor calls `cancel_work_sync()` before the memory is released, so it stays
+ // live for the duration of this call. Moreover, `Self: Sync` (from `T: ScopedWorkItem` and
+ // `Queue: Sync`), so passing `&Self` on the worker thread is sound.
+ T::run(unsafe { &*inner.cast::<Self>() });
+ }
+}
+
+#[pinned_drop]
+impl<T: ScopedWorkItem> PinnedDrop for ScopedWork<'_, T> {
+ #[inline]
+ fn drop(self: Pin<&mut Self>) {
+ // SAFETY: `raw_work()` returns a valid `work_struct`. Because `work` is only ever
+ // enqueued onto its single bound `queue` (type invariant), `cancel_work_sync()` is
+ // guaranteed to wait for any running execution of `Self::run` to complete before returning.
+ unsafe { bindings::cancel_work_sync(self.raw_work()) };
+
+ // SAFETY: `raw_work()` returns a valid `work_struct` that has been cancelled and will not
+ // be used again.
+ unsafe { bindings::destroy_work_on_stack(self.raw_work()) };
+
+ // SAFETY: `inner` is initialized (type invariant), no longer accessed by the work
+ // function, and never accessed again after this point. `Opaque` does not drop its
+ // contents, so we have to do it here.
+ unsafe { core::ptr::drop_in_place(self.inner.get()) };
+ }
+}
+
+/// Creates a [`ScopedWork`] pin-initializer with a new lock class.
+///
+/// This macro expands to a call to [`ScopedWork::new`], which is `unsafe`, so the invocation must
+/// be wrapped in an `unsafe` block.
+///
+/// # Safety
+///
+/// The caller must uphold the safety requirements of [`ScopedWork::new`]: the destructor of the
+/// initialized `ScopedWork` must run before the memory it lives in is reused and before the bound
+/// [`Queue`]'s lifetime or any lifetime in the inner type expires.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::workqueue::{
+/// new_scoped_work,
+/// OwnedQueue,
+/// Queue,
+/// ScopedWork,
+/// ScopedWorkItem,
+/// };
+///
+/// struct MyWork {
+/// value: u32,
+/// }
+///
+/// impl ScopedWorkItem for MyWork {
+/// fn run(work: &ScopedWork<'_, Self>) {
+/// pr_info!("value = {}\n", work.value);
+/// }
+/// }
+///
+/// #[pin_data]
+/// struct MyData {
+/// #[pin]
+/// work: ScopedWork<'wq, MyWork>,
+/// wq: OwnedQueue,
+/// }
+///
+/// fn init_data() -> impl PinInit<MyData, Error> {
+/// // Define `my_work` outside the `unsafe` block.
+/// let my_work = MyWork { value: 7 };
+/// try_pin_init!(MyData {
+/// wq: Queue::new_unbound().build(c"my-wq")?,
+/// // SAFETY: `MyData` is only ever pin-initialized, and `work` is declared before `wq`,
+/// // so `work` is dropped before `wq`.
+/// work <- unsafe { new_scoped_work!(wq, "MyWork", my_work) },
+/// })
+/// }
+/// # pin_init::stack_try_pin_init!(let data =? init_data());
+/// # data.work().enqueue();
+/// # Ok::<(), Error>(())
+/// ```
+#[macro_export]
+macro_rules! new_scoped_work {
+ ($queue:expr, $name:literal, $init:expr $(,)?) => {
+ $crate::workqueue::ScopedWork::new(
+ $queue,
+ $crate::c_str!($name),
+ $crate::static_lock_class!(),
+ $init,
+ )
+ };
+}
+pub use new_scoped_work;
--
2.56.1.708.g77570a6a1d-goog
^ permalink raw reply [flat|nested] 9+ messages in thread