Received-SPF: pass (google.com: domain of linux-kernel+bounces-59498-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
From: Waiman Long <longman@redhat.com>
To: Tejun Heo <tj@kernel.org>,
	Lai Jiangshan <jiangshanlai@gmail.com>
Cc: linux-kernel@vger.kernel.org,
	Waiman Long <longman@redhat.com>
Subject: [PATCH] workqueue: Fix kernel-doc comment of unplug_oldest_pwq()
Date: Fri,  9 Feb 2024 09:58:50 -0500
Message-Id: <20240209145850.1157304-1-longman@redhat.com>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

It turns out that it is not a good idea to put an ASCII diagram in the
kernel-doc comment of unplug_oldest_pwq() as the tool puts out warnings
about its format and will likely render it illegible anyway. Break the
ASCII diagram out into its own comment block inside the function to
avoid this problem.

Signed-off-by: Waiman Long <longman@redhat.com>
---
 kernel/workqueue.c | 32 ++++++++++++++++++--------------
 1 file changed, 18 insertions(+), 14 deletions(-)

diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index cd2c6edc5c66..f622f535bc00 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -1790,25 +1790,29 @@ static bool pwq_activate_first_inactive(struct pool_workqueue *pwq, bool fill)
  * unplug_oldest_pwq - restart an oldest plugged pool_workqueue
  * @wq: workqueue_struct to be restarted
  *
- * pwq's are linked into wq->pwqs with the oldest first. For ordered
- * workqueues, only the oldest pwq is unplugged, the others are plugged to
- * suspend execution until the oldest one is drained. When this happens, the
- * next oldest one (first plugged pwq in iteration) will be unplugged to
- * restart work item execution to ensure proper work item ordering.
- *
- *    dfl_pwq --------------+     [P] - plugged
- *                          |
- *                          v
- *    pwqs -> A -> B [P] -> C [P] (newest)
- *            |    |        |
- *            1    3        5
- *            |    |        |
- *            2    4        6
+ * This function should only be called for ordered workqueues where only the
+ * oldest pwq is unplugged, the others are plugged to suspend execution until
+ * the oldest one is drained and removed. When this happens, the next oldest
+ * one will be unplugged to restart work item execution to ensure proper work
+ * item ordering. Note that pwq's are linked into wq->pwqs with the oldest
+ * first, so the first one in the list is the oldest.
  */
 static void unplug_oldest_pwq(struct workqueue_struct *wq)
 {
 	struct pool_workqueue *pwq;
 
+	/*
+	 * Layout of an ordered workqueue during a wq_unbound_cpumask update:
+	 *
+	 *    dfl_pwq --------------+     [P] - plugged
+	 *                          |
+	 *                          v
+	 *    pwqs -> A -> B [P] -> C [P] (newest)
+	 *            |    |        |
+	 *            1    3        5
+	 *            |    |        |
+	 *            2    4        6
+	 */
 	lockdep_assert_held(&wq->mutex);
 
 	/* Caller should make sure that pwqs isn't empty before calling */
-- 
2.39.3