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?"