docs: timers: convert docs to ReST and rename to *.rst

The conversion here is really trivial: just a bunch of title
markups and very few puntual changes is enough to make it to
be parsed by Sphinx and generate a nice html.

The conversion is actually:
  - add blank lines and identation in order to identify paragraphs;
  - fix tables markups;
  - add some lists markups;
  - mark literal blocks;
  - adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2019-06-12 14:53:00 -03:00 committed by Jonathan Corbet
parent 4ca9bc225e
commit 458f69ef36
14 changed files with 84 additions and 43 deletions

View File

@ -1,5 +1,6 @@
=====================================================
High resolution timers and dynamic ticks design notes High resolution timers and dynamic ticks design notes
----------------------------------------------------- =====================================================
Further information can be found in the paper of the OLS 2006 talk "hrtimers 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 and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
@ -30,11 +31,12 @@ hrtimer base infrastructure
--------------------------- ---------------------------
The hrtimer base infrastructure was merged into the 2.6.16 kernel. Details of The hrtimer base infrastructure was merged into the 2.6.16 kernel. Details of
the base implementation are covered in Documentation/timers/hrtimers.txt. See the base implementation are covered in Documentation/timers/hrtimers.rst. See
also figure #2 (OLS slides p. 15) also figure #2 (OLS slides p. 15)
The main differences to the timer wheel, which holds the armed timer_list type The main differences to the timer wheel, which holds the armed timer_list type
timers are: timers are:
- time ordered enqueueing into a rb-tree - time ordered enqueueing into a rb-tree
- independent of ticks (the processing is based on nanoseconds) - independent of ticks (the processing is based on nanoseconds)
@ -55,7 +57,8 @@ merged into the 2.6.18 kernel.
Further information about the Generic Time Of Day framework is available in the Further information about the Generic Time Of Day framework is available in the
OLS 2005 Proceedings Volume 1: OLS 2005 Proceedings Volume 1:
http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
The paper "We Are Not Getting Any Younger: A New Approach to Time and The paper "We Are Not Getting Any Younger: A New Approach to Time and
Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan. Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan.
@ -100,6 +103,7 @@ accounting, profiling, and high resolution timers.
The management layer assigns one or more of the following functions to a clock The management layer assigns one or more of the following functions to a clock
event device: event device:
- system global periodic tick (jiffies update) - system global periodic tick (jiffies update)
- cpu local update_process_times - cpu local update_process_times
- cpu local profiling - cpu local profiling
@ -244,6 +248,3 @@ extended to x86_64 and ARM already. Initial (work in progress) support is also
available for MIPS and PowerPC. available for MIPS and PowerPC.
Thomas, Ingo Thomas, Ingo

View File

@ -1,4 +1,6 @@
High Precision Event Timer Driver for Linux ===========================================
High Precision Event Timer Driver for Linux
===========================================
The High Precision Event Timer (HPET) hardware follows a specification The High Precision Event Timer (HPET) hardware follows a specification
by Intel and Microsoft, revision 1. by Intel and Microsoft, revision 1.

View File

@ -1,6 +1,6 @@
======================================================
hrtimers - subsystem for high-resolution kernel timers hrtimers - subsystem for high-resolution kernel timers
---------------------------------------------------- ======================================================
This patch introduces a new subsystem for high-resolution kernel timers. This patch introduces a new subsystem for high-resolution kernel timers.
@ -146,7 +146,7 @@ the clock_getres() interface. This will return whatever real resolution
a given clock has - be it low-res, high-res, or artificially-low-res. a given clock has - be it low-res, high-res, or artificially-low-res.
hrtimers - testing and verification hrtimers - testing and verification
---------------------------------- -----------------------------------
We used the high-resolution clock subsystem ontop of hrtimers to verify We used the high-resolution clock subsystem ontop of hrtimers to verify
the hrtimer implementation details in praxis, and we also ran the posix the hrtimer implementation details in praxis, and we also ran the posix

View File

