From patchwork Tue Jan 23 16:46:55 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anna-Maria Behnsen X-Patchwork-Id: 191068 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp465649dyi; Tue, 23 Jan 2024 08:53:12 -0800 (PST) X-Google-Smtp-Source: AGHT+IFhA5wArEXK8LjvAxLkppq91DDzHLjlvXxVi6WtLCFJ7LbAT9gfAOs8wjXgRw6FQfTrmTKn X-Received: by 2002:ad4:5c88:0:b0:686:aafb:2696 with SMTP id o8-20020ad45c88000000b00686aafb2696mr415742qvh.29.1706028792547; Tue, 23 Jan 2024 08:53:12 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706028792; cv=pass; d=google.com; s=arc-20160816; b=acv31hzsN6NEsIzent9RVDOsGH6++/5GRvi83yu/UXl5zdkOw80jh1Zf6uTOYNKnak 10sl2dgnsiTItEbc15BMnMImTAHw7lCIst/WVe+UdweKHRstkh+WSFsbPJJ6YMSHfp4L 0Ujy8kmooy8E11rGNoF1uBD5rkTPNnmLfpBMAVhFZDMcUVKHhSnZx1Ro7dEPcrL4GKtE lQTayHG8+wunus5hztr79b6lEZLBF6JmEmlQdKQJI5Nub+fCLLGmixGyoDP7huooqrrI HurYVhrmB+fKc6zfnd6wvYYlo8B7JIIeTkmEgAB6CxMca/3wzfW4wnQyQaokibWLVpVP mHOQ== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:dkim-signature:dkim-signature:from; bh=ZfTDt6aPz62rV806CfoeHxKKD7o7Ht8+FmIptV0yh7g=; fh=nOEvUOtvIydWxxQpRdVGTZdE7oDfSvGmdNyLCMjLbrA=; b=uem3xIdvONj4UqjP1N9EK3FHGIOf6vVCPjnafeQP27nUuAByTPeMyf570FanrQFJFS JvqK5p9sZC128YGRGjeMClSOo5x3+IzNlVIHEWS4cxIY3vHexweWvbT1ibXOuSkSoUcl M3CAlXU4YcWo8AVId76vHgvqa5G/yIX7onvLKbdFhUoO34GHxa8g6vlnCmZWQUeHSP4m 84MItZLB4t0yVRmoPFhoxH6Tnays48cGJ2oomSqT5OYp+PVb1F/SUSrkQbNbkiIRmKY8 w5QgABCFb93grJt7kBuNLVtNLrwkKq0gW0Y8K7Cg1iGrmPveVcZKlq+YWbFwvqZ6NVen UKIg== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b="y/QQqeuL"; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e header.b=YaBAj9s4; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35701-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35701-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [147.75.199.223]) by mx.google.com with ESMTPS id a21-20020a0ca995000000b0068196a55b2csi7189942qvb.132.2024.01.23.08.53.12 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 08:53:12 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35701-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b="y/QQqeuL"; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e header.b=YaBAj9s4; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35701-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35701-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ny.mirrors.kernel.org (Postfix) with ESMTPS id 48B771C26A7C for ; Tue, 23 Jan 2024 16:53:12 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 2174B1292C9; Tue, 23 Jan 2024 16:47:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="y/QQqeuL"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="YaBAj9s4" 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 076E981AD4; Tue, 23 Jan 2024 16:47:17 +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=1706028439; cv=none; b=UYVGmkZhbOs37Z66iv00n6ts1/LRwt/tC8sO5J5XenQwurET0oxCll8LSmeDO+e/7Rwv52Nv4CH5p5CKMdFYlzTRNv2TjsWHYFQ0Z8qjB9EnMgKYaUcuykYvpzAujT3UtEeGTq4Z02VlU1DzDnPvpyQuP4r8uW2+ND4h72OVCSE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706028439; c=relaxed/simple; bh=bX7fuTKu2BCLrBdyLmngaZOPLBAKuCahp8JdL0FUnWc=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=uEOxwAC8ApAXcj3V+iKbsYDUwpZ6wPwXWJgdIRd9S4nt4r3K/uIfhULT0X+82zPwGX5Pa3yFGlA/zWA0vwdOHI5SYhhi1hTHTbDl/sqhF180ktCekuMXKG9ssQu/HHDNa5qBtlMb0rTp5cGGoe57jBhUTUQNm+Bmrg+PBG90vu0= 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=y/QQqeuL; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=YaBAj9s4; 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 From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1706028435; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZfTDt6aPz62rV806CfoeHxKKD7o7Ht8+FmIptV0yh7g=; b=y/QQqeuLECuIW8WkZWogpntfSkoK+YLtgxeoE0dF6y5jtmGsatmnaGRfzCwdu27XQfmF7t A5P94z4YNNZM1uWGpYJOXJYDcq92yiUuBmlq4THJ+XLuPeuWXGza+dUIHshKDuGMG0nHQM /IZic60FSpuCpVHvXLgqe2IfTwlFgy5SI7oCuzqjNmvY4h8AVcS8s4x4/ejsR3hMxaqppd LkC6SoWOnjYuMItHVIrqWmmIEmp5vPQkwPIZgmI6qlsVovLvfDPJNmX/InAUio1mI3OqDM WdBSwNsMxbQiRvphwhVIcfocV2CLM6RcPAA6cppjReNggDE0+77v0JAOJL6OtQ== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1706028435; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZfTDt6aPz62rV806CfoeHxKKD7o7Ht8+FmIptV0yh7g=; b=YaBAj9s4KrfS9Vk66W0YDX3sSr7JxKvaPxWzLf0F1TmZPxCS/NxjFYfSgmUAOpu9nEE07p hCXfgBIozzaFeVBg== To: linux-kernel@vger.kernel.org Cc: Thomas Gleixner , Frederic Weisbecker , Ingo Molnar , John Stultz , Stephen Boyd , Jonathan Corbet , Clemens Ladisch , linux-doc@vger.kernel.org, Anna-Maria Behnsen Subject: [PATCH 1/8] include/hrtimers: Move hrtimer base related definitions into hrtimer_defs Date: Tue, 23 Jan 2024 17:46:55 +0100 Message-Id: <20240123164702.55612-2-anna-maria@linutronix.de> In-Reply-To: <20240123164702.55612-1-anna-maria@linutronix.de> References: <20240123164702.55612-1-anna-maria@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788900847379524524 X-GMAIL-MSGID: 1788900847379524524 hrtimer base related struct definitions are part of hrtimers.h as it is required there. With this, also the struct documentation which is for core code internal use, is exposed into the general api. To prevent this, all core internal definitions and the related includes are moved into hrtimer_defs header file. Signed-off-by: Anna-Maria Behnsen --- include/linux/hrtimer.h | 103 ----------------------------------- include/linux/hrtimer_defs.h | 102 ++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 103 deletions(-) diff --git a/include/linux/hrtimer.h b/include/linux/hrtimer.h index 87e3bedf8eb0..792a0ac75378 100644 --- a/include/linux/hrtimer.h +++ b/include/linux/hrtimer.h @@ -18,12 +18,8 @@ #include #include #include -#include #include -struct hrtimer_clock_base; -struct hrtimer_cpu_base; - /* * Mode arguments of xxx_hrtimer functions: * @@ -98,105 +94,6 @@ struct hrtimer_sleeper { struct task_struct *task; }; -#ifdef CONFIG_64BIT -# define __hrtimer_clock_base_align ____cacheline_aligned -#else -# define __hrtimer_clock_base_align -#endif - -/** - * struct hrtimer_clock_base - the timer base for a specific clock - * @cpu_base: per cpu clock base - * @index: clock type index for per_cpu support when moving a - * timer to a base on another cpu. - * @clockid: clock id for per_cpu support - * @seq: seqcount around __run_hrtimer - * @running: pointer to the currently running hrtimer - * @active: red black tree root node for the active timers - * @get_time: function to retrieve the current time of the clock - * @offset: offset of this clock to the monotonic base - */ -struct hrtimer_clock_base { - struct hrtimer_cpu_base *cpu_base; - unsigned int index; - clockid_t clockid; - seqcount_raw_spinlock_t seq; - struct hrtimer *running; - struct timerqueue_head active; - ktime_t (*get_time)(void); - ktime_t offset; -} __hrtimer_clock_base_align; - -enum hrtimer_base_type { - HRTIMER_BASE_MONOTONIC, - HRTIMER_BASE_REALTIME, - HRTIMER_BASE_BOOTTIME, - HRTIMER_BASE_TAI, - HRTIMER_BASE_MONOTONIC_SOFT, - HRTIMER_BASE_REALTIME_SOFT, - HRTIMER_BASE_BOOTTIME_SOFT, - HRTIMER_BASE_TAI_SOFT, - HRTIMER_MAX_CLOCK_BASES, -}; - -/** - * struct hrtimer_cpu_base - the per cpu clock bases - * @lock: lock protecting the base and associated clock bases - * and timers - * @cpu: cpu number - * @active_bases: Bitfield to mark bases with active timers - * @clock_was_set_seq: Sequence counter of clock was set events - * @hres_active: State of high resolution mode - * @in_hrtirq: hrtimer_interrupt() is currently executing - * @hang_detected: The last hrtimer interrupt detected a hang - * @softirq_activated: displays, if the softirq is raised - update of softirq - * related settings is not required then. - * @nr_events: Total number of hrtimer interrupt events - * @nr_retries: Total number of hrtimer interrupt retries - * @nr_hangs: Total number of hrtimer interrupt hangs - * @max_hang_time: Maximum time spent in hrtimer_interrupt - * @softirq_expiry_lock: Lock which is taken while softirq based hrtimer are - * expired - * @timer_waiters: A hrtimer_cancel() invocation waits for the timer - * callback to finish. - * @expires_next: absolute time of the next event, is required for remote - * hrtimer enqueue; it is the total first expiry time (hard - * and soft hrtimer are taken into account) - * @next_timer: Pointer to the first expiring timer - * @softirq_expires_next: Time to check, if soft queues needs also to be expired - * @softirq_next_timer: Pointer to the first expiring softirq based timer - * @clock_base: array of clock bases for this cpu - * - * Note: next_timer is just an optimization for __remove_hrtimer(). - * Do not dereference the pointer because it is not reliable on - * cross cpu removals. - */ -struct hrtimer_cpu_base { - raw_spinlock_t lock; - unsigned int cpu; - unsigned int active_bases; - unsigned int clock_was_set_seq; - unsigned int hres_active : 1, - in_hrtirq : 1, - hang_detected : 1, - softirq_activated : 1; -#ifdef CONFIG_HIGH_RES_TIMERS - unsigned int nr_events; - unsigned short nr_retries; - unsigned short nr_hangs; - unsigned int max_hang_time; -#endif -#ifdef CONFIG_PREEMPT_RT - spinlock_t softirq_expiry_lock; - atomic_t timer_waiters; -#endif - ktime_t expires_next; - struct hrtimer *next_timer; - ktime_t softirq_expires_next; - struct hrtimer *softirq_next_timer; - struct hrtimer_clock_base clock_base[HRTIMER_MAX_CLOCK_BASES]; -} ____cacheline_aligned; - static inline void hrtimer_set_expires(struct hrtimer *timer, ktime_t time) { timer->node.expires = time; diff --git a/include/linux/hrtimer_defs.h b/include/linux/hrtimer_defs.h index 2d3e3c5fb946..b12869dba59a 100644 --- a/include/linux/hrtimer_defs.h +++ b/include/linux/hrtimer_defs.h @@ -3,6 +3,8 @@ #define _LINUX_HRTIMER_DEFS_H #include +#include +#include #ifdef CONFIG_HIGH_RES_TIMERS @@ -24,4 +26,104 @@ #endif +#ifdef CONFIG_64BIT +# define __hrtimer_clock_base_align ____cacheline_aligned +#else +# define __hrtimer_clock_base_align +#endif + +/** + * struct hrtimer_clock_base - the timer base for a specific clock + * @cpu_base: per cpu clock base + * @index: clock type index for per_cpu support when moving a + * timer to a base on another cpu. + * @clockid: clock id for per_cpu support + * @seq: seqcount around __run_hrtimer + * @running: pointer to the currently running hrtimer + * @active: red black tree root node for the active timers + * @get_time: function to retrieve the current time of the clock + * @offset: offset of this clock to the monotonic base + */ +struct hrtimer_clock_base { + struct hrtimer_cpu_base *cpu_base; + unsigned int index; + clockid_t clockid; + seqcount_raw_spinlock_t seq; + struct hrtimer *running; + struct timerqueue_head active; + ktime_t (*get_time)(void); + ktime_t offset; +} __hrtimer_clock_base_align; + +enum hrtimer_base_type { + HRTIMER_BASE_MONOTONIC, + HRTIMER_BASE_REALTIME, + HRTIMER_BASE_BOOTTIME, + HRTIMER_BASE_TAI, + HRTIMER_BASE_MONOTONIC_SOFT, + HRTIMER_BASE_REALTIME_SOFT, + HRTIMER_BASE_BOOTTIME_SOFT, + HRTIMER_BASE_TAI_SOFT, + HRTIMER_MAX_CLOCK_BASES, +}; + +/** + * struct hrtimer_cpu_base - the per cpu clock bases + * @lock: lock protecting the base and associated clock bases + * and timers + * @cpu: cpu number + * @active_bases: Bitfield to mark bases with active timers + * @clock_was_set_seq: Sequence counter of clock was set events + * @hres_active: State of high resolution mode + * @in_hrtirq: hrtimer_interrupt() is currently executing + * @hang_detected: The last hrtimer interrupt detected a hang + * @softirq_activated: displays, if the softirq is raised - update of softirq + * related settings is not required then. + * @nr_events: Total number of hrtimer interrupt events + * @nr_retries: Total number of hrtimer interrupt retries + * @nr_hangs: Total number of hrtimer interrupt hangs + * @max_hang_time: Maximum time spent in hrtimer_interrupt + * @softirq_expiry_lock: Lock which is taken while softirq based hrtimer are + * expired + * @timer_waiters: A hrtimer_cancel() invocation waits for the timer + * callback to finish. + * @expires_next: absolute time of the next event, is required for remote + * hrtimer enqueue; it is the total first expiry time (hard + * and soft hrtimer are taken into account) + * @next_timer: Pointer to the first expiring timer + * @softirq_expires_next: Time to check, if soft queues needs also to be expired + * @softirq_next_timer: Pointer to the first expiring softirq based timer + * @clock_base: array of clock bases for this cpu + * + * Note: next_timer is just an optimization for __remove_hrtimer(). + * Do not dereference the pointer because it is not reliable on + * cross cpu removals. + */ +struct hrtimer_cpu_base { + raw_spinlock_t lock; + unsigned int cpu; + unsigned int active_bases; + unsigned int clock_was_set_seq; + unsigned int hres_active : 1, + in_hrtirq : 1, + hang_detected : 1, + softirq_activated : 1; +#ifdef CONFIG_HIGH_RES_TIMERS + unsigned int nr_events; + unsigned short nr_retries; + unsigned short nr_hangs; + unsigned int max_hang_time; +#endif +#ifdef CONFIG_PREEMPT_RT + spinlock_t softirq_expiry_lock; + atomic_t timer_waiters; +#endif + ktime_t expires_next; + struct hrtimer *next_timer; + ktime_t softirq_expires_next; + struct hrtimer *softirq_next_timer; + struct hrtimer_clock_base clock_base[HRTIMER_MAX_CLOCK_BASES]; +} ____cacheline_aligned; + + #endif From patchwork Tue Jan 23 16:46:56 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anna-Maria Behnsen X-Patchwork-Id: 191116 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp486076dyi; Tue, 23 Jan 2024 09:23:30 -0800 (PST) X-Google-Smtp-Source: AGHT+IFtInmXMTfJNik46UnvUvhXXclz8bJwmfIUt8JzBg83Qhz1zeZ+zN9G5F46+HuODbx0rzD0 X-Received: by 2002:a17:903:2351:b0:1d7:137e:329d with SMTP id c17-20020a170903235100b001d7137e329dmr4084598plh.98.1706030610401; Tue, 23 Jan 2024 09:23:30 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706030610; cv=pass; d=google.com; s=arc-20160816; b=Alu3oU5s70eWFYvJiNof9oA8bQimc8QCQEice/8xYnhRL4HGyIjqWqqtXOpXHcmpib 60mklZerchcnPONrQXvDbV996PJQN76947cB7sGRiJuns6yCPHoWYRp1un+KvIMK9MRf x5qXVkrMjwwjZ+wuOg48LLziW/06g2YY7WuDHch6xH9Z7vZvIZqQ8Ahl8Ow5Ts3mO+N0 YQX32fWSgUAAAeTWEt78B+p2rzvgd3HpSGwbP9CmmdYDH/ofrqOdLJp91RVdt1jlocqv WNI7ASZeQACKde63SXYwhskzF4bYyGq0mOI6bD13GiDTWRuYDxo1LCoqCidBtlcoutq3 a7Rg== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:dkim-signature:dkim-signature:from; bh=JGyehJjSy1LmtgI6x+CLT4pSFNpa6twwbsgiLtZc8lY=; fh=nOEvUOtvIydWxxQpRdVGTZdE7oDfSvGmdNyLCMjLbrA=; b=VhV69NEtTXw3/5o+AJnKCzWWELMSBway/0v+wGdG7uaEvM/A3mrOJpwcWMv8x7Rjt9 Qm60zqzn7NxZuHQTL6DdHUaEj7D/2qg2xv++3r4L2uOipjPJaJb7qzaXBf+hc6ab/F+u RP7nBoRRXH6TRw2FvGJgqdiSnehpz6ipX/HwqDuZL2OuHsB6AnMRDh1Wt9noUV3AQGBX 9kH/SbpOd142CivtllkmEGZBFKVGGej9k42FAB54Z22yFEmlZGCAE60UmyWdr1uypUqS e6/1+EnSiDSsV6MCV6YAoUB/GUi1bta6HYVggHGa2DcTa6Ozt2E37GOTmj+wIsyq0lxH 2sLQ== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=ypNAgJ5o; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35704-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35704-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from sy.mirrors.kernel.org (sy.mirrors.kernel.org. [147.75.48.161]) by mx.google.com with ESMTPS id x5-20020a17090a8a8500b0028da227178dsi9972922pjn.76.2024.01.23.09.23.29 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 09:23:30 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35704-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) client-ip=147.75.48.161; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=ypNAgJ5o; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35704-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35704-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sy.mirrors.kernel.org (Postfix) with ESMTPS id 678B3B2C727 for ; Tue, 23 Jan 2024 16:53:07 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 004CE1292C3; Tue, 23 Jan 2024 16:47:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="ypNAgJ5o"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="C9fOdwLQ" 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 3494081AD7; Tue, 23 Jan 2024 16:47:17 +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=1706028441; cv=none; b=qQ7m7gGKBsJjXSdlCR3NnhwhIo8unH1eZ+nnIxmiN1fDwc6LAPlYKOSF0q+PtESdVFXFuLTwjhMjlobz/yE3/PhNRr/bQc8zzNP1ypS0bpIbVPLt5M+bW0Lj4YdON75t8epEXkkH6pdjhUPQQ52vkKepf56bc0WYkiIodvUO180= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706028441; c=relaxed/simple; bh=o5OrShZSySnx9z4Dc96d9/mMYCWz28Tvaz3npFr+rh4=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=FkwwzN8oBrTIKX95iITPdvFskZ/tNG4QNL0fX+oUBiJDo38OYZ6IiRk/+VTs/x53YIPmX82ZpU/fQw5b9VKwNHxWj7FpqipuXnlxlu4en+Ms/nvor1yaTsQ/C/7FYkOaYUJuL9MoCAu2l6QGCstRGZB+0OKEOoXqJavu8DbSYyg= 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=ypNAgJ5o; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=C9fOdwLQ; 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 From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1706028436; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=JGyehJjSy1LmtgI6x+CLT4pSFNpa6twwbsgiLtZc8lY=; b=ypNAgJ5o2E2HrqlcasGti3LkSQNxdrXdZpK9JPzmPiIh+nieeotJtuQlam2QQUyW2FwdgK PTXD2VHGz/jsq5tyUvhb32brf7YVn8pAGjm3pFP23paDbqsC3zHyC5vEyb0dzfn20332oV An79ByquwbNn8fY1tIgq0ek90xdP5NmQVAqIJQcsVym2dtf4NY+MxC7X9kJGGLJRdmctMI RbW9wNm2ODt45AXRey4okBAxfJ4gm9i5puw5zidlTQdff1Cug1S/X3JyyWNH869ovgYHoC MGC9rcRrGreFKf8vfLaEEj3A+0EMyIHt4RNU5oUUpIozb4moQPfpwYvCiUY0aA== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1706028436; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=JGyehJjSy1LmtgI6x+CLT4pSFNpa6twwbsgiLtZc8lY=; b=C9fOdwLQ6ND8D7qlZS9r8hvXNfAPDcBSNny1G4lDDZmmjGLKyyOosAMtTuLln5/CCnRo5r hvBfT3Tyrd9KZoBg== To: linux-kernel@vger.kernel.org Cc: Thomas Gleixner , Frederic Weisbecker , Ingo Molnar , John Stultz , Stephen Boyd , Jonathan Corbet , Clemens Ladisch , linux-doc@vger.kernel.org, Anna-Maria Behnsen Subject: [PATCH 2/8] hrtimers: Update formatting of documentation Date: Tue, 23 Jan 2024 17:46:56 +0100 Message-Id: <20240123164702.55612-3-anna-maria@linutronix.de> In-Reply-To: <20240123164702.55612-1-anna-maria@linutronix.de> References: <20240123164702.55612-1-anna-maria@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788902752973035969 X-GMAIL-MSGID: 1788902752973035969 Documentation of functions lacks the annotations which are used by kernel-doc and *.rst to make appearance in rendered documents more user-friendly. Use those annotations to improve user-friendliness. While at it prevent duplication of comments and use a reference instead. Signed-off-by: Anna-Maria Behnsen --- include/linux/hrtimer.h | 14 +++----------- kernel/time/hrtimer.c | 18 ++++++++++-------- 2 files changed, 13 insertions(+), 19 deletions(-) diff --git a/include/linux/hrtimer.h b/include/linux/hrtimer.h index 792a0ac75378..aa1e65ccb615 100644 --- a/include/linux/hrtimer.h +++ b/include/linux/hrtimer.h @@ -342,20 +342,12 @@ extern u64 hrtimer_forward(struct hrtimer *timer, ktime_t now, ktime_t interval); /** - * hrtimer_forward_now - forward the timer expiry so it expires after now + * hrtimer_forward_now() - forward the timer expiry so it expires after now * @timer: hrtimer to forward * @interval: the interval to forward * - * Forward the timer expiry so it will expire after the current time - * of the hrtimer clock base. Returns the number of overruns. - * - * Can be safely called from the callback function of @timer. If - * called from other contexts @timer must neither be enqueued nor - * running the callback and the caller needs to take care of - * serialization. - * - * Note: This only updates the timer expiry value and does not requeue - * the timer. + * It is a variant of hrtimer_forward(). The timer will expire after the current + * time of the hrtimer clock base. See hrtimer_forward() for details. */ static inline u64 hrtimer_forward_now(struct hrtimer *timer, ktime_t interval) diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c index 760793998cdd..4c8dd633ab4a 100644 --- a/kernel/time/hrtimer.c +++ b/kernel/time/hrtimer.c @@ -1021,21 +1021,23 @@ void unlock_hrtimer_base(const struct hrtimer *timer, unsigned long *flags) } /** - * hrtimer_forward - forward the timer expiry + * hrtimer_forward() - forward the timer expiry * @timer: hrtimer to forward * @now: forward past this time * @interval: the interval to forward * * Forward the timer expiry so it will expire in the future. - * Returns the number of overruns. * - * Can be safely called from the callback function of @timer. If - * called from other contexts @timer must neither be enqueued nor - * running the callback and the caller needs to take care of - * serialization. + * .. note:: + * This only updates the timer expiry value and does not requeue the timer. * - * Note: This only updates the timer expiry value and does not requeue - * the timer. + * There is also a variant of the function hrtimer_forward_now(). + * + * Context: Can be safely called from the callback function of @timer. If called + * from other contexts @timer must neither be enqueued nor running the + * callback and the caller needs to take care of serialization. + * + * Return: The number of overruns are returned. */ u64 hrtimer_forward(struct hrtimer *timer, ktime_t now, ktime_t interval) { From patchwork Tue Jan 23 16:46:57 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anna-Maria Behnsen X-Patchwork-Id: 191067 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp465417dyi; Tue, 23 Jan 2024 08:52:40 -0800 (PST) X-Google-Smtp-Source: AGHT+IHzz1s4HWZdmIS8eoTTDCi6Rgq0ZKpFbgOurTbjknzWV+UcJEB/dbjWQZxg3spOl6FG9jZU X-Received: by 2002:a17:906:8459:b0:a2f:b9be:66c9 with SMTP id e25-20020a170906845900b00a2fb9be66c9mr49878ejy.99.1706028760664; Tue, 23 Jan 2024 08:52:40 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706028760; cv=pass; d=google.com; s=arc-20160816; b=opube1/CjPagmPs+BXUHoi6ubGlhHkGtURrOy2W3hmfTft9RplFMvFfD+X4f3Xm/oo wg/KUGwVJE/TxRh49LX37qGhywUuR0BBKmr56dUrccOGs6UfJsjhkxdg6UJz8XYTEm+M vVTMhdKDD5mLp6DnZj9sq43b1dp825hq2wkgZ/BkySkHj84n8pMmg7uvZqx56sg1MPOI iGi5bHt2uEQamnVn+r5Lp/rAjbww32rgjN3azg/qaS7jc5GDq6zl0sGgbWbrDSKaaW+L gZMl8EiuKyTUJrk6NX39ahUMl5zUKUsq6pPhIRcR74FOTLJF+D5XAppSJBXuTggBcxJn Gs3A== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:dkim-signature:dkim-signature:from; bh=PhoBCIZZLnCECGPqIowTZ08lfwc9D2r/FOyJZ9QOgHo=; fh=nOEvUOtvIydWxxQpRdVGTZdE7oDfSvGmdNyLCMjLbrA=; b=elXJ/baM/oe10LB/S3kVfmnBwFgHBnkoRJxnA1CS5Cm8Nutxp1YuBx+vObCi4lQQWj tORgXBjnVSooZm2t7ESMlW4v83O5l/VspOxkpWml/eoHInm7a341Jz3wjFZi3cIvDd9j 8DjaShvFwIKNqxnXkHtoVV0+ISr6P4wKybICvZpRXZ93Ect8jIBxtFgGeibYhG0nX8GK /K7/xZYKikNc/1ZIf1eZZtP+TvkCQJ+5wSOJyiGBizd4LoesEuaB1oPvJJzXFd/HaQ0y ml/nF/oEzfYkLn9V1juNzC/a0M2mmWLnso6Har47a/+86mFVcHAvtpEi4kcV5mtPko5M 0Osg== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=BQbY4po9; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35702-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35702-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from am.mirrors.kernel.org (am.mirrors.kernel.org. [147.75.80.249]) by mx.google.com with ESMTPS id t27-20020a1709060c5b00b00a2e585a459esi7605478ejf.629.2024.01.23.08.52.40 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 08:52:40 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35702-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=BQbY4po9; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35702-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35702-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by am.mirrors.kernel.org (Postfix) with ESMTPS id 43BE81F30707 for ; Tue, 23 Jan 2024 16:52:40 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id EEA9185C52; Tue, 23 Jan 2024 16:47:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="BQbY4po9"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="hCS4YdrH" 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 8D30581ADA; Tue, 23 Jan 2024 16:47:18 +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=1706028440; cv=none; b=au+XFqf+TYO2rxzSUpnaNiJLpsxUOakg8T3yyg6n21xs1UAupLOGTGw0isset81C/5Uil0A9nMiOX50ZuFDuFz2WUS/X7HzVWZW+gVDPkZ5QXu/gN9bRHoHGzuGw9oorAqLDZgFlquWJ+IFPt3xqp1u97ibL5LR+qZJeo8zFqYc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706028440; c=relaxed/simple; bh=HFSMKE1bgjlAsGi1MrNiRokzcDfgJUWmntUgaecyamk=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=uoiQcr43motOuMY3+UmKSkcC4haIhNAzwlKaeFUJFLJT8wdD5QzRTGMzFflBzsBJsnPFounGbCrlOiFB1OyiRfsuq121jNn3mZcRgpw082XTJugutuVuwKWUdrVudtjfqpYrUKCDNr+WM7v3s1pZsbUd15iQw/97LTPDgOx9SPg= 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=BQbY4po9; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=hCS4YdrH; 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 From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1706028436; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=PhoBCIZZLnCECGPqIowTZ08lfwc9D2r/FOyJZ9QOgHo=; b=BQbY4po9HrsTcQSx6IkQD07yysEbfa4dnqHfgGWm2R08w1+kBTf3TcXMz1E0ZWoUu76L7R y+A/uJuVblFUHY0X9+q9KY/cr7ZvpMECXXNvn2OZKj12dvirphwqwWJYCr3QYydDrzduzr y/kBQGhCVHoHmuidPBEPv5TB0gdGuKRXypCoaNdQLrA80U2GGNstNYpxpZVREkGTkrIsoB RmZc9aXaj9PRk0HjiBwZCPAW0QiRGACAuIQAlvNDZWe7HmC78IKiN4GQL/nEmTOQAnbfOu +3mfaxW9XGUu+Pm/QmjfehV6rlL2VT2U4PNgE+P4/IfT/jCSNWQ750wKlAcXqA== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1706028436; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=PhoBCIZZLnCECGPqIowTZ08lfwc9D2r/FOyJZ9QOgHo=; b=hCS4YdrHkHiUDoT7f1qYKpzoe5053vW64j3zVCAWgRFdpio0XsNCTJa6rBZ33hdfoAjs2J Q0wxamm1ERTY60BQ== To: linux-kernel@vger.kernel.org Cc: Thomas Gleixner , Frederic Weisbecker , Ingo Molnar , John Stultz , Stephen Boyd , Jonathan Corbet , Clemens Ladisch , linux-doc@vger.kernel.org, Anna-Maria Behnsen Subject: [PATCH 3/8] tick/sched: Add function description for tick_nohz_next_event() Date: Tue, 23 Jan 2024 17:46:57 +0100 Message-Id: <20240123164702.55612-4-anna-maria@linutronix.de> In-Reply-To: <20240123164702.55612-1-anna-maria@linutronix.de> References: <20240123164702.55612-1-anna-maria@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788900814156744929 X-GMAIL-MSGID: 1788900814156744929 The return value of tick_nohz_next_event() is not obvious at the first glance. Add a kernel-doc compatible function description which also covers return values. Signed-off-by: Anna-Maria Behnsen --- kernel/time/tick-sched.c | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/kernel/time/tick-sched.c b/kernel/time/tick-sched.c index d2501673028d..e1d80f462551 100644 --- a/kernel/time/tick-sched.c +++ b/kernel/time/tick-sched.c @@ -799,6 +799,16 @@ static inline bool local_timer_softirq_pending(void) return local_softirq_pending() & BIT(TIMER_SOFTIRQ); } +/** + * tick_nohz_next_event() - return the clock monotonic based next event + * @ts: pointer to tick_sched struct + * @cpu: CPU number + * + * Return: + * *%0 - When the next event is a maximum of TICK_NSEC in the future + * and the tick is not stopped yet + * *%next_event - Next event based on clock monotonic + */ static ktime_t tick_nohz_next_event(struct tick_sched *ts, int cpu) { u64 basemono, next_tick, delta, expires; From patchwork Tue Jan 23 16:46:58 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anna-Maria Behnsen X-Patchwork-Id: 191111 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp484206dyi; Tue, 23 Jan 2024 09:20:14 -0800 (PST) X-Google-Smtp-Source: AGHT+IHT5Lv8lZ8mC1CwB4rp38+4HU7QDvOp5tltRJhCIOIb64b7Ea2V5s8aMEA6qrVdMjC1MFVA X-Received: by 2002:a17:90b:30c2:b0:28e:8012:f2b1 with SMTP id hi2-20020a17090b30c200b0028e8012f2b1mr3567187pjb.80.1706030414566; Tue, 23 Jan 2024 09:20:14 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706030414; cv=pass; d=google.com; s=arc-20160816; b=l76+K0hdGUJTyuzQpCjCfcU3DYN8OjjvTb2DHUvhrH0frvJ9i/1QDV5FWkRXA8Cq5N TFNkHPemax1/OCi3We27ALrm4JefqjmVw5KV0nPvZtdpLMHpH+r6EzR5gej2AKaD0/BA VCZYPYxjtsgQFuRJJaYDqLISkdk/NLu9RAZJuUem+c57eu9YCfDKywLzUQA4S8v/b/pz DZUSFlSJV3bXhPQAG2NmW7XiaGXwqw2ec6Ffo8mZVFHFHlgfx5grbSHsf4u0s51uA021 G5put0z7vhfrIGhqTfn1CYNWBFczray9IwlvXL7neumSCDnavR55K7QUz0WdWrSrsA3k hwYw== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:dkim-signature:dkim-signature:from; bh=d0sxRv/SQf4nMms7k/oUwYmN6EK8PHV+d6aCUPuL/OY=; fh=nOEvUOtvIydWxxQpRdVGTZdE7oDfSvGmdNyLCMjLbrA=; b=L2cWxnu5qBQFACwNBiPSViqMZ95MN4ER8LYpV7Nl2bUq24TTWL+B1xUcXiKpeHCJyw dumJcTScguCXW8QPw0U7XAznNvmLRSFapn3e8Hj2iKPEqKN/Z5aE3cdQUkgWG4J26OPR LyU/Kichv3q49nPf5fdRoOFW+cxsbOK7EhYMd0BT++2+7v0HXFjn9cvWPMd65KhLE0Al ND9pFC/Y3LRH663LlAIyN2RbcGkt5H1U+zXsD3V+6TPMOmt14G8x3AfqzHi/yovDPzAh 5zIPqG2ppJzOCF960wjaDMxUj6YUw55y8mLF5JuZMe3c26+PfRkaHAYuyk3D7x5aZMgx eRIA== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=IaV2OZp+; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35703-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35703-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from sy.mirrors.kernel.org (sy.mirrors.kernel.org. [147.75.48.161]) by mx.google.com with ESMTPS id fw21-20020a17090b129500b0029051ddf431si7656400pjb.115.2024.01.23.09.20.14 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 09:20:14 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35703-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) client-ip=147.75.48.161; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=IaV2OZp+; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35703-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35703-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sy.mirrors.kernel.org (Postfix) with ESMTPS id A6EFBB241FD for ; Tue, 23 Jan 2024 16:52:50 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 5C4E6128383; Tue, 23 Jan 2024 16:47:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="IaV2OZp+"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="PZvGQp3T" 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 C11A781ADD; Tue, 23 Jan 2024 16:47:18 +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=1706028440; cv=none; b=L9Vkkcl9x3AERU7feg4Rn+9fihm5Jav9TYok5gbZjWyR0SWC0yQroz+xhz0W0CwOVqyjV/CZ0NUQGKJAsAJ7u96TxkOzi0/I/NHCc727NZiv8AxlEroJWrf+KP9+OfwYc4ds3gBLKrFq3FI+KsGpJ++zTgdniLpRpnJV46/xxCA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706028440; c=relaxed/simple; bh=d8rsDzMorDANdDMVQ3WQDhgi/FdSTHxklICIHXgHMvk=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=h9F+ItRBiUVn0A0uMTBox/iZJ8sLeDFVBHi1a+0Td4r/6LjgdNJWO6cGFuRluo7ZtH7T01QFPN7ah16bH3AFZ/addpApPy5r61KMU/pOJv0cj6I5RgtXyQskIu7w/2eqNJvJbQhLORqLuvU8JLXM+Q2/jfx84u2w6YUp/5cZp2c= 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=IaV2OZp+; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=PZvGQp3T; 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 From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1706028437; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=d0sxRv/SQf4nMms7k/oUwYmN6EK8PHV+d6aCUPuL/OY=; b=IaV2OZp+82gkYOAV+dk4Zl5Pq/IpigdN4/qk/TGHR43GhajiQJlF66S9vy7HipdqedE1CD tR7/fM7p7wmhnPlcXqXpLGRWP+Lg9kpKEwq5UgVXI12WlInhyf6Dn0dkNOhMlb3zUipLJB GoYVByy4D6IOXkisiwyC4K9rdCtyWvSe/5sty5NPWBTsbmUF/SXbNZaD9HtvtCSm/G53Nv uf8uigvwGdqrT6VKFQZF/gDUC3ToIBf3Qlv0RwdVOqV5tQpsyQSAtyUrGv33enxt4qaZU+ zb8qvCrqT9TutCQttTLqWeMLnzJe72Q0r5vH3MY2fCzd/a5DhEArfgEbG5Loow== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1706028437; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=d0sxRv/SQf4nMms7k/oUwYmN6EK8PHV+d6aCUPuL/OY=; b=PZvGQp3T7mdQiqZcppvQM3x23Dfd6TVpV11f6Zpt1zxEhdsU4qQziTKnKgr9T2LfrL1bHC dosDHgv8nHgna1Dg== To: linux-kernel@vger.kernel.org Cc: Thomas Gleixner , Frederic Weisbecker , Ingo Molnar , John Stultz , Stephen Boyd , Jonathan Corbet , Clemens Ladisch , linux-doc@vger.kernel.org, Anna-Maria Behnsen Subject: [PATCH 4/8] timers: Add struct member description for timer_base Date: Tue, 23 Jan 2024 17:46:58 +0100 Message-Id: <20240123164702.55612-5-anna-maria@linutronix.de> In-Reply-To: <20240123164702.55612-1-anna-maria@linutronix.de> References: <20240123164702.55612-1-anna-maria@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788902548247810538 X-GMAIL-MSGID: 1788902548247810538 timer_base struct lacks description of struct members. Important struct member information is sprinkled in comments or in code all over the place. Collect information and write struct description to keep track of most important information in a single place. Signed-off-by: Anna-Maria Behnsen --- kernel/time/timer.c | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/kernel/time/timer.c b/kernel/time/timer.c index 352b161113cd..d44dba1d4af0 100644 --- a/kernel/time/timer.c +++ b/kernel/time/timer.c @@ -196,6 +196,51 @@ EXPORT_SYMBOL(jiffies_64); # define BASE_DEF 0 #endif +/** + * struct timer_base - Per CPU timer base (number of base depends on config) + * @lock: Lock protecting the timer_base + * @running_timer: When expiring timers, the lock is dropped. To make + * sure not to race agains deleting/modifying a + * currently running timer, the pointer is set to the + * timer, which expires at the moment. If no timer is + * running, the pointer is NULL. + * @expiry_lock: PREEMPT_RT only: Lock is taken in softirq around + * timer expiry callback execution and when trying to + * delete a running timer and it wasn't successful in + * the first glance. It prevents priority inversion + * when callback was preempted on a remote CPU and a + * caller tries to delete the running timer. It also + * prevents a life lock, when the task which tries to + * delete a timer preempted the softirq thread which + * is running the timer callback function. + * @timer_waiters: PREEMPT_RT only: Tells, if there is a waiter + * waiting for the end of the timer callback function + * execution. + * @clk: clock of the timer base; is updated before enqueue + * of a timer; during expiry, it is 1 offset ahead of + * jiffies to avoid endless requeuing to current + * jiffies + * @next_expiry: expiry value of the first timer; it is updated when + * finding the next timer and during enqueue; the + * value is not valid, when next_expiry_recalc is set + * @cpu: Number of CPU the timer base belongs to + * @next_expiry_recalc: States, whether a recalculation of next_expiry is + * required. Value is set true, when a timer was + * deleted. + * @is_idle: Is set, when timer_base is idle. It is triggered by NOHZ + * code. This state is only used in standard + * base. Deferrable timers, which are enqueued remotely + * never wake up an idle CPU. So no matter of supporting it + * for this base. + * @timers_pending: Is set, when a timer is pending in the base. It is only + * reliable when next_expiry_recalc is not set. + * @pending_map: bitmap of the timer wheel; each bit reflects a + * bucket of the wheel. When a bit is set, at least a + * single timer is enqueued in the related bucket. + * @vectors: Array of lists; Each array member reflects a bucket + * of the timer wheel. The list contains all timers + * which are enqueued into a specific bucket. + */ struct timer_base { raw_spinlock_t lock; struct timer_list *running_timer; From patchwork Tue Jan 23 16:46:59 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anna-Maria Behnsen X-Patchwork-Id: 191118 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp488634dyi; Tue, 23 Jan 2024 09:28:18 -0800 (PST) X-Google-Smtp-Source: AGHT+IE31e8cQlH6+HD7lDQ9OwVd1wUWxSb2BXDLyQ2M558P2SXBAv1+fArCP/02QjC1tszMT5gC X-Received: by 2002:a05:6a20:2453:b0:199:b9ef:9d6b with SMTP id t19-20020a056a20245300b00199b9ef9d6bmr3779994pzc.90.1706030898197; Tue, 23 Jan 2024 09:28:18 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706030898; cv=pass; d=google.com; s=arc-20160816; b=ZGZ+J5WP2oJj9hude3cmz6wO1KaRHuJwIZYSlswtXO8mvQNK1Ti1EpgGD9HgVIM2t+ 33Ngrp2COVckpkH9oRgFsVMlnzrcBU5LNgh01D7rc9N0/fpwhXLVU6KhwiBAzx4vDOQ9 YyIo9dbd955r1Q3PoNTEAd2EnC01cyjU1UlmSM1T8JNif+EWNPLD4vqOSKgHHKtupxpH 1bNr5YGNmWv5f4mcg0wOoFzrdF51/ecmbb3biHDAJgnafDHpoIJdgK6f7J4PAZrtbI0o yQ+R1bx6nySE/Dk0EJVWsY4DrexeJ/nuqV9CYYQLOqaBXIwfmsizPPcBu0BRTvPCBpsb K4UA== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:dkim-signature:dkim-signature:from; bh=khMougoG0mvpU1Mds2+gCdLAlfzbFK/BUtDBN3tuvqo=; fh=nOEvUOtvIydWxxQpRdVGTZdE7oDfSvGmdNyLCMjLbrA=; b=yJvplK3WKObt5W2ejHztSdNHumc7JRCGW0OOV+XTkHw2NfxjNh9XN93O3BUQZPUfPm CdE6oIiowRShZgPq0OGIGj5dKaSAEdKAeHDQbAtkLc1779l1UIYDe9KoLrpj1gfw5lXS TeBmgNSqkHFOGVLiduWnZhOJK/MaI+fVVCz7e1cYb8lYYGQPpTrG886ywabbc0jbcPx9 zem0VDzYagsciOZmlB3VIgIsLT50B/mykgzl3FL4TCEIWRW6r37TJJuR/DzNKVFnS4gC MjFWdAKqp6YYhMkz5/Em1gUAHcjFNbY1cWnhjlx2NxKPEKtJGlCw5/fICWOa3lgkPKqY ghDA== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=ozepGXdm; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35706-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35706-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from sy.mirrors.kernel.org (sy.mirrors.kernel.org. [147.75.48.161]) by mx.google.com with ESMTPS id q5-20020a056a00084500b006dbdb7770bfsi4567957pfk.178.2024.01.23.09.28.17 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 09:28:18 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35706-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) client-ip=147.75.48.161; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=ozepGXdm; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35706-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35706-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sy.mirrors.kernel.org (Postfix) with ESMTPS id 9CC1FB2CACB for ; Tue, 23 Jan 2024 16:53:40 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 4BC171292E7; Tue, 23 Jan 2024 16:47:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="ozepGXdm"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="IYABCsLS" 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 24A19823D9; Tue, 23 Jan 2024 16:47:20 +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=1706028442; cv=none; b=H+jj4QmuPm/lyTHUlr1KCXTEw01gQgYO9+Mfc3nrB7IPI8J2JqtwqEZLTldgoklqqorFAqy35EQMqShlsuL4PslueYYk9KK1kwARRSoj/b73T/Ppc7GCDaib4BtWuL1m2uvHKQ5J0uqvjfbBQuhKuZbp9yxKBWAgWF6WJRSVXVs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706028442; c=relaxed/simple; bh=99UGYF5IBxp9JpIFxVvetsxGYd/JCchgwfyQMLrGxD0=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=c4UzSwpEI7C3FqpbX+ROpyvtVxq63HIg10JPqxCNV6Q5mIc3YKI/oKfozmBvbh4iLB/9eCw/5EdZ513JkBkwy0f9R27j6HA0o0z9exGrXUU88KJtD6AGmmOJtpeNHfxJLeiRRLYYz5GQ3ITUZd1XX8f1zoYlLFPeEfMaJJLjQo8= 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=ozepGXdm; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=IYABCsLS; 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 From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1706028437; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=khMougoG0mvpU1Mds2+gCdLAlfzbFK/BUtDBN3tuvqo=; b=ozepGXdmD3hMx/BF8U/4Jdt4uD6N1cdvJPbTdgsyFVq6VqguU9Seefjg2HIF06aWWXCbT0 +USq95oKStk3bCFvnDyUGFcy2i72mTkyaGyscol9vZeEQAFjLVn3vvXCW7iIaQdFSpfPBD BnP8nDKBWNBp4lg3T++s07+/VkhsCfDCM+oLCTO211JEDncImFRmKNf1qrRnFghxgSon/t QdtNRsW+4/NvmM81NlNZlCHSj+RMqhMzu7JIO2rX0Hyr8AX7+e1Op+izfMiOgI4QcxjbHK vWcM2JBEOOCPnGleR7XCvZX1gF114jgScsfKua8aL2qitArsNoSyJfdVsBL4Sw== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1706028437; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=khMougoG0mvpU1Mds2+gCdLAlfzbFK/BUtDBN3tuvqo=; b=IYABCsLSREXQ5FfgJQ4fye4JG2wKe+r0VkozoE+L4pxCtwZuezSYuejwBoBbCyhIxuyyGm hzGgIBDrW6/4QfCA== To: linux-kernel@vger.kernel.org Cc: Thomas Gleixner , Frederic Weisbecker , Ingo Molnar , John Stultz , Stephen Boyd , Jonathan Corbet , Clemens Ladisch , linux-doc@vger.kernel.org, Anna-Maria Behnsen Subject: [PATCH 5/8] jiffies: Transform comment about time_* functions into DOC block Date: Tue, 23 Jan 2024 17:46:59 +0100 Message-Id: <20240123164702.55612-6-anna-maria@linutronix.de> In-Reply-To: <20240123164702.55612-1-anna-maria@linutronix.de> References: <20240123164702.55612-1-anna-maria@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788903055614565257 X-GMAIL-MSGID: 1788903055614565257 This general note about time_* functions is also useful to be available in kernel documentation. Therefore transform it into a kernel-doc DOC block with proper formatting. Signed-off-by: Anna-Maria Behnsen --- include/linux/jiffies.h | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/include/linux/jiffies.h b/include/linux/jiffies.h index e0ae2a43e0eb..d9f1435a5a13 100644 --- a/include/linux/jiffies.h +++ b/include/linux/jiffies.h @@ -102,12 +102,15 @@ static inline u64 get_jiffies_64(void) } #endif -/* - * These inlines deal with timer wrapping correctly. You are - * strongly encouraged to use them: - * 1. Because people otherwise forget - * 2. Because if the timer wrap changes in future you won't have to - * alter your driver code. +/** + * DOC: General information about time_* inlines + * + * These inlines deal with timer wrapping correctly. You are strongly encouraged + * to use them: + * + * #. Because people otherwise forget + * #. Because if the timer wrap changes in future you won't have to alter your + * driver code. */ /** From patchwork Tue Jan 23 16:47:00 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anna-Maria Behnsen X-Patchwork-Id: 191071 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp466131dyi; Tue, 23 Jan 2024 08:54:11 -0800 (PST) X-Google-Smtp-Source: AGHT+IFlQMifbT1riynj4UUW2/+Yp/q4eHEy3/yqj0q2JDNa+nHPnuSdJmCb9coscLUtQVd/3R9L X-Received: by 2002:a17:907:d402:b0:a30:e093:70f9 with SMTP id vi2-20020a170907d40200b00a30e09370f9mr58705ejc.305.1706028851089; Tue, 23 Jan 2024 08:54:11 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706028851; cv=pass; d=google.com; s=arc-20160816; b=Y/tNMrlC3dJQ2G6NOXc1AV8MssBcXP8J/rCUtQpkCWb/UAsDz2n0G8QqcIJh11YOXH UJOBFOYStaRNkpE1cwH72zpTkOkw4fikqsq3c8p+FrM2INGtN0EcRfHBPbrT0cyNb+2F dlPyzZfc7Bp1sY3Ffdx8/2d+CzERzjSTEhvwnGSXwHYL30G3/OkYjbXaWso6XEVEBHmL LlkRVXKi/0EM64mXd6+1g5UBgi/Wd2Zvkf7FlMYsJ+A8Q6Im5aLMotDqJL7wcU05dYAF vaP0SyPr7HxHmRzgaRjVp5UVmZCqWVMHIUfICUCRb5Y7PbBEzZ0Kwpmi6B4EtDUmSDeq XAcQ== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:dkim-signature:dkim-signature:from; bh=pISPf/npImhbjYhJnYCx42aZMFasXDW5I0m3JI4CPiM=; fh=nOEvUOtvIydWxxQpRdVGTZdE7oDfSvGmdNyLCMjLbrA=; b=VZB3f4937UgQSEG9Vro6zQgWyg0E2BhFXU3EW3MKI929zIwsUTMuUOJKg1l8JlFowb CzdVUARXkcfidgL36YK5VYCNxgB584D25YEt97QDZ1xFo3qB9iJu/x8GHtD/WCtrWBb3 rU30Ok5a6DYqD2hhP5Cw9uf+0VHA3Q3ublzibNtlg9LOwKUywIZtgrodrXHlR2qF63YI q5/T44MHjceSGaLJUdY7NYgTaxkBcXa47DIDB61uMtDNXJpXQEKjy8LtWcKQ2gN0qZbD 1oOPmpZLmtqDW/WJmIDiv1OStg+UgRzjl4d1GJKeZewSQ6bMrf1rSQp3FwOfQwuEfxnX bBBw== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b="XkGu8/FQ"; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35707-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35707-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from am.mirrors.kernel.org (am.mirrors.kernel.org. [2604:1380:4601:e00::3]) by mx.google.com with ESMTPS id t1-20020a1709060c4100b00a26ed1ed306si11661702ejf.461.2024.01.23.08.54.10 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 08:54:11 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35707-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b="XkGu8/FQ"; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35707-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35707-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by am.mirrors.kernel.org (Postfix) with ESMTPS id 8CDF41F307A1 for ; Tue, 23 Jan 2024 16:54:10 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 1325D129A85; Tue, 23 Jan 2024 16:47:27 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="XkGu8/FQ"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="RxVJkuBH" 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 4CFDF82D62; Tue, 23 Jan 2024 16:47:21 +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=1706028443; cv=none; b=MKbMQd1Ij9cbpDV2UlPx2CzHCyRaW8CDtyDlZsD7v1z50lbRNwI1I3QpfiMOd2N1qT4S4TaGIf79j0/hCnpkRJ8LZyeanl5vRGJBlyaqVIL7PTNVwws+/lgfTTGeeZVRNgYYqMw0bjx2s/tXEPoSd5MJAE+7H3iLp9Og49USOT8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706028443; c=relaxed/simple; bh=hQbL/bTWo5b/f0fUHYOc6fJKjPDV7lRgpxdNJ+4o7iI=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=sMxFYNzYhggcTLOKodbhKnXMx8EfmvwZ19CPsvyGyMidUiy15Rcce1cTMZK7HzBQPItfwh340hsmMhIII2fwonbsgAFUFtPsWy7qGxcFenf0JOwWM5/OTgbgLkYQ0hMYbMN8vZTiI7l1fVUGqSzSrDsdWQna0YqFJDsBVwrPDoc= 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=XkGu8/FQ; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=RxVJkuBH; 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 From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1706028437; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=pISPf/npImhbjYhJnYCx42aZMFasXDW5I0m3JI4CPiM=; b=XkGu8/FQf/4pPZZTdEI2xfbNsNtmlFv2HJ8eXGczGkr8A/d7D9qjFnIsPRJv0GflZ1xImp ex7Ys39yxtHsxtD+b1yRfekzR2sXhOhjmkP7ZRc7b4AV04ON7gWDGpgbEdC0qS6l4wkHvA nIr6Krs1Zjg8gfAc+BVnQGKBep9ndYnIzVZ6a+OUro6ljY6kzmhF+i565FhRubLqzkm1VR K1TmOx4s6J/ND8Na961e82SNttCDtk8uyOFGcctVx5Ielnoh8EJ9MzWePosNw4p5BN7Z3d xgcS5r6yeV3mLHr0exYauwdnj9gQ5Xw4q20OavN+Xc/va9os8WtDxaDRsBdIcw== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1706028437; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=pISPf/npImhbjYhJnYCx42aZMFasXDW5I0m3JI4CPiM=; b=RxVJkuBH0lZE7LBg9cPxRbknZhFc/wp7Fa+ZPjMBU60tk45DrOcPu9QdVD5nq3tmgIPe2+ 4gnZbSclEBwzOWBg== To: linux-kernel@vger.kernel.org Cc: Thomas Gleixner , Frederic Weisbecker , Ingo Molnar , John Stultz , Stephen Boyd , Jonathan Corbet , Clemens Ladisch , linux-doc@vger.kernel.org, Anna-Maria Behnsen Subject: [PATCH 6/8] Documentation: Create a new folder for all timer internals Date: Tue, 23 Jan 2024 17:47:00 +0100 Message-Id: <20240123164702.55612-7-anna-maria@linutronix.de> In-Reply-To: <20240123164702.55612-1-anna-maria@linutronix.de> References: <20240123164702.55612-1-anna-maria@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788900908601866870 X-GMAIL-MSGID: 1788900908601866870 The structure of documentation changed. There is 'core-api' where also timer related documentation belongs to. But the timer related documentation (doesn't matter whether it is up to date or outdated) is still located in a separate folder with no relation to core-api. Create a new folder which is located below core-api and make it the new place for all timer related documentation. Instead of revisiting all files below the already existing timer folder right now, add a warning banner to the top of all those files. When it is ensured the content is up to date, they can be moved to the final destination. Signed-off-by: Anna-Maria Behnsen --- Documentation/core-api/index.rst | 1 + Documentation/core-api/timers/index.rst | 22 ++++++++++++++++++++++ Documentation/timers/highres.rst | 5 +++++ Documentation/timers/hpet.rst | 5 +++++ Documentation/timers/hrtimers.rst | 5 +++++ Documentation/timers/index.rst | 5 +++++ Documentation/timers/no_hz.rst | 4 ++++ Documentation/timers/timekeeping.rst | 5 +++++ Documentation/timers/timers-howto.rst | 5 +++++ 9 files changed, 57 insertions(+) create mode 100644 Documentation/core-api/timers/index.rst diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 7a3a08d81f11..5aac1bdc411e 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -128,6 +128,7 @@ Documents that don't fit elsewhere or which have yet to be categorized. librs netlink + timers/index .. only:: subproject and html diff --git a/Documentation/core-api/timers/index.rst b/Documentation/core-api/timers/index.rst new file mode 100644 index 000000000000..e0a985fe4f89 --- /dev/null +++ b/Documentation/core-api/timers/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====== +Timers +====== + +This is all timer core related documentation. It is split into two +sections. The first will provide all information for people who simply want +to use timers. The second contains all information which are required by +developers who want to dive deeper into the concepts and implementation of +the timer infrastructure. + +The documentation should cover all files, which are located below +kernel/timers/ and also the timer related includes. + +Information for Users +===================== + + + +Information about concepts and internals +======================================== diff --git a/Documentation/timers/highres.rst b/Documentation/timers/highres.rst index bde5eb7e5c9e..14bf4e680b59 100644 --- a/Documentation/timers/highres.rst +++ b/Documentation/timers/highres.rst @@ -2,6 +2,11 @@ High resolution timers and dynamic ticks design notes ===================================================== +.. warning:: Documents in this folder might be outdated, as they haven't + been revisited for a longer time. Up to date documentation is + located in the core-api documentation: + :doc:`../core-api/timers/index` + Further information can be found in the paper of the OLS 2006 talk "hrtimers and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can be found on the OLS website: diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst index c9d05d3caaca..1459555048d9 100644 --- a/Documentation/timers/hpet.rst +++ b/Documentation/timers/hpet.rst @@ -2,6 +2,11 @@ High Precision Event Timer Driver for Linux =========================================== +.. warning:: Documents in this folder might be outdated, as they haven't + been revisited for a longer time. Up to date documentation is + located in the core-api documentation: + :doc:`../core-api/timers/index` + The High Precision Event Timer (HPET) hardware follows a specification by Intel and Microsoft, revision 1. diff --git a/Documentation/timers/hrtimers.rst b/Documentation/timers/hrtimers.rst index f88ff8bae89c..ce8a7b5c1387 100644 --- a/Documentation/timers/hrtimers.rst +++ b/Documentation/timers/hrtimers.rst @@ -2,6 +2,11 @@ hrtimers - subsystem for high-resolution kernel timers ====================================================== +.. warning:: Documents in this folder might be outdated, as they haven't + been revisited for a longer time. Up to date documentation is + located in the core-api documentation: + :doc:`../core-api/timers/index` + This patch introduces a new subsystem for high-resolution kernel timers. One might ask the question: we already have a timer subsystem diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst index 983f91f8f023..f99b26430a1d 100644 --- a/Documentation/timers/index.rst +++ b/Documentation/timers/index.rst @@ -4,6 +4,11 @@ Timers ====== +.. warning:: Documents in this folder might be outdated, as they haven't + been revisited for a longer time. Up to date documentation is + located in the core-api documentation: + :doc:`../core-api/timers/index` + .. toctree:: :maxdepth: 1 diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst index f8786be15183..04cb41c53eb7 100644 --- a/Documentation/timers/no_hz.rst +++ b/Documentation/timers/no_hz.rst @@ -2,6 +2,10 @@ NO_HZ: Reducing Scheduling-Clock Ticks ====================================== +.. warning:: Documents in this folder might be outdated, as they haven't + been revisited for a longer time. Up to date documentation is + located in the core-api documentation: + :doc:`../core-api/timers/index` This document describes Kconfig options and boot parameters that can reduce the number of scheduling-clock interrupts, thereby improving energy diff --git a/Documentation/timers/timekeeping.rst b/Documentation/timers/timekeeping.rst index f83e98852e2c..36d02d4fc085 100644 --- a/Documentation/timers/timekeeping.rst +++ b/Documentation/timers/timekeeping.rst @@ -2,6 +2,11 @@ Clock sources, Clock events, sched_clock() and delay timers =========================================================== +.. warning:: Documents in this folder might be outdated, as they haven't + been revisited for a longer time. Up to date documentation is + located in the core-api documentation: + :doc:`../core-api/timers/index` + This document tries to briefly explain some basic kernel timekeeping abstractions. It partly pertains to the drivers usually found in drivers/clocksource in the kernel tree, but the code may be spread out diff --git a/Documentation/timers/timers-howto.rst b/Documentation/timers/timers-howto.rst index 5c169e3d29a8..bdf34453339a 100644 --- a/Documentation/timers/timers-howto.rst +++ b/Documentation/timers/timers-howto.rst @@ -2,6 +2,11 @@ delays - Information on the various kernel delay / sleep mechanisms =================================================================== +.. warning:: Documents in this folder might be outdated, as they haven't + been revisited for a longer time. Up to date documentation is + located in the core-api documentation: + :doc:`../core-api/timers/index` + This document seeks to answer the common question: "What is the RightWay (TM) to insert a delay?" From patchwork Tue Jan 23 16:47:01 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anna-Maria Behnsen X-Patchwork-Id: 191072 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp466141dyi; Tue, 23 Jan 2024 08:54:12 -0800 (PST) X-Google-Smtp-Source: AGHT+IH5gILDST09oRm3GTOJJ23Dv3nfnT1sCqcNVWS9B1XzbBazExPj01pDsZKMiYK7/fLwpmIC X-Received: by 2002:a17:906:f354:b0:a30:80a5:e3eb with SMTP id hg20-20020a170906f35400b00a3080a5e3ebmr70603ejb.101.1706028851775; Tue, 23 Jan 2024 08:54:11 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706028851; cv=pass; d=google.com; s=arc-20160816; b=ZtyLgHnduLOarZybXcKgI0FZdkUPPM22aDTd7p/Il1we1RY6GxqE5aFk4+/GIElKyh oRdPtBBtrRb5IFJtdHEfGfOR1vuA5FB7TVRPRFqJymIzMldaLnv52ndeDseHqm7z+OpQ L8eTNK4/ul8W6eJDuAONsF1TFk2aMEvEkDu+xVFZPRB62twrrLCeeBJ3EtsAma+yjFBR q3OOGfmvgDegF5dpzG1QBNQbfsGcUn6XeIkjwhqHvoI3RxWH1kMdFJ2qpiRY7pTaJCMf E8Y2qBpAE8QA49xsvhi8doNCZycWMid3Ve06ZCQpX3jMWn6ba9WiHOjmBwIN8VTbjuw1 jKmA== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:dkim-signature:dkim-signature:from; bh=v56TOhPHDVLk12cYFc3wY5Njq/3+mXzyMEHeyZ6UrJY=; fh=nOEvUOtvIydWxxQpRdVGTZdE7oDfSvGmdNyLCMjLbrA=; b=nnvgT+HVELP1ObHixCpiljN33Tcr636F7NnNSIageX4+BHNUbwsj0HEGevOJjvRQ7p qXem3VOOfkvVM87sMYqyRDOIZNkWx9V2Uzn+TG/ImyKTbz7GdlvorQK9/ql+f9OVl7fh WC5Foewjq2OhoZT1+hDtzXlz3TsP+cTkJMD0xm6xZj+HVhIg5yT4UbhduWG/Utb77Ma+ nhI/yBRYWAgCZ6UQmSG+ikf+Q3ZnKEj0NBdgu9TgJcqAes6Zj2+5CCEMYbvBK63osHNh lQ0iKyDxSQDx2825KT40ODKoJCTtg2QffyENYrMB8TIktkswmrUGJjTdytOnOFWUXk2U dUjg== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b="erTxn/UG"; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35708-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35708-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from am.mirrors.kernel.org (am.mirrors.kernel.org. [2604:1380:4601:e00::3]) by mx.google.com with ESMTPS id r24-20020a170906549800b00a26eea5291bsi11620890ejo.523.2024.01.23.08.54.11 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 08:54:11 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35708-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b="erTxn/UG"; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35708-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35708-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by am.mirrors.kernel.org (Postfix) with ESMTPS id 3DF701F3077F for ; Tue, 23 Jan 2024 16:54:11 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 23CF4129A86; Tue, 23 Jan 2024 16:47:27 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="erTxn/UG"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="/45NMdQW" 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 B002B82D73; Tue, 23 Jan 2024 16:47:21 +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=1706028443; cv=none; b=UNNB/CMVSMDN1gfCBFMZul782d/JEQVQ8SwWVngRl4j+JNfGIp4FtN5C76nbxmkob77U85Pv48qL8gxdcgwmRVad6yghSPO0EsGKX6riEJXBR1LhLuHWS2QlSrHzW7QuPER4JRpQ5X/Sj0yFjOVxEpgkUn8fa9gka5I59AC3RX4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706028443; c=relaxed/simple; bh=R2XU6nCysWoBfcCiBV9o40hPodsH/YkZepizm38mysc=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=hHKRo4iLU/opB7qqiDA342ONqsboX4rIHxsbMOI+gJ71B3AkoJ5ZuWL8iETnqU51OfacnXcVBXQ/DPFLu9gE/zRTVLtclPGinOlTN4m5uY1zyVXcX4GIB9byr5USDr93obGrpJDmP69OxiymD+ZlhgYlAPZye0+mdd5kjT2nSdM= 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=erTxn/UG; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=/45NMdQW; 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 From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1706028438; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=v56TOhPHDVLk12cYFc3wY5Njq/3+mXzyMEHeyZ6UrJY=; b=erTxn/UGENeyYM4crwXW7kYiH6Bnlp/9P41fcyVabv2aEcL3J+c3vUVgAK3KQySDiXHDLm 9yBcvlqaj94J6LWhEsPVyqCGukoE9kTjte5Z6vx3KOnAPz4yEbWBaGxUB221Si89lWQFNC KyrRnav7aMoidAwMUMqBHfiRyLSayKEZ6SrpfZPpz9/5eOMNT2M6upLJuyLEHMp1dippy+ TLox5h9x+1+yNilCNdQVeObe5bIE3Wx32PLVrMXL6ELBcUhbyyjcHe3t3oKALkcRWQ1oTD Lm1LVOGRSYseC9muz6nL20g187W23gsiExcNhOrrcq7XfiDeyf1Y2ECkEFxNkA== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1706028438; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=v56TOhPHDVLk12cYFc3wY5Njq/3+mXzyMEHeyZ6UrJY=; b=/45NMdQWFfEH1hTiyMswsXkyzw5jlZA1lD+Mg2yh8Q4sdE8AwXuNxkPuwj/kR5O2TDm1OI hnNt+DFzLGsoS2CA== To: linux-kernel@vger.kernel.org Cc: Thomas Gleixner , Frederic Weisbecker , Ingo Molnar , John Stultz , Stephen Boyd , Jonathan Corbet , Clemens Ladisch , linux-doc@vger.kernel.org, Anna-Maria Behnsen Subject: [PATCH 7/8] Documentation: Move "core core" api into a separate file Date: Tue, 23 Jan 2024 17:47:01 +0100 Message-Id: <20240123164702.55612-8-anna-maria@linutronix.de> In-Reply-To: <20240123164702.55612-1-anna-maria@linutronix.de> References: <20240123164702.55612-1-anna-maria@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788900909297708791 X-GMAIL-MSGID: 1788900909297708791 Some "core core" API as timer API is documented in driver-api. This is definitely the wrong place. As the subject description in core-api/index.rst mentions, is also core-api/kernel-api.rst a collection of leftovers. Therefore create a new core-api file and start to integrate timer api. As this contains a lot of functions, it is separated into a timer specific API file. Signed-off-by: Anna-Maria Behnsen --- Documentation/core-api/core-api.rst | 14 ++++++ Documentation/core-api/index.rst | 4 +- Documentation/core-api/kernel-api.rst | 12 +++-- Documentation/core-api/timers/api.rst | 63 +++++++++++++++++++++++++ Documentation/core-api/timers/index.rst | 4 ++ Documentation/driver-api/basics.rst | 24 ---------- 6 files changed, 93 insertions(+), 28 deletions(-) create mode 100644 Documentation/core-api/core-api.rst create mode 100644 Documentation/core-api/timers/api.rst diff --git a/Documentation/core-api/core-api.rst b/Documentation/core-api/core-api.rst new file mode 100644 index 000000000000..4fe00d084dc7 --- /dev/null +++ b/Documentation/core-api/core-api.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +The Linux Kernel Core API +========================= + +.. note:: Some Core API is still documented in :doc:`../driver-api/basic` and + needs to be moved here. As this document will be huge when it contains + the whole API, split the API for a special part into a separate file. + +Timers +====== + +For timer related API, please refere to :doc:`timers/api`. diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 5aac1bdc411e..ed239269253a 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -11,12 +11,14 @@ Core utilities This section has general and "core core" documentation. The first is a massive grab-bag of kerneldoc info left over from the docbook days; it should really be broken up someday when somebody finds the energy to do -it. +it. :doc:`core-api` is a first step to clean things up. It should only +contain "core core" API documentation. .. toctree:: :maxdepth: 1 kernel-api + core-api workqueue watch_queue printk-basics diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index ae92a2571388..13b808084881 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -1,7 +1,13 @@ -==================== -The Linux Kernel API -==================== +=========================== +The Linux Kernel (Misc) API +=========================== + +.. warning:: + This API description is not the "core core" API description. It can be + found in :doc:`core-api`. + This document contains a collection of kernel related APIs and needs to + be split and sorted when there is time. List Management Functions ========================= diff --git a/Documentation/core-api/timers/api.rst b/Documentation/core-api/timers/api.rst new file mode 100644 index 000000000000..4a84714d3933 --- /dev/null +++ b/Documentation/core-api/timers/api.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +Timers API +========== + +Working with jiffies +==================== + +.. kernel-doc:: include/linux/jiffies.h + :identifiers: get_jiffies_64 jiffies_to_nsecs msecs_to_jiffies usecs_to_jiffies + +.. kernel-doc:: kernel/time/time.c + :no-identifiers: mktime64 set_normalized_timespec64 ns_to_timespec64 get_timespec64 put_timespec64 get_old_timespec32 put_old_timespec32 get_itimerspec64 put_itimerspec64 get_old_itimerspec32 put_old_itimerspec32 + +.. kernel-doc:: kernel/time/timer.c + :identifiers: __round_jiffies __round_jiffies_relative round_jiffies round_jiffies_relative __round_jiffies_up __round_jiffies_up_relative round_jiffies_up round_jiffies_up_relative + +Jiffie based time comparison helpers +==================================== + +.. kernel-doc:: include/linux/jiffies.h + :doc: General information about time_* inlines + +.. kernel-doc:: include/linux/jiffies.h + :no-identifiers: time_comparision_disclaimer get_jiffies_64 jiffies_to_nsecs msecs_to_jiffies usecs_to_jiffies + + +Timespec related functions +========================== + +.. kernel-doc:: kernel/time/time.c + :identifiers: mktime64 set_normalized_timespec64 ns_to_timespec64 get_timespec64 put_timespec64 get_old_timespec32 put_old_timespec32 get_itimerspec64 put_itimerspec64 get_old_itimerspec32 put_old_itimerspec32 + + +Handle timer list timers +======================== + +.. kernel-doc:: kernel/time/timer.c + :identifiers: init_timer_key mod_timer_pending mod_timer timer_reduce add_timer add_timer_local add_timer_global add_timer_on timer_delete timer_shutdown try_to_del_timer_sync + + +Timeout and sleeping +==================== + +.. kernel-doc:: kernel/time/timer.c + :identifiers: schedule_timeout msleep msleep_interruptible usleep_range_state + +ktime_t operations +================== + +.. kernel-doc:: include/linux/ktime.h + :internal: + + +High-Resolution Timers +====================== + +.. kernel-doc:: include/linux/hrtimer.h + :internal: + +.. kernel-doc:: kernel/time/hrtimer.c + :export: diff --git a/Documentation/core-api/timers/index.rst b/Documentation/core-api/timers/index.rst index e0a985fe4f89..2f99fc9d4f44 100644 --- a/Documentation/core-api/timers/index.rst +++ b/Documentation/core-api/timers/index.rst @@ -16,6 +16,10 @@ kernel/timers/ and also the timer related includes. Information for Users ===================== +.. toctree:: + :maxdepth: 1 + + api Information about concepts and internals diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index d78b7c328ff7..0e352682bbc7 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -33,30 +33,6 @@ Delaying and scheduling routines .. kernel-doc:: include/linux/completion.h :internal: -Time and timer routines ------------------------ - -.. kernel-doc:: include/linux/jiffies.h - :internal: - -.. kernel-doc:: kernel/time/time.c - :export: - -.. kernel-doc:: kernel/time/timer.c - :export: - -High-resolution timers ----------------------- - -.. kernel-doc:: include/linux/ktime.h - :internal: - -.. kernel-doc:: include/linux/hrtimer.h - :internal: - -.. kernel-doc:: kernel/time/hrtimer.c - :export: - Wait queues and Wake events --------------------------- From patchwork Tue Jan 23 16:47:02 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anna-Maria Behnsen X-Patchwork-Id: 191073 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp466248dyi; Tue, 23 Jan 2024 08:54:25 -0800 (PST) X-Google-Smtp-Source: AGHT+IGOekZFLVCGCzUY0c/j8HBdPJE/eD7YhUFAP7Z0yMzrl6YL3dOX89GOmbVCxLGKf6QL+Cgs X-Received: by 2002:a50:ed02:0:b0:55c:93c1:4a4d with SMTP id j2-20020a50ed02000000b0055c93c14a4dmr564641eds.7.1706028865065; Tue, 23 Jan 2024 08:54:25 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706028865; cv=pass; d=google.com; s=arc-20160816; b=K5LnW6bbSrU+7qhoM4LnpAWslUBYY5g5o5QISZ0F35TTE5ZhcE1Fn57wUzROIQ1WVw KzildCBnEFJZvtqafLOdLNVly22cjVY3viJbQIK6zVGEY3/ZugWmkaN1gef8I4cfS32p LahtFxp95qQnbL3BDzpbkh80n5a7LShUjBNvaLa+WhUPhYOSBlFBSglJlWuKPidTMs/D CIV29GENgknBG6vz1aHIjIbrPvBm4Ikzgx9zlI2uM7EsrlLkWZKFFb19nDcDZXUFos8G vwliLZPOWtYIBYdhdnxbhXs9ggJTs4/EvRqCe5RmB8tlygsJ0b4Y/SozHdurYeNE2Xbr 8+Ew== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:dkim-signature:dkim-signature:from; bh=C/rFGi6KLFOmslk7r4TJ7Hb4p+h1puESpm2cPfdBJRs=; fh=nOEvUOtvIydWxxQpRdVGTZdE7oDfSvGmdNyLCMjLbrA=; b=r/gek+E3dCRH/82lZcCG9URr6XUtRmQs1lomTP3ZsLEjt1TVta7VJb4cNaUbY3zpcG 9qZbX6ez3Z1qgzkmatxWEm6e5o2OznyKG4MwXt7m8acvESlpMol/dGFMk0IAC+b6gbrY rP+EbZ6uUY6phYpc43AW+sUQnxM5K16n2COS4lkRM1H2SlvkEGJC2NWroFJTr3GiW0Tg vJgy2btaVcCExCoQrIp2b3mlq//lTGCt9cD4JjVxB388DeVcHRLDgsLOFLvdeVlZ9eUH ThKQXG/HJrJCzUyULiOV9d5OCW/UrkoacPy7HvStN6Y66dwWrt37gTsT/WCv/GyBoDQM Shdw== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=aZcvd1hX; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35709-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35709-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from am.mirrors.kernel.org (am.mirrors.kernel.org. [2604:1380:4601:e00::3]) by mx.google.com with ESMTPS id a5-20020a509e85000000b0055c153341f8si3219862edf.271.2024.01.23.08.54.24 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 08:54:25 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35709-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=aZcvd1hX; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e; arc=pass (i=1 spf=pass spfdomain=linutronix.de dkim=pass dkdomain=linutronix.de dmarc=pass fromdomain=linutronix.de); spf=pass (google.com: domain of linux-kernel+bounces-35709-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35709-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by am.mirrors.kernel.org (Postfix) with ESMTPS id 7D8A31F30564 for ; Tue, 23 Jan 2024 16:54:24 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 4BE47129A9D; Tue, 23 Jan 2024 16:47:29 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="aZcvd1hX"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="UwkqvgMn" 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 7918882D6B; Tue, 23 Jan 2024 16:47:21 +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=1706028444; cv=none; b=e+Qz1ZmpPRbO9opTOAhk5hmT3brDUjzaOmb6gbugbPPOe0Fjyr58eZkcCjExfN/ELNF9Bk6zeosKar0CY38sroqOlqRVSubLC/G/KtNkhZXYJ/V0md/GdWjGSyKD4oGSot0HFRZYqy6J6t4LWWqc4zZAodgti06cPDszJSw7ET8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706028444; c=relaxed/simple; bh=3LNhHfci3f3fHL8QZF2f9WWX+aZxoCrrzCZ6No3k10I=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=BHlX4DyeDcI0YZzndulW7D5/cbH7boz0cs+RdQ0MAbnilEetdHPJ4DsHJZ6tllBvejJUSunb7obqrB0G/vcMtk/FhLo5TsAqRvmrQxgLVpjY23N+a37Y5R0FdREJjqBWvM+5zW+Hqss6Yu3d+EXXJdDyHho+3VEm51NI6vQyY/U= 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=aZcvd1hX; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=UwkqvgMn; 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 From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1706028438; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=C/rFGi6KLFOmslk7r4TJ7Hb4p+h1puESpm2cPfdBJRs=; b=aZcvd1hXwhFzktglpojoAQb5XGn4sr52kAr0yITbqWCVm1PQh6tjymxtET+Fmo6MzTFuV9 spL4IHHd5m8kRwkGu/Ywdn0uS8LPNtRle5sh2ChUCt08MJASKLYJx1+PfQtuUDXqoyTBVs mX3SpWSQiqtIHDRAEBOgERL14UedN7HyAI3GKVPwNXjDSA9TWCErqSQdiPd1LG3k0x7YyY 1WPn8C1OrPWDoQUJyUkJUC06NRRbfuz0KdESgWVSOT8o9IPlO7K6i1SoY+MKWIUBq9E8mq qVABTrZIOxf1Zt2H+k2G7+AKu/XdnuYiNyd9rZB314YbqGUOaSmArKVYwqJRdw== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1706028438; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=C/rFGi6KLFOmslk7r4TJ7Hb4p+h1puESpm2cPfdBJRs=; b=UwkqvgMnUEfksfbPBXe4jTkYP4krx6oXWr4h1yuDWuoQwe6dIrph6DXXIKPyQsIAavQnnN XmR/hmdanu4J0CBA== To: linux-kernel@vger.kernel.org Cc: Thomas Gleixner , Frederic Weisbecker , Ingo Molnar , John Stultz , Stephen Boyd , Jonathan Corbet , Clemens Ladisch , linux-doc@vger.kernel.org, Anna-Maria Behnsen Subject: [PATCH 8/8] timers: Add timer wheel documentation Date: Tue, 23 Jan 2024 17:47:02 +0100 Message-Id: <20240123164702.55612-9-anna-maria@linutronix.de> In-Reply-To: <20240123164702.55612-1-anna-maria@linutronix.de> References: <20240123164702.55612-1-anna-maria@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788900923412882769 X-GMAIL-MSGID: 1788900923412882769 There is a lot of documentation inside the timer code. But this documentation is not exported into the official kernel documentation. Rework the comments to follow the rules of kernel-doc and rst. Create a new documentation file about the timer wheel concept and another file which contains information for the user of timer list timers. Signed-off-by: Anna-Maria Behnsen --- Documentation/core-api/timers/index.rst | 6 + .../core-api/timers/timer-list-timers.rst | 13 ++ Documentation/core-api/timers/timer-wheel.rst | 38 +++++ include/linux/timer.h | 15 +- kernel/time/timer.c | 139 ++++++++++-------- 5 files changed, 142 insertions(+), 69 deletions(-) create mode 100644 Documentation/core-api/timers/timer-list-timers.rst create mode 100644 Documentation/core-api/timers/timer-wheel.rst diff --git a/Documentation/core-api/timers/index.rst b/Documentation/core-api/timers/index.rst index 2f99fc9d4f44..9f8f6afac859 100644 --- a/Documentation/core-api/timers/index.rst +++ b/Documentation/core-api/timers/index.rst @@ -20,7 +20,13 @@ Information for Users :maxdepth: 1 api + timer-list-timers Information about concepts and internals ======================================== + +.. toctree:: + :maxdepth: 1 + + timer-wheel diff --git a/Documentation/core-api/timers/timer-list-timers.rst b/Documentation/core-api/timers/timer-list-timers.rst new file mode 100644 index 000000000000..ba2d3841098c --- /dev/null +++ b/Documentation/core-api/timers/timer-list-timers.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +Timer list timers - How to use them +=================================== + +Timer flags +=========== + +A timer list timer could have specified one of the following timer flags: + +.. kernel-doc:: include/linux/timer.h + :doc: Flags of the timer list timers diff --git a/Documentation/core-api/timers/timer-wheel.rst b/Documentation/core-api/timers/timer-wheel.rst new file mode 100644 index 000000000000..f0469445d2c6 --- /dev/null +++ b/Documentation/core-api/timers/timer-wheel.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================================================== +Timer wheel and timer list timers - Implementation Details +=================================================================== + +The timer wheel is the infrastructure to handle all timer list +timers. Originally it was a cascading wheel and was reworked as a +non-cascading timer wheel back in 2016 with commit 500462a9de65 ("timers: +Switch to a non-cascading wheel"). + +Concept +======= + +.. kernel-doc:: kernel/time/timer.c + :doc: Concept of the timer wheel + + +Locking of timer bases +====================== + +.. kernel-doc:: kernel/time/timer.c + :doc: Timer bases and hashed locking + + +NOHZ and timer bases +==================== + +.. kernel-doc:: kernel/time/timer.c + :doc: NOHZ and timer bases + + +How to use timer list timers +============================ + +See also the users guide for how to use timer list timers. Details which are +important for the user are not listed here a second time to prevent duplicated +information (:doc:`timer-list-timers`). diff --git a/include/linux/timer.h b/include/linux/timer.h index f18a2f1eb79e..b1ae19df17e1 100644 --- a/include/linux/timer.h +++ b/include/linux/timer.h @@ -23,6 +23,8 @@ #endif /** + * DOC: Flags of the timer list timers + * * @TIMER_DEFERRABLE: A deferrable timer will work normally when the * system is busy, but will not cause a CPU to come out of idle just * to service it; instead, the timer will be serviced when the CPU @@ -40,12 +42,13 @@ * placement heuristics (like, NOHZ) and will always expire on the CPU * on which the timer was enqueued. * - * Note: Because enqueuing of timers can migrate the timer from one - * CPU to another, pinned timers are not guaranteed to stay on the - * initialy selected CPU. They move to the CPU on which the enqueue - * function is invoked via mod_timer() or add_timer(). If the timer - * should be placed on a particular CPU, then add_timer_on() has to be - * used. + * .. note:: + * Because enqueuing of timers can migrate the timer from one + * CPU to another, pinned timers are not guaranteed to stay on the + * initialy selected CPU. They move to the CPU on which the enqueue + * function is invoked via mod_timer() or add_timer(). If the timer + * should be placed on a particular CPU, then add_timer_on() has to be + * used. */ #define TIMER_CPUMASK 0x0003FFFF #define TIMER_MIGRATING 0x00040000 diff --git a/kernel/time/timer.c b/kernel/time/timer.c index d44dba1d4af0..c001d8934172 100644 --- a/kernel/time/timer.c +++ b/kernel/time/timer.c @@ -61,13 +61,15 @@ __visible u64 jiffies_64 __cacheline_aligned_in_smp = INITIAL_JIFFIES; EXPORT_SYMBOL(jiffies_64); -/* - * The timer wheel has LVL_DEPTH array levels. Each level provides an array of - * LVL_SIZE buckets. Each level is driven by its own clock and therefor each - * level has a different granularity. +/** + * DOC: Concept of the timer wheel + * + * The timer wheel has ``LVL_DEPTH`` array levels. Each level provides an array + * of ``LVL_SIZE`` buckets. Each level is driven by its own clock and therefor + * each level has a different granularity. * - * The level granularity is: LVL_CLK_DIV ^ lvl - * The level clock frequency is: HZ / (LVL_CLK_DIV ^ level) + * * The level granularity is: ``LVL_CLK_DIV ^ lvl`` + * * The level clock frequency is: ``HZ / (LVL_CLK_DIV ^ level)`` * * The array level of a newly armed timer depends on the relative expiry * time. The farther the expiry time is away the higher the array level and @@ -99,54 +101,54 @@ EXPORT_SYMBOL(jiffies_64); * The currently chosen array constants values are a good compromise between * array size and granularity. * - * This results in the following granularity and range levels: - * - * HZ 1000 steps - * Level Offset Granularity Range - * 0 0 1 ms 0 ms - 63 ms - * 1 64 8 ms 64 ms - 511 ms - * 2 128 64 ms 512 ms - 4095 ms (512ms - ~4s) - * 3 192 512 ms 4096 ms - 32767 ms (~4s - ~32s) - * 4 256 4096 ms (~4s) 32768 ms - 262143 ms (~32s - ~4m) - * 5 320 32768 ms (~32s) 262144 ms - 2097151 ms (~4m - ~34m) - * 6 384 262144 ms (~4m) 2097152 ms - 16777215 ms (~34m - ~4h) - * 7 448 2097152 ms (~34m) 16777216 ms - 134217727 ms (~4h - ~1d) - * 8 512 16777216 ms (~4h) 134217728 ms - 1073741822 ms (~1d - ~12d) - * - * HZ 300 - * Level Offset Granularity Range - * 0 0 3 ms 0 ms - 210 ms - * 1 64 26 ms 213 ms - 1703 ms (213ms - ~1s) - * 2 128 213 ms 1706 ms - 13650 ms (~1s - ~13s) - * 3 192 1706 ms (~1s) 13653 ms - 109223 ms (~13s - ~1m) - * 4 256 13653 ms (~13s) 109226 ms - 873810 ms (~1m - ~14m) - * 5 320 109226 ms (~1m) 873813 ms - 6990503 ms (~14m - ~1h) - * 6 384 873813 ms (~14m) 6990506 ms - 55924050 ms (~1h - ~15h) - * 7 448 6990506 ms (~1h) 55924053 ms - 447392423 ms (~15h - ~5d) - * 8 512 55924053 ms (~15h) 447392426 ms - 3579139406 ms (~5d - ~41d) - * - * HZ 250 - * Level Offset Granularity Range - * 0 0 4 ms 0 ms - 255 ms - * 1 64 32 ms 256 ms - 2047 ms (256ms - ~2s) - * 2 128 256 ms 2048 ms - 16383 ms (~2s - ~16s) - * 3 192 2048 ms (~2s) 16384 ms - 131071 ms (~16s - ~2m) - * 4 256 16384 ms (~16s) 131072 ms - 1048575 ms (~2m - ~17m) - * 5 320 131072 ms (~2m) 1048576 ms - 8388607 ms (~17m - ~2h) - * 6 384 1048576 ms (~17m) 8388608 ms - 67108863 ms (~2h - ~18h) - * 7 448 8388608 ms (~2h) 67108864 ms - 536870911 ms (~18h - ~6d) - * 8 512 67108864 ms (~18h) 536870912 ms - 4294967288 ms (~6d - ~49d) - * - * HZ 100 - * Level Offset Granularity Range - * 0 0 10 ms 0 ms - 630 ms - * 1 64 80 ms 640 ms - 5110 ms (640ms - ~5s) - * 2 128 640 ms 5120 ms - 40950 ms (~5s - ~40s) - * 3 192 5120 ms (~5s) 40960 ms - 327670 ms (~40s - ~5m) - * 4 256 40960 ms (~40s) 327680 ms - 2621430 ms (~5m - ~43m) - * 5 320 327680 ms (~5m) 2621440 ms - 20971510 ms (~43m - ~5h) - * 6 384 2621440 ms (~43m) 20971520 ms - 167772150 ms (~5h - ~1d) - * 7 448 20971520 ms (~5h) 167772160 ms - 1342177270 ms (~1d - ~15d) + * This results in the following granularity and range levels:: + * + * HZ 1000 steps + * Level Offset Granularity Range + * 0 0 1 ms 0 ms - 63 ms + * 1 64 8 ms 64 ms - 511 ms + * 2 128 64 ms 512 ms - 4095 ms (512ms - ~4s) + * 3 192 512 ms 4096 ms - 32767 ms (~4s - ~32s) + * 4 256 4096 ms (~4s) 32768 ms - 262143 ms (~32s - ~4m) + * 5 320 32768 ms (~32s) 262144 ms - 2097151 ms (~4m - ~34m) + * 6 384 262144 ms (~4m) 2097152 ms - 16777215 ms (~34m - ~4h) + * 7 448 2097152 ms (~34m) 16777216 ms - 134217727 ms (~4h - ~1d) + * 8 512 16777216 ms (~4h) 134217728 ms - 1073741822 ms (~1d - ~12d) + * + * HZ 300 + * Level Offset Granularity Range + * 0 0 3 ms 0 ms - 210 ms + * 1 64 26 ms 213 ms - 1703 ms (213ms - ~1s) + * 2 128 213 ms 1706 ms - 13650 ms (~1s - ~13s) + * 3 192 1706 ms (~1s) 13653 ms - 109223 ms (~13s - ~1m) + * 4 256 13653 ms (~13s) 109226 ms - 873810 ms (~1m - ~14m) + * 5 320 109226 ms (~1m) 873813 ms - 6990503 ms (~14m - ~1h) + * 6 384 873813 ms (~14m) 6990506 ms - 55924050 ms (~1h - ~15h) + * 7 448 6990506 ms (~1h) 55924053 ms - 447392423 ms (~15h - ~5d) + * 8 512 55924053 ms (~15h) 447392426 ms - 3579139406 ms (~5d - ~41d) + * + * HZ 250 + * Level Offset Granularity Range + * 0 0 4 ms 0 ms - 255 ms + * 1 64 32 ms 256 ms - 2047 ms (256ms - ~2s) + * 2 128 256 ms 2048 ms - 16383 ms (~2s - ~16s) + * 3 192 2048 ms (~2s) 16384 ms - 131071 ms (~16s - ~2m) + * 4 256 16384 ms (~16s) 131072 ms - 1048575 ms (~2m - ~17m) + * 5 320 131072 ms (~2m) 1048576 ms - 8388607 ms (~17m - ~2h) + * 6 384 1048576 ms (~17m) 8388608 ms - 67108863 ms (~2h - ~18h) + * 7 448 8388608 ms (~2h) 67108864 ms - 536870911 ms (~18h - ~6d) + * 8 512 67108864 ms (~18h) 536870912 ms - 4294967288 ms (~6d - ~49d) + * + * HZ 100 + * Level Offset Granularity Range + * 0 0 10 ms 0 ms - 630 ms + * 1 64 80 ms 640 ms - 5110 ms (640ms - ~5s) + * 2 128 640 ms 5120 ms - 40950 ms (~5s - ~40s) + * 3 192 5120 ms (~5s) 40960 ms - 327670 ms (~40s - ~5m) + * 4 256 40960 ms (~40s) 327680 ms - 2621430 ms (~5m - ~43m) + * 5 320 327680 ms (~5m) 2621440 ms - 20971510 ms (~43m - ~5h) + * 6 384 2621440 ms (~43m) 20971520 ms - 167772150 ms (~5h - ~1d) + * 7 448 20971520 ms (~5h) 167772160 ms - 1342177270 ms (~1d - ~15d) */ /* Clock divisor for the next level */ @@ -181,11 +183,20 @@ EXPORT_SYMBOL(jiffies_64); #define WHEEL_TIMEOUT_MAX (WHEEL_TIMEOUT_CUTOFF - LVL_GRAN(LVL_DEPTH - 1)) /* - * The resulting wheel size. If NOHZ is configured we allocate two - * wheels so we have a separate storage for the deferrable timers. + * The resulting wheel size. */ #define WHEEL_SIZE (LVL_SIZE * LVL_DEPTH) +/** + * DOC: NOHZ and timer bases + * + * If NOHZ is configured two timer bases are allocated to have a separate + * storage for deferrable timers: + * + * @BASE_STD: Contains are all non deferrable timers + * + * @BASE_DEF: Contains all deferrable timers (with ``TIMER_DEFERRABLE`` flag) + */ #ifdef CONFIG_NO_HZ_COMMON # define NR_BASES 2 # define BASE_STD 0 @@ -1013,16 +1024,18 @@ static inline void forward_timer_base(struct timer_base *base) __forward_timer_base(base, READ_ONCE(jiffies)); } -/* - * We are using hashed locking: Holding per_cpu(timer_bases[x]).lock means - * that all timers which are tied to this base are locked, and the base itself - * is locked too. +/** + * DOC: Timer bases and hashed locking + * + * For locking, hashed locking is used: Holding ``per_cpu(timer_bases[x]).lock`` + * means that all timers which are tied to this base are locked, and the base + * itself is locked too. * - * So __run_timers/migrate_timers can safely modify all timers which could + * So __run_timers()/migrate_timer_list() can safely modify all timers which could * be found in the base->vectors array. * - * When a timer is migrating then the TIMER_MIGRATING flag is set and we need - * to wait until the migration is done. + * When a timer is migrating then the ``TIMER_MIGRATING`` flag is set and it's + * required to wait before grabbing the lock, until the migration is done. */ static struct timer_base *lock_timer_base(struct timer_list *timer, unsigned long *flags)