diff --git a/Documentation/timers/highres.txt b/Documentation/timers/highres.rst similarity index 98% rename from Documentation/timers/highres.txt rename to Documentation/timers/highres.rst index 8f97415921238f15289779df31c0056e876ce615..bde5eb7e5c9efc10494b242bd055bb602a03efff 100644 --- a/Documentation/timers/highres.txt +++ b/Documentation/timers/highres.rst @@ -1,5 +1,6 @@ +===================================================== High resolution timers and dynamic ticks design notes ------------------------------------------------------ +===================================================== 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 @@ -30,11 +31,12 @@ hrtimer base infrastructure --------------------------- 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) The main differences to the timer wheel, which holds the armed timer_list type timers are: + - time ordered enqueueing into a rb-tree - 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 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 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 event device: + - system global periodic tick (jiffies update) - cpu local update_process_times - 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. Thomas, Ingo - - - diff --git a/Documentation/timers/hpet.txt b/Documentation/timers/hpet.rst similarity index 91% rename from Documentation/timers/hpet.txt rename to Documentation/timers/hpet.rst index 895345ec513b5cfe90ac3a2d7c95d355ecce121a..c9d05d3caaca9701a5988770e6dfda5b45b4bfad 100644 --- a/Documentation/timers/hpet.txt +++ b/Documentation/timers/hpet.rst @@ -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 by Intel and Microsoft, revision 1. diff --git a/Documentation/timers/hrtimers.txt b/Documentation/timers/hrtimers.rst similarity index 98% rename from Documentation/timers/hrtimers.txt rename to Documentation/timers/hrtimers.rst index 588d85724f1088da3f8359ba36d35fef92413962..c1c20a693e8f9449ba817c54bc6db062615619c4 100644 --- a/Documentation/timers/hrtimers.txt +++ b/Documentation/timers/hrtimers.rst @@ -1,6 +1,6 @@ - +====================================================== hrtimers - 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. hrtimers - testing and verification ----------------------------------- +----------------------------------- We used the high-resolution clock subsystem ontop of hrtimers to verify the hrtimer implementation details in praxis, and we also ran the posix diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..91f6f8263c48acc6137ff0250e00b6094695d1e2 --- /dev/null +++ b/Documentation/timers/index.rst @@ -0,0 +1,22 @@ +:orphan: + +====== +timers +====== + +.. toctree:: + :maxdepth: 1 + + highres + hpet + hrtimers + no_hz + timekeeping + timers-howto + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/timers/NO_HZ.txt b/Documentation/timers/no_hz.rst similarity index 93% rename from Documentation/timers/NO_HZ.txt rename to Documentation/timers/no_hz.rst index 9591092da5e03739fb49aee8f0fd95807028383e..065db217cb04fc252bbf6a05991296e7f1d3a4c5 100644 --- a/Documentation/timers/NO_HZ.txt +++ b/Documentation/timers/no_hz.rst @@ -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 @@ -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. -NEVER OMIT SCHEDULING-CLOCK TICKS +Never Omit Scheduling-Clock Ticks +================================= Very old versions of Linux from the 1990s and the very early 2000s 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. -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 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. -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 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. -RCU IMPLICATIONS +RCU Implications +================ There are situations in which idle CPUs cannot be permitted to 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. -TESTING +Testing +======= 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 @@ -222,9 +229,10 @@ We do not currently have a good way to remove OS jitter from single-CPU 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 aggressive real-time workloads, which have the option of disabling 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 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 workloads, which have few such transitions. Careful benchmarking will be required to determine whether or not other workloads 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 of other situations where the scheduling-clock tick is not 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. -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 if needed, however, due to the complexity of reconfiguring RCU at 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 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 and processes. This configuration normally involves binding 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 OS jitter due to global TLB shootdowns is to avoid the unmapping 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() 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 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 going, even if all CPUs are otherwise idle. 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 load, maintaining sched average, computing CFS entity vruntime, computing avenrun, and carrying out load balancing. They are diff --git a/Documentation/timers/timekeeping.txt b/Documentation/timers/timekeeping.rst similarity index 98% rename from Documentation/timers/timekeeping.txt rename to Documentation/timers/timekeeping.rst index 2d1732b0a868012165a11a21f2b3d4ffe4c1f750..f83e98852e2cb5f65972dc1e90989c2ea73c2396 100644 --- a/Documentation/timers/timekeeping.txt +++ b/Documentation/timers/timekeeping.rst @@ -1,5 +1,6 @@ +=========================================================== Clock sources, Clock events, sched_clock() and delay timers ------------------------------------------------------------ +=========================================================== This document tries to briefly explain some basic kernel timekeeping abstractions. It partly pertains to the drivers usually found in diff --git a/Documentation/timers/timers-howto.txt b/Documentation/timers/timers-howto.rst similarity index 93% rename from Documentation/timers/timers-howto.txt rename to Documentation/timers/timers-howto.rst index 038f8c77a0767d26f64526924178bec3439b98bc..7e3167bec2b1ff96c961609cd75a098665497375 100644 --- a/Documentation/timers/timers-howto.txt +++ b/Documentation/timers/timers-howto.rst @@ -1,5 +1,6 @@ +=================================================================== delays - Information on the various kernel delay / sleep mechanisms -------------------------------------------------------------------- +=================================================================== This document seeks to answer the common question: "What is the 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... 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 and will busy wait for enough loop cycles to achieve the desired delay: @@ -35,21 +36,26 @@ ATOMIC CONTEXT: be refactored to allow for the use of msleep. 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 work correctly, using the "right" sleep function will help the scheduler, power management, and just make your driver better :) -- Backed by busy-wait loop: + udelay(unsigned long usecs) + -- Backed by hrtimers: + usleep_range(unsigned long min, unsigned long max) + -- Backed by jiffies / legacy_timers + msleep(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 quirks you should be aware of. @@ -70,6 +76,7 @@ NON-ATOMIC CONTEXT: - Why not msleep for (1ms - 20ms)? Explained originally here: http://lkml.org/lkml/2007/8/3/250 + msleep(1~20) may not do what the caller intends, and will often sleep longer (~20 ms actual sleep for any value given in the 1~20ms range). In many cases this diff --git a/MAINTAINERS b/MAINTAINERS index 5fe44d5d82b4f3fd05e1b9816b0e307349fd01fb..0db7f12439f7655199b86de366cc96b331ae9ccb 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7192,7 +7192,7 @@ F: drivers/net/ethernet/hp/hp100.* HPET: High Precision Event Timers driver M: Clemens Ladisch S: Maintained -F: Documentation/timers/hpet.txt +F: Documentation/timers/hpet.rst F: drivers/char/hpet.c F: include/linux/hpet.h F: include/uapi/linux/hpet.h diff --git a/drivers/media/usb/dvb-usb-v2/anysee.c b/drivers/media/usb/dvb-usb-v2/anysee.c index 48fb0d41e03bbe2a99033b536342654925f9d237..fb6d99dea31aa878bfb0f15d186b9d97670c77b7 100644 --- a/drivers/media/usb/dvb-usb-v2/anysee.c +++ b/drivers/media/usb/dvb-usb-v2/anysee.c @@ -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 * (EPIPE, Broken pipe). Function supports currently msleep() as a * 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 * better choice as not to add unwanted delays... * Fixing that correctly is one of those or both; diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c index c894cf0d8a2840fe9745eda801db3adc4cdc9360..c5d8996d51653e53a0d4810a2b084bcf3a451f24 100644 --- a/drivers/regulator/core.c +++ b/drivers/regulator/core.c @@ -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: * - * Documentation/timers/timers-howto.txt + * Documentation/timers/timers-howto.rst * * The assumption here is that regulators will never be enabled in * atomic context and therefore sleeping functions can be used. diff --git a/include/linux/iopoll.h b/include/linux/iopoll.h index 3908353deec6a2c0306e772155e53aef29b7e511..35e15dfd41557d361ef5b64436957852b6b9192f 100644 --- a/include/linux/iopoll.h +++ b/include/linux/iopoll.h @@ -21,7 +21,7 @@ * @cond: Break condition (usually involving @val) * @sleep_us: Maximum time to sleep between reads in us (0 * 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 * * Returns 0 on success and -ETIMEDOUT upon a timeout. In either @@ -60,7 +60,7 @@ * @cond: Break condition (usually involving @val) * @delay_us: Time to udelay between reads in us (0 tight-loops). Should * 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 * * Returns 0 on success and -ETIMEDOUT upon a timeout. In either diff --git a/include/linux/regmap.h b/include/linux/regmap.h index daeec7dbd65c2d7912c8fe761559bef7bac1a777..ed5e9d0a1285eaf1affb678e015c1ac3a832cad5 100644 --- a/include/linux/regmap.h +++ b/include/linux/regmap.h @@ -112,7 +112,7 @@ struct reg_sequence { * @cond: Break condition (usually involving @val) * @sleep_us: Maximum time to sleep between reads in us (0 * 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 * * 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) * @sleep_us: Maximum time to sleep between reads in us (0 * 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 * * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index 342c7c781ba5a663d4cadb50ac7cd6b8d76dfd0b..a6d436809bf561f3604c1e7d1f4f42e8224ed376 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -5712,7 +5712,7 @@ sub process { # ignore udelay's < 10, however if (! ($delay < 10) ) { 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) { WARN("LONG_UDELAY", @@ -5724,7 +5724,7 @@ sub process { if ($line =~ /\bmsleep\s*\((\d+)\);/) { if ($1 < 20) { 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; if ($min eq $max) { 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+$/ && $min > $max) { 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"); } } diff --git a/sound/soc/sof/ops.h b/sound/soc/sof/ops.h index 80fc3b374c2b3bd27aa2198813c8c008136f78b0..8058a6c7308200281bdae378c7b79c816101bfc5 100644 --- a/sound/soc/sof/ops.h +++ b/sound/soc/sof/ops.h @@ -349,7 +349,7 @@ static inline const struct snd_sof_dsp_ops * @cond: Break condition (usually involving @val) * @sleep_us: Maximum time to sleep between reads in us (0 * 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 * * Returns 0 on success and -ETIMEDOUT upon a timeout. In either