[PATCH v3 0/2] rust: add new workqueue functions

[PATCH v3 0/2] rust: add new workqueue functions

[Marco Crivellari]

Hi,

Recently the workqueue code has been changed introducing two new workqueue,
system_percpu_wq and system_dfl_wq, as a future replacement for system_wq and
system_unbound_wq respectively.

The change has been introduced by:
    'commit 128ea9f6ccfb ("workqueue: Add system_percpu_wq and system_dfl_wq")'

The old workqueue(s) will be removed in a next release cycle.

=== Introduced Changes by this series ===

1) [P 1-2] Add wrapper for the new workqueues
  -   This change introduce two new Rust functions in order to add a wrapper for
      the new wq(s) defined in the C code.


Thanks!

---
Changes in v3:
- added a proper comment documenting the new added functions.

Changes in v2:
- added system_percpu() and system_dfl() in order to use the new
  wq defined in the C code.

- fixed misleading paragraph in the commit log (no warnings are currently
  present).

Marco Crivellari (2):
  rust: replace use of system_unbound_wq with system_dfl_wq
  rust: replace use of system_wq with system_percpu_wq

 rust/kernel/workqueue.rs | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

-- 
2.51.0

[PATCH v3 1/2] rust: add system_dfl() around the new system_dfl_wq

[Marco Crivellari]

The C code defines 2 new workqueues: system_percpu_wq and system_dfl_wq,
respectively the futures replacement for system_wq and system_unbound_wq.

This change introduce system_dfl(), that use the new system_dfl_wq.

system_unbound_wq will be replaced in a future release cycle and should
not be used.

Suggested-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Marco Crivellari <marco.crivellari@suse.com>
---
 rust/kernel/workqueue.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index 706e833e9702..300cc2bfe012 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -968,11 +968,25 @@ pub fn system_long() -> &'static Queue {
 /// Workers are not bound to any specific CPU, not concurrency managed, and all queued work items
 /// are executed immediately as long as `max_active` limit is not reached and resources are
 /// available.
+///
+/// Note: `system_unbound_wq` will be removed in a future release cycle. Use [`system_dfl_wq`] instead.
 pub fn system_unbound() -> &'static Queue {
     // SAFETY: `system_unbound_wq` is a C global, always available.
     unsafe { Queue::from_raw(bindings::system_unbound_wq) }
 }
 
+/// Returns the system unbound work queue (`system_dfl_wq`).
+///
+/// Workers are not bound to any specific CPU, not concurrency managed, and all queued work items
+/// are executed immediately as long as `max_active` limit is not reached and resources are
+/// available.
+///
+/// Note: `system_dfl_wq` will replace in a future release cycle [`system_unbound_wq`].
+pub fn system_dfl() -> &'static Queue {
+    // SAFETY: `system_dfl_wq` is a C global, always available.
+    unsafe { Queue::from_raw(bindings::system_dfl_wq) }
+}
+
 /// Returns the system freezable work queue (`system_freezable_wq`).
 ///
 /// It is equivalent to the one returned by [`system`] except that it's freezable.
-- 
2.51.0

[PATCH v3 2/2] rust: add system_percpu() around the new system_percpu_wq

[Marco Crivellari]

The C code defines 2 new workqueues: system_percpu_wq and system_dfl_wq,
respectively the futures replacement for system_wq and system_unbound_wq.

This change introduce system_percpu(), that use the new system_percpu_wq.

system_wq will be replaced in a future release cycle and should
not be used.

Suggested-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Marco Crivellari <marco.crivellari@suse.com>
---
 rust/kernel/workqueue.rs | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index 300cc2bfe012..05f213444b91 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -940,11 +940,26 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for Pin<KBox<T>>
 /// users which expect relatively short queue flush time.
 ///
 /// Callers shouldn't queue work items which can run for too long.
+///
+/// Note: `system_wq` will be removed in a future release cycle. Use [`system_percpu_wq`] instead.
 pub fn system() -> &'static Queue {
     // SAFETY: `system_wq` is a C global, always available.
     unsafe { Queue::from_raw(bindings::system_wq) }
 }
 
+/// Returns the system work queue (`system_percpu_wq`).
+///
+/// It is the one used by `schedule[_delayed]_work[_on]()`. Multi-CPU multi-threaded. There are
+/// users which expect relatively short queue flush time.
+///
+/// Callers shouldn't queue work items which can run for too long.
+///
+/// Note: `system_percpu_wq` will replace ['system_wq`] in a future relase cycle.
+pub fn system_percpu() -> &'static Queue {
+    // SAFETY: `system_percpu_wq` is a C global, always available.
+    unsafe { Queue::from_raw(bindings::system_percpu_wq) }
+}
+
 /// Returns the system high-priority work queue (`system_highpri_wq`).
 ///
 /// It is similar to the one returned by [`system`] but for work items which require higher
