Message-Id: <20240123164702.55612-1-anna-maria@linutronix.de>
Date: Tue, 23 Jan 2024 17:46:54 +0100
From: Anna-Maria Behnsen <anna-maria@...utronix.de>
To: linux-kernel@...r.kernel.org
Cc: Thomas Gleixner <tglx@...utronix.de>,
	Frederic Weisbecker <frederic@...nel.org>,
	Ingo Molnar <mingo@...nel.org>,
	John Stultz <jstultz@...gle.com>,
	Stephen Boyd <sboyd@...nel.org>,
	Jonathan Corbet <corbet@....net>,
	Clemens Ladisch <clemens@...isch.de>,
	linux-doc@...r.kernel.org,
	Anna-Maria Behnsen <anna-maria@...utronix.de>
Subject: [PATCH 0/8] timers and Documentation: Cleanup

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

Powered by blists - more mailing lists