[7/8] Documentation: Move "core core" api into a separate file
Commit Message
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
Comments
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 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
new file mode 100644
@@ -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`.
@@ -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
@@ -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
=========================
new file mode 100644
@@ -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:
@@ -16,6 +16,10 @@ kernel/timers/ and also the timer related includes.
Information for Users
=====================
+.. toctree::
+ :maxdepth: 1
+
+ api
Information about concepts and internals
@@ -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
---------------------------