@ -0,0 +1,22 @@
:orphan:
======
timers
======
.. toctree::
:maxdepth: 1
highres
hpet
hrtimers
no_hz
timekeeping
timers-howto
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -1,4 +1,6 @@
NO_HZ: Reducing Scheduling-Clock Ticks ======================================
NO_HZ: Reducing Scheduling-Clock Ticks
======================================
This document describes Kconfig options and boot parameters that can This document describes Kconfig options and boot parameters that can
@ -28,7 +30,8 @@ by a third section on RCU-specific considerations, a fourth section
discussing testing, and a fifth and final section listing known issues. discussing testing, and a fifth and final section listing known issues.
NEVER OMIT SCHEDULING-CLOCK TICKS Never Omit Scheduling-Clock Ticks
=================================
Very old versions of Linux from the 1990s and the very early 2000s Very old versions of Linux from the 1990s and the very early 2000s
are incapable of omitting scheduling-clock ticks. It turns out that are incapable of omitting scheduling-clock ticks. It turns out that
@ -59,7 +62,8 @@ degrade your applications performance. If this describes your workload,
you should read the following two sections. you should read the following two sections.
OMIT SCHEDULING-CLOCK TICKS FOR IDLE CPUs Omit Scheduling-Clock Ticks For Idle CPUs
=========================================
If a CPU is idle, there is little point in sending it a scheduling-clock If a CPU is idle, there is little point in sending it a scheduling-clock
interrupt. After all, the primary purpose of a scheduling-clock interrupt interrupt. After all, the primary purpose of a scheduling-clock interrupt
@ -97,7 +101,8 @@ By default, CONFIG_NO_HZ_IDLE=y kernels boot with "nohz=on", enabling
dyntick-idle mode. dyntick-idle mode.
OMIT SCHEDULING-CLOCK TICKS FOR CPUs WITH ONLY ONE RUNNABLE TASK Omit Scheduling-Clock Ticks For CPUs With Only One Runnable Task
================================================================
If a CPU has only one runnable task, there is little point in sending it If a CPU has only one runnable task, there is little point in sending it
a scheduling-clock interrupt because there is no other task to switch to. a scheduling-clock interrupt because there is no other task to switch to.
@ -174,7 +179,8 @@ However, the drawbacks listed above mean that adaptive ticks should not
(yet) be enabled by default. (yet) be enabled by default.
RCU IMPLICATIONS RCU Implications
================
There are situations in which idle CPUs cannot be permitted to There are situations in which idle CPUs cannot be permitted to
enter either dyntick-idle mode or adaptive-tick mode, the most enter either dyntick-idle mode or adaptive-tick mode, the most
@ -199,7 +205,8 @@ scheduler will decide where to run them, which might or might not be
where you want them to run. where you want them to run.
TESTING Testing
=======
So you enable all the OS-jitter features described in this document, So you enable all the OS-jitter features described in this document,
but do not see any change in your workload's behavior. Is this because but do not see any change in your workload's behavior. Is this because
@ -222,9 +229,10 @@ We do not currently have a good way to remove OS jitter from single-CPU
systems. systems.
KNOWN ISSUES Known Issues
============
o Dyntick-idle slows transitions to and from idle slightly. * Dyntick-idle slows transitions to and from idle slightly.
In practice, this has not been a problem except for the most In practice, this has not been a problem except for the most
aggressive real-time workloads, which have the option of disabling aggressive real-time workloads, which have the option of disabling
dyntick-idle mode, an option that most of them take. However, dyntick-idle mode, an option that most of them take. However,
@ -248,13 +256,13 @@ o Dyntick-idle slows transitions to and from idle slightly.
this parameter effectively disables Turbo Mode on Intel this parameter effectively disables Turbo Mode on Intel
CPUs, which can significantly reduce maximum performance. CPUs, which can significantly reduce maximum performance.
o Adaptive-ticks slows user/kernel transitions slightly. * Adaptive-ticks slows user/kernel transitions slightly.
This is not expected to be a problem for computationally intensive This is not expected to be a problem for computationally intensive
workloads, which have few such transitions. Careful benchmarking workloads, which have few such transitions. Careful benchmarking
will be required to determine whether or not other workloads will be required to determine whether or not other workloads
are significantly affected by this effect. are significantly affected by this effect.
o Adaptive-ticks does not do anything unless there is only one * Adaptive-ticks does not do anything unless there is only one
runnable task for a given CPU, even though there are a number runnable task for a given CPU, even though there are a number
of other situations where the scheduling-clock tick is not of other situations where the scheduling-clock tick is not
needed. To give but one example, consider a CPU that has one needed. To give but one example, consider a CPU that has one
@ -275,7 +283,7 @@ o Adaptive-ticks does not do anything unless there is only one
Better handling of these sorts of situations is future work. Better handling of these sorts of situations is future work.
o A reboot is required to reconfigure both adaptive idle and RCU * A reboot is required to reconfigure both adaptive idle and RCU
callback offloading. Runtime reconfiguration could be provided callback offloading. Runtime reconfiguration could be provided
if needed, however, due to the complexity of reconfiguring RCU at if needed, however, due to the complexity of reconfiguring RCU at
runtime, there would need to be an earthshakingly good reason. runtime, there would need to be an earthshakingly good reason.
@ -283,12 +291,12 @@ o A reboot is required to reconfigure both adaptive idle and RCU
simply offloading RCU callbacks from all CPUs and pinning them simply offloading RCU callbacks from all CPUs and pinning them
where you want them whenever you want them pinned. where you want them whenever you want them pinned.
o Additional configuration is required to deal with other sources * Additional configuration is required to deal with other sources
of OS jitter, including interrupts and system-utility tasks of OS jitter, including interrupts and system-utility tasks
and processes. This configuration normally involves binding and processes. This configuration normally involves binding
interrupts and tasks to particular CPUs. interrupts and tasks to particular CPUs.
o Some sources of OS jitter can currently be eliminated only by * Some sources of OS jitter can currently be eliminated only by
constraining the workload. For example, the only way to eliminate constraining the workload. For example, the only way to eliminate
OS jitter due to global TLB shootdowns is to avoid the unmapping OS jitter due to global TLB shootdowns is to avoid the unmapping
operations (such as kernel module unload operations) that operations (such as kernel module unload operations) that
@ -299,17 +307,17 @@ o Some sources of OS jitter can currently be eliminated only by
helpful, especially when combined with the mlock() and mlockall() helpful, especially when combined with the mlock() and mlockall()
system calls. system calls.
o Unless all CPUs are idle, at least one CPU must keep the * Unless all CPUs are idle, at least one CPU must keep the
scheduling-clock interrupt going in order to support accurate scheduling-clock interrupt going in order to support accurate
timekeeping. timekeeping.
o If there might potentially be some adaptive-ticks CPUs, there * If there might potentially be some adaptive-ticks CPUs, there
will be at least one CPU keeping the scheduling-clock interrupt will be at least one CPU keeping the scheduling-clock interrupt
going, even if all CPUs are otherwise idle. going, even if all CPUs are otherwise idle.
Better handling of this situation is ongoing work. Better handling of this situation is ongoing work.
o Some process-handling operations still require the occasional * Some process-handling operations still require the occasional
scheduling-clock tick. These operations include calculating CPU scheduling-clock tick. These operations include calculating CPU
load, maintaining sched average, computing CFS entity vruntime, load, maintaining sched average, computing CFS entity vruntime,
computing avenrun, and carrying out load balancing. They are computing avenrun, and carrying out load balancing. They are

