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.

Mauro Carvalho Chehab committed 7 years ago

Commit 458f69e1 parent 4ca9bc214 files · +84 −43Browse files

Unified · Split

14 files

Documentation/timers/highres.rst +7 −6
Documentation/timers/hpet.rst +3 −1
Documentation/timers/hrtimers.rst +3 −3
Documentation/timers/index.rst +22 −0
Documentation/timers/no_hz.rst +24 −16
Documentation/timers/timekeeping.rst +2 −1
Documentation/timers/timers-howto.rst +11 −4
MAINTAINERS +1 −1
drivers/media/usb/dvb-usb-v2/anysee.c +1 −1
drivers/regulator/core.c +1 −1
include/linux/iopoll.h +2 −2
include/linux/regmap.h +2 −2
scripts/checkpatch.pl +4 −4
sound/soc/sof/ops.h +1 −1

Documentation/timers/highres.rstrenamed from Documentation/timers/highres.txt+7−6

@@ -1,5 +1,6 @@
		1	=====================================================
1	High resolution timers and dynamic ticks design notes	2	High resolution timers and dynamic ticks design notes
2	-----------------------------------------------------	3	=====================================================
3		4
4	Further information can be found in the paper of the OLS 2006 talk "hrtimers	5	Further information can be found in the paper of the OLS 2006 talk "hrtimers
5	and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can	6	and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
@@ -30,11 +31,12 @@ hrtimer base infrastructure · 24 unmodified lines
30	---------------------------	31	---------------------------
31		32
32	The hrtimer base infrastructure was merged into the 2.6.16 kernel. Details of	33	The hrtimer base infrastructure was merged into the 2.6.16 kernel. Details of
33	the base implementation are covered in Documentation/timers/hrtimers.txt. See	34	the base implementation are covered in Documentation/timers/hrtimers.rst. See
34	also figure #2 (OLS slides p. 15)	35	also figure #2 (OLS slides p. 15)
35		36
36	The main differences to the timer wheel, which holds the armed timer_list type	37	The main differences to the timer wheel, which holds the armed timer_list type
37	timers are:	38	timers are:
		39
38	- time ordered enqueueing into a rb-tree	40	- time ordered enqueueing into a rb-tree
39	- independent of ticks (the processing is based on nanoseconds)	41	- independent of ticks (the processing is based on nanoseconds)
40		42
@@ -55,7 +57,8 @@ merged into the 2.6.18 kernel. · 14 unmodified lines
55		57
56	Further information about the Generic Time Of Day framework is available in the	58	Further information about the Generic Time Of Day framework is available in the
57	OLS 2005 Proceedings Volume 1:	59	OLS 2005 Proceedings Volume 1:
58	http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf	60
		61	http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
59		62
60	The paper "We Are Not Getting Any Younger: A New Approach to Time and	63	The paper "We Are Not Getting Any Younger: A New Approach to Time and
61	Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan.	64	Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan.
@@ -100,6 +103,7 @@ accounting, profiling, and high resolution timers. · 38 unmodified lines
100		103
101	The management layer assigns one or more of the following functions to a clock	104	The management layer assigns one or more of the following functions to a clock
102	event device:	105	event device:
		106
103	- system global periodic tick (jiffies update)	107	- system global periodic tick (jiffies update)
104	- cpu local update_process_times	108	- cpu local update_process_times
105	- cpu local profiling	109	- cpu local profiling
@@ -244,6 +248,3 @@ extended to x86_64 and ARM already. Initial (work in progress) support is also · 138 unmodified lines
244	available for MIPS and PowerPC.	248	available for MIPS and PowerPC.
245		249
246	Thomas, Ingo	250	Thomas, Ingo
247
248
249

Documentation/timers/hpet.rstrenamed from Documentation/timers/hpet.txt+3−1

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

Documentation/timers/hrtimers.rstrenamed from Documentation/timers/hrtimers.txt+3−3

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

Documentation/timers/index.rst+22−0

@@ -0,0 +1,22 @@
	1	:orphan:
	2
	3	======
	4	timers
	5	======
	6
	7	.. toctree::
	8	:maxdepth: 1
	9
	10	highres
	11	hpet
	12	hrtimers
	13	no_hz
	14	timekeeping
	15	timers-howto
	16
	17	.. only:: subproject and html
	18
	19	Indices
	20	=======
	21
	22	* :ref:`genindex`

Documentation/timers/no_hz.rstrenamed from Documentation/timers/NO_HZ.txt+24−16

