Messages in this thread Patch in this message | | | Date | Wed, 23 Nov 2022 11:23:18 +0100 (CET) | From | Anna-Maria Behnsen <> | Subject | Re: [patch V2 07/17] timers: Update kernel-doc for various functions |
| |
On Tue, 22 Nov 2022, Thomas Gleixner wrote:
> The kernel-doc of timer related functions is partially uncomprehensible > word salad. Rewrite it to make it useful. > > Signed-off-by: Thomas Gleixner <tglx@linutronix.de> > 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.
> */ > 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
| |