From nobody Wed Nov 27 04:48:36 2024 Received: from galois.linutronix.de (Galois.linutronix.de [193.142.43.55]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id EED57153BD7; Mon, 14 Oct 2024 08:22:46 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=193.142.43.55 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1728894168; cv=none; b=Mp9vosiC88b5LTq2EqaJ1PFgZJ60VjYrAzH0Bd70lgDVsrze6zHV3+Qw1m5INGAPtrz9VKJ5kzZ1vAvNLbvxrqn5WhqMdAjQaaKa9YL2xKz1VfiitetHdWuIODHe6wvvwBS56snzYG+nh84U79DqGD9bIQAm9lmUAEbpUh6qPXM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1728894168; c=relaxed/simple; bh=m/9NfYkbSBspHRYgsc7+c2HJCNy9U5Uted8OLc7olNc=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=J81zKQdi6W0Mq68HyR1gCk9fatcw0vq0usGlK2HA3zVhkif1lRQpesFLEBgyaYf8dbUwVoQ/Ijk11QxhYLC7StiSYQaAyijRe3VV3JewBCMnTJ3IzxIywTF6Rt/hNLCDcVyzZ9gFxi/I+mhgQFsBVpZEcYf7fml+KP+JmXYWSt0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linutronix.de; spf=pass smtp.mailfrom=linutronix.de; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=JB3B9MMg; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=SX+7rtvs; arc=none smtp.client-ip=193.142.43.55 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linutronix.de Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linutronix.de Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="JB3B9MMg"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="SX+7rtvs" From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1728894164; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=x0dkMqLeJQoGt1aUXRfUeE0Qz3QS1tOrq27JnRdcMaI=; b=JB3B9MMgZrpNdD+97PFSwfowXw/9oxad6tmKLf41ufCVFqpuJx/OeMA8IvOpon89iqHQQO c6aDqQtoxfqFktbGRIgxdzrLHznykv52wyoeTmTF287qw8CIm9h2q4kMa6O/PlFu6Vr/0T KYgZv22UJKdzH/aulsFHah7fU3dssQv1mVr0vncAUNshjao123ZAugI/D9Y5YQ+QJZ8XCR apc6LbONMBzF/D7hTCKI/O8zQg+TJ+i3Jko7wtKp/jXfeWkyisjOVFouSQysP4zp0NhOwB iwc7LyuCeEZSj+qcuvsKDH95rEuBtl6MDwNwLG6tsMZx4Q/vSJkvpcxPlDFTTQ== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1728894164; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=x0dkMqLeJQoGt1aUXRfUeE0Qz3QS1tOrq27JnRdcMaI=; b=SX+7rtvshdB9bt6zvamBBqm/KeV9X/+Nr5j7BH6icZshhSkhKhdpxCW6tldmmaaqg12c6F WX/W/rMVUc5dzEDw== Date: Mon, 14 Oct 2024 10:22:20 +0200 Subject: [PATCH v3 03/16] timers: Update schedule_[hr]timeout*() related function descriptions Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20241014-devel-anna-maria-b4-timers-flseep-v3-3-dc8b907cb62f@linutronix.de> References: <20241014-devel-anna-maria-b4-timers-flseep-v3-0-dc8b907cb62f@linutronix.de> In-Reply-To: <20241014-devel-anna-maria-b4-timers-flseep-v3-0-dc8b907cb62f@linutronix.de> To: Frederic Weisbecker , Thomas Gleixner , Jonathan Corbet Cc: linux-kernel@vger.kernel.org, Len Brown , "Rafael J. Wysocki" , rust-for-linux@vger.kernel.org, Alice Ryhl , FUJITA Tomonori , Andrew Lunn , Anna-Maria Behnsen , Miguel Ojeda schedule_timeout*() functions do not have proper kernel-doc formatted function descriptions. schedule_hrtimeout() and schedule_hrtimeout_range() have a almost identical description. Add missing function descriptions. Remove copy of function description and add a pointer to the existing description instead. Signed-off-by: Anna-Maria Behnsen Acked-by: Frederic Weisbecker --- v2: New in v2 --- kernel/time/sleep_timeout.c | 66 ++++++++++++++++++++++++++++-------------= ---- 1 file changed, 41 insertions(+), 25 deletions(-) diff --git a/kernel/time/sleep_timeout.c b/kernel/time/sleep_timeout.c index 78b2e7e30b1e..560d17c30aa5 100644 --- a/kernel/time/sleep_timeout.c +++ b/kernel/time/sleep_timeout.c @@ -110,8 +110,17 @@ signed long __sched schedule_timeout(signed long timeo= ut) EXPORT_SYMBOL(schedule_timeout); =20 /* - * We can use __set_current_state() here because schedule_timeout() calls - * schedule() unconditionally. + * __set_current_state() can be used in schedule_timeout_*() functions, be= cause + * schedule_timeout() calls schedule() unconditionally. + */ + +/** + * schedule_timeout_interruptible - sleep until timeout (interruptible) + * @timeout: timeout value in jiffies + * + * See schedule_timeout() for details. + * + * Task state is set to TASK_INTERRUPTIBLE before starting the timeout. */ signed long __sched schedule_timeout_interruptible(signed long timeout) { @@ -120,6 +129,14 @@ signed long __sched schedule_timeout_interruptible(sig= ned long timeout) } EXPORT_SYMBOL(schedule_timeout_interruptible); =20 +/** + * schedule_timeout_killable - sleep until timeout (killable) + * @timeout: timeout value in jiffies + * + * See schedule_timeout() for details. + * + * Task state is set to TASK_KILLABLE before starting the timeout. + */ signed long __sched schedule_timeout_killable(signed long timeout) { __set_current_state(TASK_KILLABLE); @@ -127,6 +144,14 @@ signed long __sched schedule_timeout_killable(signed l= ong timeout) } EXPORT_SYMBOL(schedule_timeout_killable); =20 +/** + * schedule_timeout_uninterruptible - sleep until timeout (uninterruptible) + * @timeout: timeout value in jiffies + * + * See schedule_timeout() for details. + * + * Task state is set to TASK_UNINTERRUPTIBLE before starting the timeout. + */ signed long __sched schedule_timeout_uninterruptible(signed long timeout) { __set_current_state(TASK_UNINTERRUPTIBLE); @@ -134,9 +159,15 @@ signed long __sched schedule_timeout_uninterruptible(s= igned long timeout) } EXPORT_SYMBOL(schedule_timeout_uninterruptible); =20 -/* - * Like schedule_timeout_uninterruptible(), except this task will not cont= ribute - * to load average. +/** + * schedule_timeout_idle - sleep until timeout (idle) + * @timeout: timeout value in jiffies + * + * See schedule_timeout() for details. + * + * Task state is set to TASK_IDLE before starting the timeout. It is simil= ar to + * schedule_timeout_uninterruptible(), except this task will not contribut= e to + * load average. */ signed long __sched schedule_timeout_idle(signed long timeout) { @@ -151,6 +182,9 @@ EXPORT_SYMBOL(schedule_timeout_idle); * @delta: slack in expires timeout (ktime_t) * @mode: timer mode * @clock_id: timer clock to be used + * + * Details are explained in schedule_hrtimeout_range() function descriptio= n as + * this function is commonly used. */ int __sched schedule_hrtimeout_range_clock(ktime_t *expires, u64 delta, const enum hrtimer_mode mode, clockid_t clock_id) @@ -236,26 +270,8 @@ EXPORT_SYMBOL_GPL(schedule_hrtimeout_range); * @expires: timeout value (ktime_t) * @mode: timer mode * - * Make the current task sleep until the given expiry time has - * elapsed. The routine will return immediately unless - * the current task state has been set (see set_current_state()). - * - * You can set the task state as follows - - * - * %TASK_UNINTERRUPTIBLE - at least @timeout time is guaranteed to - * 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 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. 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. + * See schedule_hrtimeout_range() for details. @delta argument of + * schedule_hrtimeout_range() is set to 0 and has therefore no impact. */ int __sched schedule_hrtimeout(ktime_t *expires, const enum hrtimer_mode m= ode) { --=20 2.39.5