-		NO_HZ: Reducing Scheduling-Clock Ticks
+======================================
+NO_HZ: Reducing Scheduling-Clock Ticks
+======================================
 This document describes Kconfig options and boot parameters that can
 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
 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
 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.
 (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
 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
 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,
 		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
 	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.
 	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
 	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

Documentation/timers/timekeeping.rstrenamed from Documentation/timers/timekeeping.txt+2−1

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

Documentation/timers/timers-howto.rstrenamed from Documentation/timers/timers-howto.txt+11−4

+===================================================================
 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?"
 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:
 	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.
 		- 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

MAINTAINERS+1−1

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

drivers/media/usb/dvb-usb-v2/anysee.c+1−1

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

drivers/regulator/core.c+1−1

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

include/linux/iopoll.h+2−2

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

include/linux/regmap.h+2−2

@@ -112,7 +112,7 @@ struct reg_sequence { · 111 unmodified lines
112	* @cond: Break condition (usually involving @val)	112	* @cond: Break condition (usually involving @val)
113	* @sleep_us: Maximum time to sleep between reads in us (0	113	* @sleep_us: Maximum time to sleep between reads in us (0
114	* tight-loops). Should be less than ~20ms since usleep_range	114	* tight-loops). Should be less than ~20ms since usleep_range
115	* is used (see Documentation/timers/timers-howto.txt).	115	* is used (see Documentation/timers/timers-howto.rst).
116	* @timeout_us: Timeout in us, 0 means never timeout	116	* @timeout_us: Timeout in us, 0 means never timeout
117	*	117	*
118	* Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read	118	* Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
@@ -154,7 +154,7 @@ struct reg_sequence { · 35 unmodified lines
154	* @cond: Break condition (usually involving @val)	154	* @cond: Break condition (usually involving @val)
155	* @sleep_us: Maximum time to sleep between reads in us (0	155	* @sleep_us: Maximum time to sleep between reads in us (0
156	* tight-loops). Should be less than ~20ms since usleep_range	156	* tight-loops). Should be less than ~20ms since usleep_range
157	* is used (see Documentation/timers/timers-howto.txt).	157	* is used (see Documentation/timers/timers-howto.rst).
158	* @timeout_us: Timeout in us, 0 means never timeout	158	* @timeout_us: Timeout in us, 0 means never timeout
159	*	159	*
160	* Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read	160	* Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read

scripts/checkpatch.pl+4−4

@@ -5712,7 +5712,7 @@ sub process { · 5711 unmodified lines
5712	# ignore udelay's < 10, however	5712	# ignore udelay's < 10, however
5713	if (! ($delay < 10) ) {	5713	if (! ($delay < 10) ) {
5714	CHK("USLEEP_RANGE",	5714	CHK("USLEEP_RANGE",
5715	"usleep_range is preferred over udelay; see Documentation/timers/timers-howto.txt\n" . $herecurr);	5715	"usleep_range is preferred over udelay; see Documentation/timers/timers-howto.rst\n" . $herecurr);
5716	}	5716	}
5717	if ($delay > 2000) {	5717	if ($delay > 2000) {
5718	WARN("LONG_UDELAY",	5718	WARN("LONG_UDELAY",
@@ -5724,7 +5724,7 @@ sub process { · 5 unmodified lines
5724	if ($line =~ /\bmsleep\s*$(\d+)$;/) {	5724	if ($line =~ /\bmsleep\s*$(\d+)$;/) {
5725	if ($1 < 20) {	5725	if ($1 < 20) {
5726	WARN("MSLEEP",	5726	WARN("MSLEEP",
5727	"msleep < 20ms can sleep for up to 20ms; see Documentation/timers/timers-howto.txt\n" . $herecurr);	5727	"msleep < 20ms can sleep for up to 20ms; see Documentation/timers/timers-howto.rst\n" . $herecurr);
5728	}	5728	}
5729	}	5729	}
5730		5730
@@ -6115,11 +6115,11 @@ sub process { · 384 unmodified lines
6115	my $max = $7;	6115	my $max = $7;
6116	if ($min eq $max) {	6116	if ($min eq $max) {
6117	WARN("USLEEP_RANGE",	6117	WARN("USLEEP_RANGE",
6118	"usleep_range should not use min == max args; see Documentation/timers/timers-howto.txt\n" . "$here\n$stat\n");	6118	"usleep_range should not use min == max args; see Documentation/timers/timers-howto.rst\n" . "$here\n$stat\n");
6119	} elsif ($min =~ /^\d+$/ && $max =~ /^\d+$/ &&	6119	} elsif ($min =~ /^\d+$/ && $max =~ /^\d+$/ &&
6120	$min > $max) {	6120	$min > $max) {
6121	WARN("USLEEP_RANGE",	6121	WARN("USLEEP_RANGE",
6122	"usleep_range args reversed, use min then max; see Documentation/timers/timers-howto.txt\n" . "$here\n$stat\n");	6122	"usleep_range args reversed, use min then max; see Documentation/timers/timers-howto.rst\n" . "$here\n$stat\n");
6123	}	6123	}
6124	}	6124	}
6125		6125

sound/soc/sof/ops.h+1−1

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

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

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code