From patchwork Thu Oct 20 20:34:24 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Doug Anderson X-Patchwork-Id: 9387535 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 EB8CF607D0 for ; Thu, 20 Oct 2016 20:35:14 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DD5D729B8C for ; Thu, 20 Oct 2016 20:35:14 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D197029C08; Thu, 20 Oct 2016 20:35:14 +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 A8B6A29B8C for ; Thu, 20 Oct 2016 20:35:13 +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 1bxK3U-0008VC-Bs; Thu, 20 Oct 2016 20:35:12 +0000 Received: from mail-pf0-x22a.google.com ([2607:f8b0:400e:c00::22a]) by bombadil.infradead.org with esmtps (Exim 4.85_2 #1 (Red Hat Linux)) id 1bxK3Q-0007Uz-Oa for linux-rockchip@lists.infradead.org; Thu, 20 Oct 2016 20:35:09 +0000 Received: by mail-pf0-x22a.google.com with SMTP id 128so43133226pfz.0 for ; Thu, 20 Oct 2016 13:34:48 -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=7j+6aSyu13GzbHk0Cq057uzq+FspTIeu99zM1wuYk70=; b=M00iPPWXqr+rZa/4tQL91Yai0rySOnzXcrKzOP7B7gyPvCB/1pG7QZUhVSssjnasOA GDqduxyuBZigR4CDSXk9zQXa6xtc7DWTx6opqeguQrDp08t6BLAL/r+WrbQ8rNNHelkv 35KzDQjXSqLpVKFyekjVKMeW6Gxq/6pyS5R1o= 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=7j+6aSyu13GzbHk0Cq057uzq+FspTIeu99zM1wuYk70=; b=KOzroVeS9f6czmRl7t9U3hi+I2LUDZIjMrvWmdoSK2J6f9cVhzR72M7WgQfIv+6Y4n bMhWCtE2IStOeDlre0Wmd/OkcYAqdje1iJFZhq0YCeL5TaPBeQMTMCyqGfQIKTqWEzXY beyK1WeW9k3LCDSVOPxmxV8sJBN3AnrVeZl4RZ+s5WW/S4nX3/Q0hJE09N15JP8jEtg9 rDKm2QP48cFPPW0zgrKjMvVwqLWwoUxUxLcTXaZBOEZsZfAQBTOKvQ8OTpD0yngZEN2x fBQ2fRFXNcEmwGaG0dPcbX6324UUchQZpWRsFizGsMI3EIKwRh+iygxDRTwxrqXWvBXk Hpow== X-Gm-Message-State: AA6/9RmobsnPYlKYI7/7mli9rjAr9EHItOBSxSMQKxjMwZHMAazpelcsUcNcJXcXnxboPREz X-Received: by 10.98.82.75 with SMTP id g72mr4496343pfb.119.1476995687622; Thu, 20 Oct 2016 13:34:47 -0700 (PDT) Received: from chromelab4.mtv.corp.google.com ([100.98.62.8]) by smtp.gmail.com with ESMTPSA id zh13sm73986359pab.4.2016.10.20.13.34.45 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 20 Oct 2016 13:34:46 -0700 (PDT) From: Douglas Anderson To: Thomas Gleixner , John Stultz Subject: [PATCH v3 2/2] timers: Fix documentation for schedule_timeout() and similar Date: Thu, 20 Oct 2016 13:34:24 -0700 Message-Id: <1476995664-15668-2-git-send-email-dianders@chromium.org> X-Mailer: git-send-email 2.8.0.rc3.226.g39d4020 In-Reply-To: <1476995664-15668-1-git-send-email-dianders@chromium.org> References: <1476995664-15668-1-git-send-email-dianders@chromium.org> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20161020_133508_886238_57FEDC00 X-CRM114-Status: GOOD ( 16.37 ) 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 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..707ecf47a5fd 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 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. */ 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 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. */ 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 219439efd56a..b2ca2a6bc4d2 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) {