Re: [patch V2 07/17] timers: Update kernel-doc for various functions
From: Anna-Maria Behnsen <anna-maria@linutronix.de>
Date: 2022-11-23 10:39:40
Also in:
linux-bluetooth, lkml
On Tue, 22 Nov 2022, Thomas Gleixner wrote:
quoted hunk ↗ jump to hunk
The kernel-doc of timer related functions is partially uncomprehensible word salad. Rewrite it to make it useful. Signed-off-by: Thomas Gleixner <redacted> Tested-by: Guenter Roeck <linux@roeck-us.net> --- V2: Refined comments (Steven) --- kernel/time/timer.c | 148 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 88 insertions(+), 60 deletions(-)--- a/kernel/time/timer.c +++ b/kernel/time/timer.c@@ -1200,11 +1212,12 @@ void add_timer(struct timer_list *timer) EXPORT_SYMBOL(add_timer); /** - * add_timer_on - start a timer on a particular CPU - * @timer: the timer to be added - * @cpu: the CPU to start it on + * add_timer_on - Start a timer on a particular CPU + * @timer: The timer to be started + * @cpu: The CPU to start it on * - * This is not very scalable on SMP. Double adds are not possible. + * This can only operate on an inactive timer. Attempts to invoke this on + * an active timer are rejected with a warning.
This is also true for add_timer(). Is it possible to add this to add_timer() function description and just referencing to add_timer() function description in add_timer_on()? They behave the same, only difference is the CPU where the timer is enqueued.
quoted hunk ↗ jump to hunk
*/ void add_timer_on(struct timer_list *timer, int cpu) {@@ -1240,15 +1253,18 @@ void add_timer_on(struct timer_list *tim EXPORT_SYMBOL_GPL(add_timer_on); /** - * del_timer - deactivate a timer. - * @timer: the timer to be deactivated - * - * del_timer() deactivates a timer - this works on both active and inactive - * timers. + * del_timer - Deactivate a timer. + * @timer: The timer to be deactivated * - * The function returns whether it has deactivated a pending timer or not. - * (ie. del_timer() of an inactive timer returns 0, del_timer() of an - * active timer returns 1.) + * The function only deactivates a pending timer, but contrary to + * del_timer_sync() it does not take into account whether the timers
timer's callback function or timer callback function (if the latter one is used, please replace it in description for del_timer_sync() as well).
+ * callback function is concurrently executed on a different CPU or not. + * It neither prevents rearming of the timer. If @timer can be rearmed
NIT ^ two whitespaces
+ * concurrently then the return value of this function is meaningless.
+ *
+ * Return:
+ * * %0 - The timer was not pending
+ * * %1 - The timer was pending and deactivated
*/
int del_timer(struct timer_list *timer)
{Thanks, Anna-Maria