From patchwork Thu Oct 20 21:21:30 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Doug Anderson X-Patchwork-Id: 9387601 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 03DDC607D0 for ; Thu, 20 Oct 2016 21:22:23 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id EB30629C5E for ; Thu, 20 Oct 2016 21:22:22 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id DF99929C73; Thu, 20 Oct 2016 21:22:22 +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 81ABB29C5E for ; Thu, 20 Oct 2016 21:22:22 +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 1bxKn7-0004yU-Ku; Thu, 20 Oct 2016 21:22:21 +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 1bxKn2-0004mC-FV for linux-rockchip@lists.infradead.org; Thu, 20 Oct 2016 21:22:20 +0000 Received: by mail-pf0-x22a.google.com with SMTP id 128so43671190pfz.0 for ; Thu, 20 Oct 2016 14:21:56 -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=mUalakEloitPN8dKUSN868Yz3s16hN24tSRdY9w0Vpo=; b=TnWvz+tp7/llvRWAKqwbTYc3/yAyM7OfNAbEOw1Dan+VugrBsXqd3v9V7H79JpkGNw cav6PoA3QV1KbqvK9HbWI299H7NqBDibO7itTesdhVCuaV+r0ZbU9hXNVKkgB++VIJXm GgnR3Q7CGC36uatweZyuSRkNinSNaFBun0Jf0= 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=mUalakEloitPN8dKUSN868Yz3s16hN24tSRdY9w0Vpo=; b=jd3W6Dn3X9h+vwvFcM7s1XYIrMhNW/NR02glpfRtgu0dqrU3HJ//HL5lBsXV3a10Mw POr4sPotRhEDDoasnFbRLRTbfDKBhhmwsxZa4uEXxd1LJLfQLyxpIM6R6tJSGQUGbYn1 PfLt7gqcT/RxUTGQxV1CALGhzWmjuWqUgUJUaS5/tfoPMwiaGNeMNmOYl/Cncp7YX0TH JGuWQ+sWvLGAM8FhVSEOd65ElbBuV7pX74wJ1f2VR0iSK0gZwRfQiFEgPDhrjUFlM/ic kbBWwHD5P/tzT11tUgSO0gElX01lECeYYSuu3D4gn7lr14CRsqv2fOngMu4XTXt8FXEl psnA== X-Gm-Message-State: AA6/9Rk6tFPmBWbIQmZKYA0/mQBenZpI1CsfjcbbRoJU5HdDbCI5rUB9NIFF/Bzapv06F1YH X-Received: by 10.99.50.71 with SMTP id y68mr4043854pgy.111.1476998515495; Thu, 20 Oct 2016 14:21:55 -0700 (PDT) Received: from chromelab4.mtv.corp.google.com ([100.98.62.8]) by smtp.gmail.com with ESMTPSA id yz6sm752499pab.35.2016.10.20.14.21.54 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 20 Oct 2016 14:21:54 -0700 (PDT) From: Douglas Anderson To: Thomas Gleixner , John Stultz Subject: [PATCH v4 2/2] timers: Fix documentation for schedule_timeout() and similar Date: Thu, 20 Oct 2016 14:21:30 -0700 Message-Id: <1476998490-4481-2-git-send-email-dianders@chromium.org> X-Mailer: git-send-email 2.8.0.rc3.226.g39d4020 In-Reply-To: <1476998490-4481-1-git-send-email-dianders@chromium.org> References: <1476998490-4481-1-git-send-email-dianders@chromium.org> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20161020_142216_800110_47457983 X-CRM114-Status: GOOD ( 16.50 ) 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 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 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) {