View File

@ -1,5 +1,6 @@
===========================================================
Clock sources, Clock events, sched_clock() and delay timers Clock sources, Clock events, sched_clock() and delay timers
----------------------------------------------------------- ===========================================================
This document tries to briefly explain some basic kernel timekeeping This document tries to briefly explain some basic kernel timekeeping
abstractions. It partly pertains to the drivers usually found in abstractions. It partly pertains to the drivers usually found in

View File

@ -1,5 +1,6 @@
===================================================================
delays - Information on the various kernel delay / sleep mechanisms delays - Information on the various kernel delay / sleep mechanisms
------------------------------------------------------------------- ===================================================================
This document seeks to answer the common question: "What is the This document seeks to answer the common question: "What is the
RightWay (TM) to insert a delay?" RightWay (TM) to insert a delay?"
@ -17,7 +18,7 @@ code in an atomic context?" This should be followed closely by "Does
it really need to delay in atomic context?" If so... it really need to delay in atomic context?" If so...
ATOMIC CONTEXT: ATOMIC CONTEXT:
You must use the *delay family of functions. These You must use the `*delay` family of functions. These
functions use the jiffie estimation of clock speed functions use the jiffie estimation of clock speed
and will busy wait for enough loop cycles to achieve and will busy wait for enough loop cycles to achieve
the desired delay: the desired delay:
@ -35,21 +36,26 @@ ATOMIC CONTEXT:
be refactored to allow for the use of msleep. be refactored to allow for the use of msleep.
NON-ATOMIC CONTEXT: NON-ATOMIC CONTEXT:
You should use the *sleep[_range] family of functions. You should use the `*sleep[_range]` family of functions.
There are a few more options here, while any of them may There are a few more options here, while any of them may
work correctly, using the "right" sleep function will work correctly, using the "right" sleep function will
help the scheduler, power management, and just make your help the scheduler, power management, and just make your
driver better :) driver better :)
-- Backed by busy-wait loop: -- Backed by busy-wait loop:
udelay(unsigned long usecs) udelay(unsigned long usecs)
-- Backed by hrtimers: -- Backed by hrtimers:
usleep_range(unsigned long min, unsigned long max) usleep_range(unsigned long min, unsigned long max)
-- Backed by jiffies / legacy_timers -- Backed by jiffies / legacy_timers
msleep(unsigned long msecs) msleep(unsigned long msecs)
msleep_interruptible(unsigned long msecs) msleep_interruptible(unsigned long msecs)
Unlike the *delay family, the underlying mechanism Unlike the `*delay` family, the underlying mechanism
driving each of these calls varies, thus there are driving each of these calls varies, thus there are
quirks you should be aware of. quirks you should be aware of.
@ -70,6 +76,7 @@ NON-ATOMIC CONTEXT:
- Why not msleep for (1ms - 20ms)? - Why not msleep for (1ms - 20ms)?
Explained originally here: Explained originally here:
http://lkml.org/lkml/2007/8/3/250 http://lkml.org/lkml/2007/8/3/250
msleep(1~20) may not do what the caller intends, and msleep(1~20) may not do what the caller intends, and
will often sleep longer (~20 ms actual sleep for any will often sleep longer (~20 ms actual sleep for any
value given in the 1~20ms range). In many cases this value given in the 1~20ms range). In many cases this

