* [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
1 sibling, 0 replies; 3+ 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 [flat|nested] 3+ 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
1 sibling, 0 replies; 3+ 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 [flat|nested] 3+ messages in thread