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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
> ---
> 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
Randy Dunlap <[email protected]> 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 <[email protected]>
>> ---
>> 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
The following commit has been merged into the timers/core branch of tip:
Commit-ID: 892abd357183bc663d6984d10c62f94b40bfc375
Gitweb: https://git.kernel.org/tip/892abd357183bc663d6984d10c62f94b40bfc375
Author: Anna-Maria Behnsen <[email protected]>
AuthorDate: Tue, 23 Jan 2024 17:46:58 +01:00
Committer: Thomas Gleixner <[email protected]>
CommitterDate: Mon, 19 Feb 2024 09:38:00 +01:00
timers: Add struct member description for timer_base
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 <[email protected]>
Signed-off-by: Thomas Gleixner <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
---
kernel/time/timer.c | 45 ++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 45 insertions(+)
diff --git a/kernel/time/timer.c b/kernel/time/timer.c
index 352b161..d44dba1 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;