[PATCH v5 2/2] workqueue: doc: Update WQ_UNBOUND and WQ_BH documentation

[Marco Crivellari]

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. Update the
WQ_BH section accordingly, as WQ_HIGHPRI is no longer the only allowed
additional flag.

Link: https://lore.kernel.org/all/20250221112003.1dSuoGyc@xxxxxxxxxxxxx/
Suggested-by: Tejun Heo <tj@xxxxxxxxxx>
Signed-off-by: Marco Crivellari <marco.crivellari@xxxxxxxx>
Reviewed-by: Breno Leitao <leitao@xxxxxxxxxx>
---
 Documentation/core-api/workqueue.rst | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst
index bb770f556568..c14aa5555171 100644
--- a/Documentation/core-api/workqueue.rst
+++ b/Documentation/core-api/workqueue.rst
@@ -177,8 +177,9 @@ resources, scheduled and executed.
   workqueues are always per-CPU and all BH work items are executed in the
   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.
+  All BH workqueues must have 0 ``max_active``. ``WQ_HIGHPRI`` and
+  ``WQ_PERCPU`` are the only allowed additional flags. ``WQ_PERCPU`` is
+  implied, as BH workqueues cannot be unbound.
 
   BH work items cannot sleep. All other features such as delayed queueing,
   flushing and canceling are supported.
@@ -190,6 +191,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
@@ -368,9 +372,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