Received-SPF: pass (google.com: domain of linux-kernel+bounces-35707-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
From: Anna-Maria Behnsen <anna-maria@linutronix.de>
To: linux-kernel@vger.kernel.org
Cc: Thomas Gleixner <tglx@linutronix.de>,
	Frederic Weisbecker <frederic@kernel.org>,
	Ingo Molnar <mingo@kernel.org>,
	John Stultz <jstultz@google.com>,
	Stephen Boyd <sboyd@kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Clemens Ladisch <clemens@ladisch.de>,
	linux-doc@vger.kernel.org,
	Anna-Maria Behnsen <anna-maria@linutronix.de>
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
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

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 <anna-maria@linutronix.de>
---
 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?"
 
-- 
2.39.2