View File

@ -7192,7 +7192,7 @@ F: drivers/net/ethernet/hp/hp100.*
HPET: High Precision Event Timers driver HPET: High Precision Event Timers driver
M: Clemens Ladisch <clemens@ladisch.de> M: Clemens Ladisch <clemens@ladisch.de>
S: Maintained S: Maintained
F: Documentation/timers/hpet.txt F: Documentation/timers/hpet.rst
F: drivers/char/hpet.c F: drivers/char/hpet.c
F: include/linux/hpet.h F: include/linux/hpet.h
F: include/uapi/linux/hpet.h F: include/uapi/linux/hpet.h

View File

@ -56,7 +56,7 @@ static int anysee_ctrl_msg(struct dvb_usb_device *d,
/* TODO FIXME: dvb_usb_generic_rw() fails rarely with error code -32 /* TODO FIXME: dvb_usb_generic_rw() fails rarely with error code -32
* (EPIPE, Broken pipe). Function supports currently msleep() as a * (EPIPE, Broken pipe). Function supports currently msleep() as a
* parameter but I would not like to use it, since according to * parameter but I would not like to use it, since according to
* Documentation/timers/timers-howto.txt it should not be used such * Documentation/timers/timers-howto.rst it should not be used such
* short, under < 20ms, sleeps. Repeating failed message would be * short, under < 20ms, sleeps. Repeating failed message would be
* better choice as not to add unwanted delays... * better choice as not to add unwanted delays...
* Fixing that correctly is one of those or both; * Fixing that correctly is one of those or both;

View File

@ -2304,7 +2304,7 @@ static int regulator_ena_gpio_ctrl(struct regulator_dev *rdev, bool enable)
* *
* Delay for the requested amount of time as per the guidelines in: * Delay for the requested amount of time as per the guidelines in:
* *
* Documentation/timers/timers-howto.txt * Documentation/timers/timers-howto.rst
* *
* The assumption here is that regulators will never be enabled in * The assumption here is that regulators will never be enabled in
* atomic context and therefore sleeping functions can be used. * atomic context and therefore sleeping functions can be used.

View File

@ -21,7 +21,7 @@
* @cond: Break condition (usually involving @val) * @cond: Break condition (usually involving @val)
* @sleep_us: Maximum time to sleep between reads in us (0 * @sleep_us: Maximum time to sleep between reads in us (0
* tight-loops). Should be less than ~20ms since usleep_range * tight-loops). Should be less than ~20ms since usleep_range
* is used (see Documentation/timers/timers-howto.txt). * is used (see Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout * @timeout_us: Timeout in us, 0 means never timeout
* *
* Returns 0 on success and -ETIMEDOUT upon a timeout. In either * Returns 0 on success and -ETIMEDOUT upon a timeout. In either
@ -60,7 +60,7 @@
* @cond: Break condition (usually involving @val) * @cond: Break condition (usually involving @val)
* @delay_us: Time to udelay between reads in us (0 tight-loops). Should * @delay_us: Time to udelay between reads in us (0 tight-loops). Should
* be less than ~10us since udelay is used (see * be less than ~10us since udelay is used (see
* Documentation/timers/timers-howto.txt). * Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout * @timeout_us: Timeout in us, 0 means never timeout
* *
* Returns 0 on success and -ETIMEDOUT upon a timeout. In either * Returns 0 on success and -ETIMEDOUT upon a timeout. In either

View File

@ -112,7 +112,7 @@ struct reg_sequence {
* @cond: Break condition (usually involving @val) * @cond: Break condition (usually involving @val)
* @sleep_us: Maximum time to sleep between reads in us (0 * @sleep_us: Maximum time to sleep between reads in us (0
* tight-loops). Should be less than ~20ms since usleep_range * tight-loops). Should be less than ~20ms since usleep_range
* is used (see Documentation/timers/timers-howto.txt). * is used (see Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout * @timeout_us: Timeout in us, 0 means never timeout
* *
* Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
@ -154,7 +154,7 @@ struct reg_sequence {
* @cond: Break condition (usually involving @val) * @cond: Break condition (usually involving @val)
* @sleep_us: Maximum time to sleep between reads in us (0 * @sleep_us: Maximum time to sleep between reads in us (0
* tight-loops). Should be less than ~20ms since usleep_range * tight-loops). Should be less than ~20ms since usleep_range
* is used (see Documentation/timers/timers-howto.txt). * is used (see Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout * @timeout_us: Timeout in us, 0 means never timeout
* *
* Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read

View File

@ -5712,7 +5712,7 @@ sub process {
# ignore udelay's < 10, however # ignore udelay's < 10, however
if (! ($delay < 10) ) { if (! ($delay < 10) ) {
CHK("USLEEP_RANGE", CHK("USLEEP_RANGE",
"usleep_range is preferred over udelay; see Documentation/timers/timers-howto.txt\n" . $herecurr); "usleep_range is preferred over udelay; see Documentation/timers/timers-howto.rst\n" . $herecurr);
} }
if ($delay > 2000) { if ($delay > 2000) {
WARN("LONG_UDELAY", WARN("LONG_UDELAY",
@ -5724,7 +5724,7 @@ sub process {
if ($line =~ /\bmsleep\s*\((\d+)\);/) { if ($line =~ /\bmsleep\s*\((\d+)\);/) {
if ($1 < 20) { if ($1 < 20) {
WARN("MSLEEP", WARN("MSLEEP",
"msleep < 20ms can sleep for up to 20ms; see Documentation/timers/timers-howto.txt\n" . $herecurr); "msleep < 20ms can sleep for up to 20ms; see Documentation/timers/timers-howto.rst\n" . $herecurr);
} }
} }
@ -6115,11 +6115,11 @@ sub process {
my $max = $7; my $max = $7;
if ($min eq $max) { if ($min eq $max) {
WARN("USLEEP_RANGE", WARN("USLEEP_RANGE",
"usleep_range should not use min == max args; see Documentation/timers/timers-howto.txt\n" . "$here\n$stat\n"); "usleep_range should not use min == max args; see Documentation/timers/timers-howto.rst\n" . "$here\n$stat\n");
} elsif ($min =~ /^\d+$/ && $max =~ /^\d+$/ && } elsif ($min =~ /^\d+$/ && $max =~ /^\d+$/ &&
$min > $max) { $min > $max) {
WARN("USLEEP_RANGE", WARN("USLEEP_RANGE",
"usleep_range args reversed, use min then max; see Documentation/timers/timers-howto.txt\n" . "$here\n$stat\n"); "usleep_range args reversed, use min then max; see Documentation/timers/timers-howto.rst\n" . "$here\n$stat\n");
} }
} }

View File

@ -349,7 +349,7 @@ static inline const struct snd_sof_dsp_ops
* @cond: Break condition (usually involving @val) * @cond: Break condition (usually involving @val)
* @sleep_us: Maximum time to sleep between reads in us (0 * @sleep_us: Maximum time to sleep between reads in us (0
* tight-loops). Should be less than ~20ms since usleep_range * tight-loops). Should be less than ~20ms since usleep_range
* is used (see Documentation/timers/timers-howto.txt). * is used (see Documentation/timers/timers-howto.rst).
* @timeout_us: Timeout in us, 0 means never timeout * @timeout_us: Timeout in us, 0 means never timeout
* *
* Returns 0 on success and -ETIMEDOUT upon a timeout. In either * Returns 0 on success and -ETIMEDOUT upon a timeout. In either