From patchwork Fri Oct 21 15:58:51 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Doug Anderson X-Patchwork-Id: 9389581 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id A611F607D0 for ; Fri, 21 Oct 2016 16:00:08 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 964902A09D for ; Fri, 21 Oct 2016 16:00:08 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 8A4A82A133; Fri, 21 Oct 2016 16:00:08 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.1 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED, T_DKIM_INVALID autolearn=unavailable version=3.3.1 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.9]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 2A9952A09D for ; Fri, 21 Oct 2016 16:00:08 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.85_2 #1 (Red Hat Linux)) id 1bxcEp-0000rs-8w; Fri, 21 Oct 2016 16:00:07 +0000 Received: from mail-pf0-x22b.google.com ([2607:f8b0:400e:c00::22b]) by bombadil.infradead.org with esmtps (Exim 4.85_2 #1 (Red Hat Linux)) id 1bxcEb-0000Gr-Nw for linux-rockchip@lists.infradead.org; Fri, 21 Oct 2016 16:00:03 +0000 Received: by mail-pf0-x22b.google.com with SMTP id 128so59182153pfz.0 for ; Fri, 21 Oct 2016 08:59:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=PE6XOwuVCvYQkA6RI9l1E6rMKpVAtkTf29icy7rmQTo=; b=VaLseEpyQd14lbjC781PwWjRSP7WDIS4kjr4JE1zTGdhJA1TET+hXZgpjcRj/wIoYL eM1nB2JSBANlURrPh3Rceu6V9vplB2MCRL7uPx4FmqfczKMlIaMwafWpLKlqDwpu8zxZ gPQDPLCPmKKQNnZoBiocJYyAv1zevGqOb07Mo= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=PE6XOwuVCvYQkA6RI9l1E6rMKpVAtkTf29icy7rmQTo=; b=D5Dr6WUxB/sH4SUJRAAa2b+qBfnsKyH/t2TNEoaA8OzTqSUPbKoOJtq3KIB/IpiGHB 5VF58SQMzdrqFmVsswLYNJPvyLzkTKKOW57K2IyRShgEAABeECFeMxSM9cECkJ+3jDI1 TXwPV7nUpCJ7JThsvRr12t7lt2y+hAv25kLG1bqTAkE4pfnwJ3vgokNXM6qnpejJBAz/ 5lpodM1AaJUuZLg7pdZLUQFfniJOQeC8L05En2KDoPqW9ewMYTjowmzutdAS/fUZEdol OduFAODJd1M+E/AeSEU+PKqR/i+JJD8MUMfMUJF5P2AGiAZPtSZ3FvUOxJrdSJZ+4d8X vctQ== X-Gm-Message-State: ABUngvcMFlRLMuRyKoylKVylOE0VgGqPcRy+K0q+iSLWdt1UrRgcdLTMn/gIvPJiKnPmGT+s X-Received: by 10.99.152.25 with SMTP id q25mr2466757pgd.36.1477065572784; Fri, 21 Oct 2016 08:59:32 -0700 (PDT) Received: from chromelab4.mtv.corp.google.com ([100.98.62.8]) by smtp.gmail.com with ESMTPSA id f1sm6234114pfa.29.2016.10.21.08.59.31 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 21 Oct 2016 08:59:32 -0700 (PDT) From: Douglas Anderson To: Thomas Gleixner , John Stultz Subject: [PATCH v5 2/2] timers: Fix documentation for schedule_timeout() and similar Date: Fri, 21 Oct 2016 08:58:51 -0700 Message-Id: <1477065531-30342-2-git-send-email-dianders@chromium.org> X-Mailer: git-send-email 2.8.0.rc3.226.g39d4020 In-Reply-To: <1477065531-30342-1-git-send-email-dianders@chromium.org> References: <1477065531-30342-1-git-send-email-dianders@chromium.org> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20161021_085954_057885_D43AC378 X-CRM114-Status: GOOD ( 16.43 ) X-BeenThere: linux-rockchip@lists.infradead.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: Upstream kernel work for Rockchip platforms List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: huangtao@rock-chips.com, heiko@sntech.de, broonie@kernel.org, briannorris@chromium.org, Douglas Anderson , Andreas Mohr , linux-kernel@vger.kernel.org, linux-rockchip@lists.infradead.org, tony.xie@rock-chips.com, djkurtz@chromium.org, linux@roeck-us.net, tskd08@gmail.com MIME-Version: 1.0 Sender: "Linux-rockchip" Errors-To: linux-rockchip-bounces+patchwork-linux-rockchip=patchwork.kernel.org@lists.infradead.org X-Virus-Scanned: ClamAV using ClamSMTP The documentatoin for schedule_timeout(), schedule_hrtimeout(), and schedule_hrtimeout_range() all claimed that the routines couldn't possibly return early if the task state was TASK_UNINTERRUPTIBLE. This was simply not true since anyone calling wake_up_process() would cause those routines to exit early. As some evidence that the documentation was broken (not the code): - If we changed the code to match the documentation, msleep() would be identical to schedule_timeout_uninterruptible() and msleep_interruptible() would be identical to schedule_timeout_interruptible(). That doesn't seem likely to have been the intention. - The schedule() function sleeps until a task is woken up. Logically, one would expect that the schedule_timeout() function would sleep until a task is woken up or a timeout occurrs. As part of the above observation, it can be seen that schedule_hrtimeout() and schedule_hrtimeout_range() might return -EINTR even if the task state was TASK_UNINTERRUPTIBLE. This isn't terrible behavior so we'll document it and keep it as-is. After all, trying to match schedule_timeout() and return the time left would incure a bunch of extra calculation cost that isn't needed in all cases. Suggested-by: Daniel Kurtz Signed-off-by: Douglas Anderson --- Changes in v5: None Changes in v4: - Fixed stray double quotes. - Updated wording as per Thomas Gleixner. Changes in v3: - Documentation fix new for v3. kernel/time/hrtimer.c | 20 ++++++++++++++------ kernel/time/timer.c | 11 +++++++---- 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c index bb5ec425dfe0..08be5c99d26b 100644 --- a/kernel/time/hrtimer.c +++ 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()). * * %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. 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()). * * %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. 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(ktime_t *expires, const enum hrtimer_mode mode) diff --git a/kernel/time/timer.c b/kernel/time/timer.c index ab65e7bcc2c2..330214a19beb 100644 --- a/kernel/time/timer.c +++ b/kernel/time/timer.c @@ -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. */ signed long __sched schedule_timeout(signed long timeout) {