All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior
@ 2026-11-16 15:50 Marco Crivellari
  2026-11-16 15:50 ` [PATCH v6 1/2] workqueue: Make alloc_workqueue() unbound by default Marco Crivellari
                   ` (2 more replies)
  0 siblings, 3 replies; 4+ messages in thread
From: Marco Crivellari @ 2026-11-16 15:50 UTC (permalink / raw)
  To: linux-kernel
  Cc: Tejun Heo, Lai Jiangshan, Frederic Weisbecker,
	Sebastian Andrzej Siewior, Marco Crivellari, Michal Hocko,
	Breno Leitao

Hi,

Currently alloc_workqueue() make sure one among WQ_UNBOUND or WQ_PERCPU is
present with the current default being WQ_PERCPU.

Per-CPU workqueues provide strict CPU affinity and concurrency
management. Some users rely on these properties, but many don't need
them, and for those users per-CPU workqueues significantly restrict
what the scheduler can do with their work items.

Unbound workqueues now use non-strict (soft) affinity scopes, so they
keep part of the locality benefits while giving the scheduler more
flexibility. This helps system-level concerns such as power management
and CPU isolation.

This series therefore transitions alloc_workqueue() to unbound as the
default. Users that need per-CPU behavior can still request it
explicitly with WQ_PERCPU.

The behavior changes as follows:

[ P1 ]

  - keep WARN_ON() if WQ_PERCPU and WQ_UNBOUND are present and drop
    WQ_PERCPU.

  - defaults to WQ_UNBOUND except for WQ_BH, that it is always per-CPU.

  - WQ_POWER_EFFICIENT description, kernel parameters and konfig
    description changed to reflect what this patch introduces.

[ P2 ]

  Documentation updated accordingly.

Thanks!

---
Changes in v6:
- rephrase cover letter

- change comments in workqueue.c, workqueue.h, power/Kconfig, kernel
  parameters so that they now reflect what has been done.

Link to v5: https://lore.kernel.org/all/20261102110047.115375-1-marco.crivellari@suse.com/

Changes in v5:
From Tejun / Breno:

- Dropped the pr_warn_once() when neither among WQ_PERCPU | WQ_UNBOUND is
  present and add WQ_UNBOUND.

- move wq_dropped_percpu declaration on top

- improve comments and commit log, so that it better describe also the
  reasons of this change.

- prefix "workqueue: doc:" on documentation improving descriptions about
  the flags.

Link to v4: https://lore.kernel.org/all/20261015140148.231126-1-marco.crivellari@suse.com/

Changes in v4:
- WQ_BH: add documentation about BH workqueue implying WQ_PERCPU

Link to v3: https://lore.kernel.org/all/20260904141421.287647-1-marco.crivellari@suse.com/

Changes in v3:
- WQ_BH require WQ_PERCPU

Link to v2: https://lore.kernel.org/all/20260903165251.481362-1-marco.crivellari@suse.com/

Changes in v2:
- if/else to add/drop WQ_UNBOUND/WQ_PERCPU moved before wq_size assignment

Link to v1: https://lore.kernel.org/all/20260903152204.401638-1-marco.crivellari@suse.com/

Marco Crivellari (2):
  workqueue: Make alloc_workqueue() unbound by default
  workqueue: doc: Update WQ_UNBOUND and WQ_BH documentation

 .../admin-guide/kernel-parameters.txt         | 15 +++-----
 Documentation/core-api/workqueue.rst          | 11 ++++--
 include/linux/workqueue.h                     | 23 +++++-------
 kernel/power/Kconfig                          |  7 ++--
 kernel/workqueue.c                            | 37 +++++++++++--------
 5 files changed, 46 insertions(+), 47 deletions(-)

-- 
2.56.0


^ permalink raw reply	[flat|nested] 4+ messages in thread

