lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Date: Fri,  9 Feb 2024 09:58:50 -0500
From: Waiman Long <longman@...hat.com>
To: Tejun Heo <tj@...nel.org>,
	Lai Jiangshan <jiangshanlai@...il.com>
Cc: linux-kernel@...r.kernel.org,
	Waiman Long <longman@...hat.com>
Subject: [PATCH] workqueue: Fix kernel-doc comment of unplug_oldest_pwq()

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@...hat.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


Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