lkml.org 
[lkml]   [2022]   [Nov]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Date
    From
    SubjectRe: [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

    \
     
     \ /
      Last update: 2022-11-23 11:40    [W:5.309 / U:0.860 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site