[PATCH 0/8] timers and Documentation: Cleanup

[PATCH 0/8] timers and Documentation: Cleanup

[Anna-Maria Behnsen]

Hi,

initially the plan was to simply transform already existing comments in
timer code into kernel-doc DOC blocks, and reference them inside a *.rst
file. After trying to get familiar with the kernel documentation by reading
Documentation/doc-guide/* and have a look at the existing timer related
kernel documentation (which is below Documentation/timers and also below
Documentation/driver-api), the list what should/could be improved started
to grow.

So the aim of the queue is to do the first step for moving the timer
related stuff into the 'core-api book'. It contains the following changes:

- Do not expose internal hrtimer documentation (to prevent people of
  thinking they should use it somehow directly)

- Add missing documentation and update existing ones to be compatible with
  kernel-doc/rst

- Create a subfolder in core-api to make this the final destination of
  up-to-date timer documentation. Add banner to already existing timer
  related documentation to make sure they are really up to date before they
  are moved to the final destination.

- Move timer API from driver-api to core-api

- Add two files which make (in code hidden) timer documentation accessible
  via kernel documentation

Thanks,

	Anna-Maria


Anna-Maria Behnsen (8):
  include/hrtimers: Move hrtimer base related definitions into
    hrtimer_defs
  hrtimers: Update formatting of documentation
  tick/sched: Add function description for tick_nohz_next_event()
  timers: Add struct member description for timer_base
  jiffies: Transform comment about time_* functions into DOC block
  Documentation: Create a new folder for all timer internals
  Documentation: Move "core core" api into a separate file
  timers: Add timer wheel documentation

 Documentation/core-api/core-api.rst           |  14 ++
 Documentation/core-api/index.rst              |   5 +-
 Documentation/core-api/kernel-api.rst         |  12 +-
 Documentation/core-api/timers/api.rst         |  63 ++++++
 Documentation/core-api/timers/index.rst       |  32 +++
 .../core-api/timers/timer-list-timers.rst     |  13 ++
 Documentation/core-api/timers/timer-wheel.rst |  38 ++++
 Documentation/driver-api/basics.rst           |  24 ---
 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 +
 include/linux/hrtimer.h                       | 117 +----------
 include/linux/hrtimer_defs.h                  | 102 ++++++++++
 include/linux/jiffies.h                       |  15 +-
 include/linux/timer.h                         |  15 +-
 kernel/time/hrtimer.c                         |  18 +-
 kernel/time/tick-sched.c                      |  10 +
 kernel/time/timer.c                           | 184 ++++++++++++------
 22 files changed, 471 insertions(+), 225 deletions(-)
 create mode 100644 Documentation/core-api/core-api.rst
 create mode 100644 Documentation/core-api/timers/api.rst
 create mode 100644 Documentation/core-api/timers/index.rst
 create mode 100644 Documentation/core-api/timers/timer-list-timers.rst
 create mode 100644 Documentation/core-api/timers/timer-wheel.rst

-- 
2.39.2

[PATCH 1/8] include/hrtimers: Move hrtimer base related definitions into hrtimer_defs

[Anna-Maria Behnsen]

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 <anna-maria@linutronix.de>
---
 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 <linux/list.h>
 #include <linux/percpu-defs.h>
 #include <linux/rbtree.h>
-#include <linux/seqlock.h>
 #include <linux/timer.h>
 
-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 <linux/ktime.h>
+#include <linux/timerqueue.h>
+#include <linux/seqlock.h>
 
 #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
-- 
2.39.2

Re: [PATCH 1/8] include/hrtimers: Move hrtimer base related definitions into hrtimer_defs

[Thomas Gleixner]

On Tue, Jan 23 2024 at 17:46, Anna-Maria Behnsen wrote:
> 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.

Shouldn't this simply move to kernel/time/... ? Nothing outside of it
needs hrtimer_base

Thanks,

        tglx

Re: [PATCH 1/8] include/hrtimers: Move hrtimer base related definitions into hrtimer_defs

[Anna-Maria Behnsen]

Thomas Gleixner <tglx@linutronix.de> writes:

> On Tue, Jan 23 2024 at 17:46, Anna-Maria Behnsen wrote:
>> 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.
>
> Shouldn't this simply move to kernel/time/... ? Nothing outside of it
> needs hrtimer_base

hrtimer_expires_remaining() which is defined in include/hrtimer.h
dereferences hrtimer_clock_base; hrtimer_is_hres_active() also defined
in include/hrtimer.h needs hrtimer_base.

Thanks,

	Anna-Maria

Re: [PATCH 1/8] include/hrtimers: Move hrtimer base related definitions into hrtimer_defs

[Thomas Gleixner]

On Thu, Jan 25 2024 at 13:20, Anna-Maria Behnsen wrote:
> Thomas Gleixner <tglx@linutronix.de> writes:
>
>> On Tue, Jan 23 2024 at 17:46, Anna-Maria Behnsen wrote:
>>> 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.
>>
>> Shouldn't this simply move to kernel/time/... ? Nothing outside of it
>> needs hrtimer_base
>
> hrtimer_expires_remaining() which is defined in include/hrtimer.h
> dereferences hrtimer_clock_base; hrtimer_is_hres_active() also defined
> in include/hrtimer.h needs hrtimer_base.

Duh, yes.

[PATCH 2/8] hrtimers: Update formatting of documentation

[Anna-Maria Behnsen]

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 <anna-maria@linutronix.de>
---
 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)
 {
-- 
2.39.2

[PATCH 3/8] tick/sched: Add function description for tick_nohz_next_event()

[Anna-Maria Behnsen]

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

[PATCH 4/8] timers: Add struct member description for timer_base

[Anna-Maria Behnsen]

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

[PATCH 5/8] jiffies: Transform comment about time_* functions into DOC block

[Anna-Maria Behnsen]

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 <anna-maria@linutronix.de>
---
 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.
  */
 
 /**
-- 
2.39.2

[PATCH 6/8] Documentation: Create a new folder for all timer internals

[Anna-Maria Behnsen]

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

Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Randy Dunlap]

Hi,

On 1/23/24 08:47, Anna-Maria Behnsen wrote:
> 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 +++++

When can we remove the old, "might be outdated" files?
Do you think that some of their contents might be valuable to someone?

I prefer not to have the old documentation and the new.

>  9 files changed, 57 insertions(+)
>  create mode 100644 Documentation/core-api/timers/index.rst
> 

Thanks.

-- 
#Randy

Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Anna-Maria Behnsen]

Randy Dunlap <rdunlap@infradead.org> writes:

> Hi,
>
> On 1/23/24 08:47, Anna-Maria Behnsen wrote:
>> 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 +++++
>
> When can we remove the old, "might be outdated" files?
> Do you think that some of their contents might be valuable to someone?
>
> I prefer not to have the old documentation and the new.
>

This is also nothing I prefere for a final solution. But I got stucked
when I was looking for a way to add the actual documentation because I
wanted to add it into a cleaned-up environment. But I don't have the
possibility at the moment to cleanup the existing timer documentation
right away with all its aspects (content, formatting, referencing,
location below Documentation,... ).

So I had those options:

1. wait until I have time for all this before publishing the new
   documentation -> not an option because I don't know when there is
   time to do all those things in one go

2. Put the new documentation below the existing one and ignore the rest
   silently (maybe someone else will clean it up someday) -> not an
   option because it suggests that the new documentation structure is
   just ignored

3. Just move the old documentation without revisiting it -> not an
   option because there might be outdated information and then it
   doesn't has a benefit for the reader

4. Add a warning banner at the existing documentation and prepare
   everything to get the timer documentation to the proper place and
   create a place for timer documentation below the current structure.

The benefit of 4. for me is, that there is this warning banner at the
top. So this suggests the reader, that this has to be revisited before
relying on it for 100%. This banner might also remind the original
author/technically deep involved developer that this should be
updated.

If there is a better way to go, please let me know!

Thanks,

        Anna-Maria

Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Jonathan Corbet]

Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
> 4. Add a warning banner at the existing documentation and prepare
>    everything to get the timer documentation to the proper place and
>    create a place for timer documentation below the current structure.
>
> The benefit of 4. for me is, that there is this warning banner at the
> top. So this suggests the reader, that this has to be revisited before
> relying on it for 100%. This banner might also remind the original
> author/technically deep involved developer that this should be
> updated.

The best thing, of course, is to just fix all of the documentation and
make it perfect now :)

Failing that, the banners are fine IMO.  They mark possibly obsolete
docs, warning readers, and also just might, in an optimal world, inspire
somebody else to work to improve the situation.

I've thought for a while that we should have a standard warning or two
along these lines, like Wikipedia does, but of course haven't done
anything about it.

jon

Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Jani Nikula]

On Thu, 25 Jan 2024, Jonathan Corbet <corbet@lwn.net> wrote:
> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
>> 4. Add a warning banner at the existing documentation and prepare
>>    everything to get the timer documentation to the proper place and
>>    create a place for timer documentation below the current structure.
>>
>> The benefit of 4. for me is, that there is this warning banner at the
>> top. So this suggests the reader, that this has to be revisited before
>> relying on it for 100%. This banner might also remind the original
>> author/technically deep involved developer that this should be
>> updated.
>
> The best thing, of course, is to just fix all of the documentation and
> make it perfect now :)
>
> Failing that, the banners are fine IMO.  They mark possibly obsolete
> docs, warning readers, and also just might, in an optimal world, inspire
> somebody else to work to improve the situation.
>
> I've thought for a while that we should have a standard warning or two
> along these lines, like Wikipedia does, but of course haven't done
> anything about it.

One approach could be to use the todo extension [1], and use todo
directives instead of warnings. With todo_include_todos config set to
True, you get the banners in the code, but it's more of an invitation
for people to fix them. Maybe. :)

BR,
Jani.


[1] https://www.sphinx-doc.org/en/master/usage/extensions/todo.html

-- 
Jani Nikula, Intel

Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Anna-Maria Behnsen]

Jani Nikula <jani.nikula@linux.intel.com> writes:

> On Thu, 25 Jan 2024, Jonathan Corbet <corbet@lwn.net> wrote:
>>
>> I've thought for a while that we should have a standard warning or two
>> along these lines, like Wikipedia does, but of course haven't done
>> anything about it.
>
> One approach could be to use the todo extension [1], and use todo
> directives instead of warnings. With todo_include_todos config set to
> True, you get the banners in the code, but it's more of an invitation
> for people to fix them. Maybe. :)
>

This might be a bit more positive than the red warning box. But with
this todo extension, the box is simply grey and might be easier to
ignore (I don't know if it is that easy to change the appearance).

Thanks,

	Anna-Maria

Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Anna-Maria Behnsen]

Jonathan Corbet <corbet@lwn.net> writes:

> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
>> 4. Add a warning banner at the existing documentation and prepare
>>    everything to get the timer documentation to the proper place and
>>    create a place for timer documentation below the current structure.
>>
>> The benefit of 4. for me is, that there is this warning banner at the
>> top. So this suggests the reader, that this has to be revisited before
>> relying on it for 100%. This banner might also remind the original
>> author/technically deep involved developer that this should be
>> updated.
>
> The best thing, of course, is to just fix all of the documentation and
> make it perfect now :)
>
> Failing that, the banners are fine IMO.  They mark possibly obsolete
> docs, warning readers, and also just might, in an optimal world, inspire
> somebody else to work to improve the situation.

I hope the world is optimal at least sometimes :)

> I've thought for a while that we should have a standard warning or two
> along these lines, like Wikipedia does, but of course haven't done
> anything about it.
>

Sure, if we could standardize it, I would definitely prefere it! For me
as a not sphinx/rst/... expert, it would be great if only something like

.. might_be_outdated:: <optional additional text>

needs to be added to the code. And then the default lines would appear
together with the optional additional text.

Is this what you have been thinking about?

Thanks,

	Anna-Maria

Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Jonathan Corbet]

Anna-Maria Behnsen <anna-maria@linutronix.de> writes:

>> I've thought for a while that we should have a standard warning or two
>> along these lines, like Wikipedia does, but of course haven't done
>> anything about it.
>>
>
> Sure, if we could standardize it, I would definitely prefere it! For me
> as a not sphinx/rst/... expert, it would be great if only something like
>
> .. might_be_outdated:: <optional additional text>
>
> needs to be added to the code. And then the default lines would appear
> together with the optional additional text.
>
> Is this what you have been thinking about?

You've already put more thought into it than I have :)

I was just thinking in terms of some relatively standard text.  I'd
rather not create an extension just for this, but Jani's idea of using
the todo extension could work, or just a convention like:

  .. include crufty-stuff-note.rst

might be good enough and not require an extension at all.

Thanks,

jon

Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Anna-Maria Behnsen]

Jonathan Corbet <corbet@lwn.net> writes:

> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
>
>>> I've thought for a while that we should have a standard warning or two
>>> along these lines, like Wikipedia does, but of course haven't done
>>> anything about it.
>>>
>>
>> Sure, if we could standardize it, I would definitely prefere it! For me
>> as a not sphinx/rst/... expert, it would be great if only something like
>>
>> .. might_be_outdated:: <optional additional text>
>>
>> needs to be added to the code. And then the default lines would appear
>> together with the optional additional text.
>>
>> Is this what you have been thinking about?
>
> You've already put more thought into it than I have :)
>
> I was just thinking in terms of some relatively standard text.  I'd
> rather not create an extension just for this, but Jani's idea of using
> the todo extension could work, or just a convention like:
>
>   .. include crufty-stuff-note.rst
>
> might be good enough and not require an extension at all.

Maybe also a combination of both - using the todo extension inside the
include file?

I would integrate it into a v2, but I'm not sure, when I have time to
prepare it.

Thanks,

        Anna-Maria

[PATCH 7/8] Documentation: Move "core core" api into a separate file

[Anna-Maria Behnsen]

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

Re: [PATCH 7/8] Documentation: Move "core core" api into a separate file

[Randy Dunlap]

On 1/23/24 08:47, Anna-Maria Behnsen wrote:
> 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 <anna-maria@linutronix.de>
> ---
>  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

I'm getting this warning from the line above:

linux-next-20240123/Documentation/core-api/core-api.rst:7: WARNING: unknown document: '../driver-api/basic'

Ah, it should be "basics".

> +          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`.


-- 
#Randy

Re: [PATCH 7/8] Documentation: Move "core core" api into a separate file

[Anna-Maria Behnsen]

Randy Dunlap <rdunlap@infradead.org> writes:

> On 1/23/24 08:47, Anna-Maria Behnsen wrote:
>> 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 <anna-maria@linutronix.de>
>> ---
>>  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
>
> I'm getting this warning from the line above:
>
> linux-next-20240123/Documentation/core-api/core-api.rst:7: WARNING: unknown document: '../driver-api/basic'
>
> Ah, it should be "basics".
>

Oh no! I fixed it - but didn't update the patch... I'm sorry!

Thanks,
        Anna-Maria

[PATCH 8/8] timers: Add timer wheel documentation

[Anna-Maria Behnsen]

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