linux-kernel - Re: [PATCH v3 2/2] timers: Fix documentation for schedule

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-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <alpine.DEB.2.20.1610202254071.4938@nanos>
Date:   Thu, 20 Oct 2016 23:06:48 +0200 (CEST)
From:   Thomas Gleixner <tglx@...utronix.de>
To:     Douglas Anderson <dianders@...omium.org>
cc:     John Stultz <john.stultz@...aro.org>, Andreas Mohr <andi@...as.de>,
        briannorris@...omium.org, huangtao@...k-chips.com,
        tony.xie@...k-chips.com, linux-rockchip@...ts.infradead.org,
        linux@...ck-us.net, heiko@...ech.de, broonie@...nel.org,
        djkurtz@...omium.org, tskd08@...il.com,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 2/2] timers: Fix documentation for schedule_timeout()
 and similar

On Thu, 20 Oct 2016, Douglas Anderson wrote:
> +++ b/kernel/time/hrtimer.c
> @@ -1742,15 +1742,19 @@ schedule_hrtimeout_range_clock(ktime_t *expires, u64 delta,
>   * You can set the task state as follows -
>   *
>   * %TASK_UNINTERRUPTIBLE - at least @timeout time is guaranteed to
> - * pass before the routine returns.
> + * pass before the routine returns unless the current task is explicitly
> + * woken up, (e.g. by wake_up_process())".

The double quote is stray.

>   *
>   * %TASK_INTERRUPTIBLE - the routine may return early if a signal is
> - * delivered to the current task.
> + * delivered to the current task or the current task is explicitly woken
> + * up.
>   *
>   * The current task state is guaranteed to be TASK_RUNNING when this
>   * routine returns.
>   *
> - * Returns 0 when the timer has expired otherwise -EINTR
> + * Returns 0 when the timer has expired otherwise -EINTR. Note that
> + * -EINTR can still be returned even if the task state is
> + * TASK_UNINTERRUPTIBLE if the current task is explicitly woken up.

I'd prefer to word it this way:

Returns 0 when the timer has expired. If the task was woken before the
timer expired by a signal (only possible in state TASK_INTERRUPTIBLE) or by
an explicit wakeup, it returns -EINTR.


>   */
>  int __sched schedule_hrtimeout_range(ktime_t *expires, u64 delta,
>  				     const enum hrtimer_mode mode)
> @@ -1772,15 +1776,19 @@ EXPORT_SYMBOL_GPL(schedule_hrtimeout_range);
>   * You can set the task state as follows -
>   *
>   * %TASK_UNINTERRUPTIBLE - at least @timeout time is guaranteed to
> - * pass before the routine returns.
> + * pass before the routine returns unless the current task is explicitly
> + * woken up, (e.g. by wake_up_process())".

See above

>   *
>   * %TASK_INTERRUPTIBLE - the routine may return early if a signal is
> - * delivered to the current task.
> + * delivered to the current task or the current task is explicitly woken
> + * up.
>   *
>   * The current task state is guaranteed to be TASK_RUNNING when this
>   * routine returns.
>   *
> - * Returns 0 when the timer has expired otherwise -EINTR
> + * Returns 0 when the timer has expired otherwise -EINTR. Note that
> + * -EINTR can still be returned even if the task state is
> + * TASK_UNINTERRUPTIBLE if the current task is explicitly woken up.

See above

> @@ -1691,11 +1691,12 @@ static void process_timeout(unsigned long __data)
>   * You can set the task state as follows -
>   *
>   * %TASK_UNINTERRUPTIBLE - at least @timeout jiffies are guaranteed to
> - * pass before the routine returns. The routine will return 0
> + * pass before the routine returns unless the current task is explicitly
> + * woken up, (e.g. by wake_up_process())".
>   *
>   * %TASK_INTERRUPTIBLE - the routine may return early if a signal is
> - * delivered to the current task. In this case the remaining time
> - * in jiffies will be returned, or 0 if the timer expired in time
> + * delivered to the current task or the current task is explicitly woken
> + * up.
>   *
>   * The current task state is guaranteed to be TASK_RUNNING when this
>   * routine returns.
> @@ -1704,7 +1705,9 @@ static void process_timeout(unsigned long __data)
>   * the CPU away without a bound on the timeout. In this case the return
>   * value will be %MAX_SCHEDULE_TIMEOUT.
>   *
> - * In all cases the return value is guaranteed to be non-negative.
> + * Returns 0 when the timer has expired otherwise the remaining time in
> + * jiffies will be returned.  In all cases the return value is guaranteed
> + * to be non-negative.

That one is fine.

Thanks,

	tglx