* [PATCH v6 1/2] workqueue: Make alloc_workqueue() unbound by default
  2026-11-16 15:50 [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior Marco Crivellari
@ 2026-11-16 15:50 ` Marco Crivellari
  2026-11-16 15:50 ` [PATCH v6 2/2] workqueue: doc: Update WQ_UNBOUND and WQ_BH documentation Marco Crivellari
  2026-11-16 21:06 ` [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior Tejun Heo
  2 siblings, 0 replies; 4+ messages in thread
From: Marco Crivellari @ 2026-11-16 15:50 UTC (permalink / raw)
  To: linux-kernel
  Cc: Tejun Heo, Lai Jiangshan, Frederic Weisbecker,
	Sebastian Andrzej Siewior, Marco Crivellari, Michal Hocko,
	Breno Leitao

Currently alloc_workqueue() ensures that one among WQ_PERCPU or WQ_UNBOUND
is present. Now every user has one among these two flags and if nothing
is specified the default is WQ_PERCPU.

Transition to unbound as the default: while some users benefit from the
strict affinity and concurrency management that per-CPU workqueues
provide, for a lot of users they don't matter and they put significant
restrictions on what the scheduler can do with the work items. Unbound
workqueues now have non-strict (soft) affinity scopes, so they don't lose
all the locality benefits while giving the scheduler more flexibility,
which helps system-level concerns such as power management and isolation.

In order to achieve the future goal of removing WQ_UNBOUND from the code,
start changing the default behavior making alloc_workqueue() act this way:

  - if WQ_PERCPU and WQ_UNBOUND are present: remove WQ_PERCPU (as before)
  - if neither are present: add WQ_UNBOUND

BH workqueues (WQ_BH) are always per-CPU and can't be unbound, so
WQ_PERCPU is now unconditionally forced for them before the above
defaulting logic runs.

The WARN_ONCE() when neither flag is present has been removed: from now
on, every alloc_workqueue() user without WQ_PERCPU will be considered
unbound.

The defaulting now happens before the workqueue is allocated, since
unbound workqueues need the node_nr_active[] array. Doing it before the
WQ_POWER_EFFICIENT override also makes sure that callers passing both
WQ_PERCPU and WQ_UNBOUND get the warning regardless of
wq_power_efficient.

Update the WQ_POWER_EFFICIENT comment accordingly.

Link: https://lore.kernel.org/all/20250221112003.1dSuoGyc@linutronix.de/
Suggested-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Marco Crivellari <marco.crivellari@suse.com>
Reviewed-by: Breno Leitao <leitao@debian.org>
---
 .../admin-guide/kernel-parameters.txt         | 15 +++-----
 include/linux/workqueue.h                     | 23 +++++-------
 kernel/power/Kconfig                          |  7 ++--
 kernel/workqueue.c                            | 37 +++++++++++--------
 4 files changed, 39 insertions(+), 43 deletions(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 2e8ee12e06de..5d4b42e04c94 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -8548,16 +8548,11 @@ Kernel parameters
 			The default is 4 times. 0 disables the warning.
 
 	workqueue.power_efficient
-			Per-cpu workqueues are generally preferred because
-			they show better performance thanks to cache
-			locality; unfortunately, per-cpu workqueues tend to
-			be more power hungry than unbound workqueues.
-
-			Enabling this makes the per-cpu workqueues which
-			were observed to contribute significantly to power
-			consumption unbound, leading to measurably lower
-			power usage at the cost of small performance
-			overhead.
+			Enabling workqueue.power_efficient kernel parameter makes
+			the per-cpu workqueues which were observed to contribute
+			significantly to power consumption unbound, leading to
+			measurably lower power usage at the cost of small
+			performance overhead.
 
 			The default value of this parameter is determined by
 			the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT.
diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h
index 6a220a57a9c6..1caacdb5bc8e 100644
--- a/include/linux/workqueue.h
+++ b/include/linux/workqueue.h
@@ -378,11 +378,11 @@ enum wq_flags {
 	WQ_SYSFS		= 1 << 6, /* visible in sysfs, see workqueue_sysfs_register() */
 
 	/*
-	 * Per-cpu workqueues are generally preferred because they tend to
-	 * show better performance thanks to cache locality.  Per-cpu
-	 * workqueues exclude the scheduler from choosing the CPU to
-	 * execute the worker threads, which has an unfortunate side effect
-	 * of increasing power consumption.
+	 * Workqueues are unbound by default. Per-cpu (WQ_PERCPU) workqueues
+	 * exclude the scheduler from choosing the CPU to execute the worker
+	 * threads, which has an unfortunate side effect of increasing power
+	 * consumption. WQ_POWER_EFFICIENT workqueue are per-CPU only if explicitly
+	 * marked WQ_PERCPU.
 	 *
 	 * The scheduler considers a CPU idle if it doesn't have any task
 	 * to execute and tries to keep idle cores idle to conserve power;
@@ -392,19 +392,16 @@ enum wq_flags {
 	 * turn may lead to more scheduling choices which are sub-optimal
 	 * in terms of power consumption.
 	 *
-	 * Workqueues marked with WQ_POWER_EFFICIENT are per-cpu by default
-	 * but become unbound if workqueue.power_efficient kernel param is
-	 * specified.  Per-cpu workqueues which are identified to
-	 * contribute significantly to power-consumption are identified and
-	 * marked with this flag and enabling the power_efficient mode
-	 * leads to noticeable power saving at the cost of small
-	 * performance disadvantage.
+	 * Per-cpu workqueues observed to contribute significantly to power
+	 * consumption are marked with WQ_POWER_EFFICIENT. They become
+	 * unbound if the workqueue.power_efficient kernel param is
+	 * specified.
 	 *
 	 * http://thread.gmane.org/gmane.linux.kernel/1480396
 	 */
 	WQ_POWER_EFFICIENT	= 1 << 7,
 	WQ_PERCPU		= 1 << 8, /* bound to a specific cpu */
-	WQ_RT			= 1 << 9, /* real-time priority, valid only with WQ_UNBOUND */
+	WQ_RT			= 1 << 9, /* real-time priority, invalid with WQ_PERCPU */
 
 	__WQ_DESTROYING		= 1 << 15, /* internal: workqueue is destroying */
 	__WQ_DRAINING		= 1 << 16, /* internal: workqueue is draining */
diff --git a/kernel/power/Kconfig b/kernel/power/Kconfig
index 71165e7f04f4..1a1880d7867a 100644
--- a/kernel/power/Kconfig
+++ b/kernel/power/Kconfig
@@ -374,10 +374,9 @@ config WQ_POWER_EFFICIENT_DEFAULT
 	bool "Enable workqueue power-efficient mode by default"
 	depends on PM
 	help
-	  Per-cpu workqueues are generally preferred because they show
-	  better performance thanks to cache locality; unfortunately,
-	  per-cpu workqueues tend to be more power hungry than unbound
-	  workqueues.
+	  Workqueues are unbound by default. Per-cpu workqueues can
+	  benefit from cache locality, but tend to be more power hungry
+	  than unbound workqueues.
 
 	  Enabling workqueue.power_efficient kernel parameter makes the
 	  per-cpu workqueues which were observed to contribute
diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index aed0516424be..558049dbb894 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -6121,6 +6121,7 @@ static struct workqueue_struct *__alloc_workqueue(const char *fmt,
 						  unsigned int flags,
 						  int max_active, va_list args)
 {
+	bool wq_dropped_percpu = false;
 	struct workqueue_struct *wq;
 	size_t wq_size;
 	int name_len;
@@ -6130,6 +6131,23 @@ static struct workqueue_struct *__alloc_workqueue(const char *fmt,
 			return NULL;
 		if (WARN_ON_ONCE(max_active))
 			return NULL;
+		flags |= WQ_PERCPU;
+	}
+
+	/*
+	 * Default to WQ_UNBOUND if neither WQ_PERCPU nor WQ_UNBOUND is set,
+	 * and drop WQ_PERCPU if both are. This must happen before the WQ_RT
+	 * check, which rejects workqueues without WQ_UNBOUND, and before
+	 * computing wq_size, which depends on WQ_UNBOUND. It must also
+	 * happen before the WQ_POWER_EFFICIENT override, which would
+	 * otherwise drop WQ_PERCPU when wq_power_efficient is enabled and
+	 * hide a caller passing both flags from the warning below.
+	 */
+	if (!(flags & (WQ_UNBOUND | WQ_PERCPU))) {
+		flags |= WQ_UNBOUND;
+	} else if (unlikely((flags & WQ_PERCPU) && (flags & WQ_UNBOUND))) {
+		flags &= ~WQ_PERCPU;
+		wq_dropped_percpu = true;
 	}
 
 	if (WARN_ON_ONCE((flags & WQ_RT) &&
@@ -6160,22 +6178,9 @@ static struct workqueue_struct *__alloc_workqueue(const char *fmt,
 		pr_warn_once("workqueue: name exceeds WQ_NAME_LEN. Truncating to: %s\n",
 			     wq->name);
 
-	/*
-	 * One among WQ_PERCPU and WQ_UNBOUND must be set, but not both.
-	 * - If neither is set, default to WQ_PERCPU
-	 * - If both are set, default to WQ_UNBOUND
-	 *
-	 * This code can be removed after workqueue are unbound by default
-	 */
-	if (unlikely(!(flags & (WQ_UNBOUND | WQ_PERCPU)))) {
-		WARN_ONCE(1, "workqueue: %s is using neither WQ_PERCPU or WQ_UNBOUND. "
-			  "Setting WQ_PERCPU.\n", wq->name);
-		flags |= WQ_PERCPU;
-	} else if (unlikely((flags & WQ_PERCPU) && (flags & WQ_UNBOUND))) {
-		WARN_ONCE(1, "workqueue: %s uses both WQ_PERCPU and WQ_UNBOUND. "
-			  "Dropped WQ_PERCPU, keeping WQ_UNBOUND.\n", wq->name);
-		flags &= ~WQ_PERCPU;
-	}
+	WARN_ONCE(wq_dropped_percpu,
+		  "workqueue: %s uses both WQ_PERCPU and WQ_UNBOUND. "
+		  "Dropped WQ_PERCPU, keeping WQ_UNBOUND.\n", wq->name);
 
 	if (flags & WQ_BH) {
 		/*
-- 
2.56.0


^ permalink raw reply related	[flat|nested] 4+ messages in thread

* [PATCH v6 2/2] workqueue: doc: Update WQ_UNBOUND and WQ_BH documentation
  2026-11-16 15:50 [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior Marco Crivellari
  2026-11-16 15:50 ` [PATCH v6 1/2] workqueue: Make alloc_workqueue() unbound by default Marco Crivellari
@ 2026-11-16 15:50 ` Marco Crivellari
  2026-11-16 21:06 ` [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior Tejun Heo
  2 siblings, 0 replies; 4+ messages in thread
From: Marco Crivellari @ 2026-11-16 15:50 UTC (permalink / raw)
  To: linux-kernel
  Cc: Tejun Heo, Lai Jiangshan, Frederic Weisbecker,
	Sebastian Andrzej Siewior, Marco Crivellari, Michal Hocko,
	Breno Leitao

When WQ_PERCPU is not present the default behavior is now WQ_UNBOUND,
so update the documentation accordingly, including the guideline that
recommended bound workqueues.

WQ_BH workqueues are the exception: they are always per-CPU, so
WQ_PERCPU is implied for them and WQ_UNBOUND is rejected. Mention that
in the WQ_BH section.

Link: https://lore.kernel.org/all/20250221112003.1dSuoGyc@linutronix.de/
Suggested-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Marco Crivellari <marco.crivellari@suse.com>
Reviewed-by: Breno Leitao <leitao@debian.org>
---
 Documentation/core-api/workqueue.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst
index 54697907f2b0..ef8f613ce402 100644
--- a/Documentation/core-api/workqueue.rst
+++ b/Documentation/core-api/workqueue.rst
@@ -178,7 +178,7 @@ resources, scheduled and executed.
   queueing CPU's softirq context in the queueing order.
 
   All BH workqueues must have 0 ``max_active`` and ``WQ_HIGHPRI`` is the
-  only allowed additional flag.
+  only allowed additional flag. ``WQ_PERCPU`` is implied.
 
   BH work items cannot sleep. All other features such as delayed queueing,
   flushing and canceling are supported.
@@ -190,6 +190,9 @@ resources, scheduled and executed.
   This flag is the complement of ``WQ_UNBOUND``.
 
 ``WQ_UNBOUND``
+  Workqueues without ``WQ_PERCPU`` are unbound by default, except for
+  ``WQ_BH`` workqueues, which are always per-CPU.
+
   Work items queued to an unbound wq are served by the special
   worker-pools which host workers which are not bound to any
   specific CPU.  This makes the wq behave as a simple execution
@@ -375,9 +378,9 @@ Guidelines
   wq and potentially lead to deadlock. It should utilize its own
   dedicated workqueue rather than the system wq.
 
-* Unless work items are expected to consume a huge amount of CPU
-  cycles, using a bound wq is usually beneficial due to the increased
-  level of locality in wq operations and work item execution.
+* Use ``WQ_PERCPU`` only if work items benefit from the increased level
+  of locality in wq operations and work item execution. Otherwise, the
+  default unbound wq is usually the better choice.
 
 
 Affinity Scopes
-- 
2.56.0


^ permalink raw reply related	[flat|nested] 4+ messages in thread

* Re: [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior
  2026-11-16 15:50 [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior Marco Crivellari
  2026-11-16 15:50 ` [PATCH v6 1/2] workqueue: Make alloc_workqueue() unbound by default Marco Crivellari
  2026-11-16 15:50 ` [PATCH v6 2/2] workqueue: doc: Update WQ_UNBOUND and WQ_BH documentation Marco Crivellari
@ 2026-11-16 21:06 ` Tejun Heo
  2 siblings, 0 replies; 4+ messages in thread
From: Tejun Heo @ 2026-11-16 21:06 UTC (permalink / raw)
  To: Marco Crivellari
  Cc: linux-kernel, Lai Jiangshan, Frederic Weisbecker,
	Sebastian Andrzej Siewior, Michal Hocko, Breno Leitao

> Marco Crivellari (2):
>   workqueue: Make alloc_workqueue() unbound by default
>   workqueue: doc: Update WQ_UNBOUND and WQ_BH documentation

Applied 1-2 to wq/for-7.5.

Thanks.

--
tejun

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2026-11-16 21:06 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-16 15:50 [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior Marco Crivellari
2026-11-16 15:50 ` [PATCH v6 1/2] workqueue: Make alloc_workqueue() unbound by default Marco Crivellari
2026-11-16 15:50 ` [PATCH v6 2/2] workqueue: doc: Update WQ_UNBOUND and WQ_BH documentation Marco Crivellari
2026-11-16 21:06 ` [PATCH v6 0/2] workqueue: Make WQ_UNBOUND the default behavior Tejun Heo

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.