-- 
2.51.0

Re: [PATCH v3 2/2] rust: add system_percpu() around the new system_percpu_wq

[Boqun Feng]

On Wed, Oct 08, 2025 at 05:15:54PM +0200, Marco Crivellari wrote:
> The C code defines 2 new workqueues: system_percpu_wq and system_dfl_wq,
> respectively the futures replacement for system_wq and system_unbound_wq.
> 
> This change introduce system_percpu(), that use the new system_percpu_wq.
> 
> system_wq will be replaced in a future release cycle and should
> not be used.
> 
> Suggested-by: Tejun Heo <tj@kernel.org>
> Signed-off-by: Marco Crivellari <marco.crivellari@suse.com>

If we were to expose the system_percpu_wq to Rust, then we should also
add queue_work_on() API to Rust, otherwise it's kinda pointless IMO.

PS. We can use the CpuId abstraction:

	http://rust.docs.kernel.org/kernel/cpu/struct.CpuId.html

and have an API like:

    ipml Queue {
        pub fn queue_on(&self, cpu: CpuId, w: W) -> W::EqueueOutput
    }

or maybe a different new type `PerCpuQueue`?

Regards,
Boqun

> ---
>  rust/kernel/workqueue.rs | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
> index 300cc2bfe012..05f213444b91 100644
> --- a/rust/kernel/workqueue.rs
> +++ b/rust/kernel/workqueue.rs
> @@ -940,11 +940,26 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for Pin<KBox<T>>
>  /// users which expect relatively short queue flush time.
>  ///
>  /// Callers shouldn't queue work items which can run for too long.
> +///
> +/// Note: `system_wq` will be removed in a future release cycle. Use [`system_percpu_wq`] instead.
>  pub fn system() -> &'static Queue {
>      // SAFETY: `system_wq` is a C global, always available.
>      unsafe { Queue::from_raw(bindings::system_wq) }
>  }
>  
> +/// Returns the system work queue (`system_percpu_wq`).
> +///
> +/// It is the one used by `schedule[_delayed]_work[_on]()`. Multi-CPU multi-threaded. There are
> +/// users which expect relatively short queue flush time.
> +///
> +/// Callers shouldn't queue work items which can run for too long.
> +///
> +/// Note: `system_percpu_wq` will replace ['system_wq`] in a future relase cycle.
> +pub fn system_percpu() -> &'static Queue {
> +    // SAFETY: `system_percpu_wq` is a C global, always available.
> +    unsafe { Queue::from_raw(bindings::system_percpu_wq) }
> +}
> +
>  /// Returns the system high-priority work queue (`system_highpri_wq`).
>  ///
>  /// It is similar to the one returned by [`system`] but for work items which require higher
> -- 
> 2.51.0
> 

Re: [PATCH v3 2/2] rust: add system_percpu() around the new system_percpu_wq

[Miguel Ojeda]

On Wed, Oct 8, 2025 at 5:16 PM Marco Crivellari
<marco.crivellari@suse.com> wrote:
>
> +/// Note: `system_percpu_wq` will replace ['system_wq`] in a future relase cycle.

Please check your patch with `make ... rustdoc` (which would complain
here about an unescaped backtick) and others like `make ... CLIPPY=1`:

    https://rust-for-linux.com/contributing#submit-checklist-addendum

Also, in general, please use intra-doc links wherever possible.

Thanks!

Cheers,
Miguel

Re: [PATCH v3 2/2] rust: add system_percpu() around the new system_percpu_wq

[Alice Ryhl]

On Wed, Oct 08, 2025 at 08:56:04AM -0700, Boqun Feng wrote:
> On Wed, Oct 08, 2025 at 05:15:54PM +0200, Marco Crivellari wrote:
> > The C code defines 2 new workqueues: system_percpu_wq and system_dfl_wq,
> > respectively the futures replacement for system_wq and system_unbound_wq.
> > 
> > This change introduce system_percpu(), that use the new system_percpu_wq.
> > 
> > system_wq will be replaced in a future release cycle and should
> > not be used.
> > 
> > Suggested-by: Tejun Heo <tj@kernel.org>
> > Signed-off-by: Marco Crivellari <marco.crivellari@suse.com>
> 
> If we were to expose the system_percpu_wq to Rust, then we should also
> add queue_work_on() API to Rust, otherwise it's kinda pointless IMO.
> 
> PS. We can use the CpuId abstraction:
> 
> 	http://rust.docs.kernel.org/kernel/cpu/struct.CpuId.html
> 
> and have an API like:
> 
>     ipml Queue {
>         pub fn queue_on(&self, cpu: CpuId, w: W) -> W::EqueueOutput
>     }
> 
> or maybe a different new type `PerCpuQueue`?
> 
> Regards,
> Boqun

How is it ... can we cleanly separate queues into those where you must
specify the cpuid, and those where you shouldn't?

Alice