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	2	High resolution timers and dynamic ticks design notes
2		−-----------------------------------------------------
	3	+=====================================================
3	4
4	5	Further information can be found in the paper of the OLS 2006 talk "hrtimers
5	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	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	35	also figure #2 (OLS slides p. 15)
35	36
36	37	The main differences to the timer wheel, which holds the armed timer_list type
37	38	timers are:
	39	+
38	40	- time ordered enqueueing into a rb-tree
39	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	58	Further information about the Generic Time Of Day framework is available in the
57	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	63	The paper "We Are Not Getting Any Younger: A New Approach to Time and
61	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	104	The management layer assigns one or more of the following functions to a clock
102	105	event device:
	106	+
103	107	- system global periodic tick (jiffies update)
104	108	- cpu local update_process_times
105	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	248	available for MIPS and PowerPC.
245	249
246	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	5	The High Precision Event Timer (HPET) hardware follows a specification
4	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	2	hrtimers - subsystem for high-resolution kernel timers
3		−----------------------------------------------------
	3	+======================================================
4	4
5	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	146	a given clock has - be it low-res, high-res, or artificially-low-res.
147	147
148	148	hrtimers - testing and verification
149		−----------------------------------
	149	+-----------------------------------
150	150
151	151	We used the high-resolution clock subsystem ontop of hrtimers to verify
152	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

@@ -1,4 +1,6 @@
1		− NO_HZ: Reducing Scheduling-Clock Ticks
	1	+======================================
	2	+NO_HZ: Reducing Scheduling-Clock Ticks
	3	+======================================
2	4
3	5
4	6	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 · 23 unmodified lines
28	30	discussing testing, and a fifth and final section listing known issues.
29	31
30	32
31		−NEVER OMIT SCHEDULING-CLOCK TICKS
	33	+Never Omit Scheduling-Clock Ticks
	34	+=================================
32	35
33	36	Very old versions of Linux from the 1990s and the very early 2000s
34	37	are incapable of omitting scheduling-clock ticks. It turns out that
@@ -59,7 +62,8 @@ degrade your applications performance. If this describes your workload, · 24 unmodified lines
59	62	you should read the following two sections.
60	63
61	64
62		−OMIT SCHEDULING-CLOCK TICKS FOR IDLE CPUs
	65	+Omit Scheduling-Clock Ticks For Idle CPUs
	66	+=========================================
63	67
64	68	If a CPU is idle, there is little point in sending it a scheduling-clock
65	69	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 · 31 unmodified lines
97	101	dyntick-idle mode.
98	102
99	103
100		−OMIT SCHEDULING-CLOCK TICKS FOR CPUs WITH ONLY ONE RUNNABLE TASK
	104	+Omit Scheduling-Clock Ticks For CPUs With Only One Runnable Task
	105	+================================================================
101	106
102	107	If a CPU has only one runnable task, there is little point in sending it
103	108	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 · 70 unmodified lines
174	179	(yet) be enabled by default.
175	180
176	181
177		−RCU IMPLICATIONS
	182	+RCU Implications
	183	+================
178	184
179	185	There are situations in which idle CPUs cannot be permitted to
180	186	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 · 18 unmodified lines
199	205	where you want them to run.
200	206
201	207
202		−TESTING
	208	+Testing
	209	+=======
203	210
204	211	So you enable all the OS-jitter features described in this document,
205	212	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 · 16 unmodified lines
222	229	systems.
223	230
224	231
225		−KNOWN ISSUES
	232	+Known Issues
	233	+============
226	234
227		−o Dyntick-idle slows transitions to and from idle slightly.
	235	+* Dyntick-idle slows transitions to and from idle slightly.
228	236	In practice, this has not been a problem except for the most
229	237	aggressive real-time workloads, which have the option of disabling
230	238	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. · 17 unmodified lines
248	256	this parameter effectively disables Turbo Mode on Intel
249	257	CPUs, which can significantly reduce maximum performance.
250	258
251		−o Adaptive-ticks slows user/kernel transitions slightly.
	259	+* Adaptive-ticks slows user/kernel transitions slightly.
252	260	This is not expected to be a problem for computationally intensive
253	261	workloads, which have few such transitions. Careful benchmarking
254	262	will be required to determine whether or not other workloads
255	263	are significantly affected by this effect.
256	264
257		−o Adaptive-ticks does not do anything unless there is only one
	265	+* Adaptive-ticks does not do anything unless there is only one
258	266	runnable task for a given CPU, even though there are a number
259	267	of other situations where the scheduling-clock tick is not
260	268	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 · 14 unmodified lines
275	283
276	284	Better handling of these sorts of situations is future work.
277	285
278		−o A reboot is required to reconfigure both adaptive idle and RCU
	286	+* A reboot is required to reconfigure both adaptive idle and RCU
279	287	callback offloading. Runtime reconfiguration could be provided
280	288	if needed, however, due to the complexity of reconfiguring RCU at
281	289	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 · 1 unmodified line
283	291	simply offloading RCU callbacks from all CPUs and pinning them
284	292	where you want them whenever you want them pinned.
285	293
286		−o Additional configuration is required to deal with other sources
	294	+* Additional configuration is required to deal with other sources
287	295	of OS jitter, including interrupts and system-utility tasks
288	296	and processes. This configuration normally involves binding
289	297	interrupts and tasks to particular CPUs.
290	298
291		−o Some sources of OS jitter can currently be eliminated only by
	299	+* Some sources of OS jitter can currently be eliminated only by
292	300	constraining the workload. For example, the only way to eliminate
293	301	OS jitter due to global TLB shootdowns is to avoid the unmapping
294	302	operations (such as kernel module unload operations) that
@@ -299,17 +307,17 @@ o Some sources of OS jitter can currently be eliminated only by · 4 unmodified lines
299	307	helpful, especially when combined with the mlock() and mlockall()
300	308	system calls.
301	309
302		−o Unless all CPUs are idle, at least one CPU must keep the
	310	+* Unless all CPUs are idle, at least one CPU must keep the
303	311	scheduling-clock interrupt going in order to support accurate
304	312	timekeeping.
305	313
306		−o If there might potentially be some adaptive-ticks CPUs, there
	314	+* If there might potentially be some adaptive-ticks CPUs, there
307	315	will be at least one CPU keeping the scheduling-clock interrupt
308	316	going, even if all CPUs are otherwise idle.
309	317
310	318	Better handling of this situation is ongoing work.
311	319
312		−o Some process-handling operations still require the occasional
	320	+* Some process-handling operations still require the occasional
313	321	scheduling-clock tick. These operations include calculating CPU
314	322	load, maintaining sched average, computing CFS entity vruntime,
315	323	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	2	Clock sources, Clock events, sched_clock() and delay timers
2		−-----------------------------------------------------------
	3	+===========================================================
3	4
4	5	This document tries to briefly explain some basic kernel timekeeping
5	6	abstractions. It partly pertains to the drivers usually found in

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

@@ -1,5 +1,6 @@
	1	+===================================================================
1	2	delays - Information on the various kernel delay / sleep mechanisms
2		−-------------------------------------------------------------------
	3	+===================================================================
3	4
4	5	This document seeks to answer the common question: "What is the
5	6	RightWay (TM) to insert a delay?"
@@ -17,7 +18,7 @@ code in an atomic context?" This should be followed closely by "Does · 11 unmodified lines
17	18	it really need to delay in atomic context?" If so...
18	19
19	20	ATOMIC CONTEXT:
20		− You must use the *delay family of functions. These
	21	+ You must use the `*delay` family of functions. These
21	22	functions use the jiffie estimation of clock speed
22	23	and will busy wait for enough loop cycles to achieve
23	24	the desired delay:
@@ -35,21 +36,26 @@ ATOMIC CONTEXT: · 11 unmodified lines
35	36	be refactored to allow for the use of msleep.
36	37
37	38	NON-ATOMIC CONTEXT:
38		− You should use the *sleep[_range] family of functions.
	39	+ You should use the `*sleep[_range]` family of functions.
39	40	There are a few more options here, while any of them may
40	41	work correctly, using the "right" sleep function will
41	42	help the scheduler, power management, and just make your
42	43	driver better :)
43	44
44	45	-- Backed by busy-wait loop:
	46	+
45	47	udelay(unsigned long usecs)
	48	+
46	49	-- Backed by hrtimers:
	50	+
47	51	usleep_range(unsigned long min, unsigned long max)
	52	+
48	53	-- Backed by jiffies / legacy_timers
	54	+
49	55	msleep(unsigned long msecs)
50	56	msleep_interruptible(unsigned long msecs)
51	57
52		− Unlike the *delay family, the underlying mechanism
	58	+ Unlike the `*delay` family, the underlying mechanism
53	59	driving each of these calls varies, thus there are
54	60	quirks you should be aware of.
55	61
@@ -70,6 +76,7 @@ NON-ATOMIC CONTEXT: · 14 unmodified lines
70	76	- Why not msleep for (1ms - 20ms)?
71	77	Explained originally here:
72	78	http://lkml.org/lkml/2007/8/3/250
	79	+
73	80	msleep(1~20) may not do what the caller intends, and
74	81	will often sleep longer (~20 ms actual sleep for any
75	82	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	7192	HPET: High Precision Event Timers driver
7193	7193	M: Clemens Ladisch <clemens@ladisch.de>
7194	7194	S: Maintained
7195		−F: Documentation/timers/hpet.txt
	7195	+F: Documentation/timers/hpet.rst
7196	7196	F: drivers/char/hpet.c
7197	7197	F: include/linux/hpet.h
7198	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	56	/* TODO FIXME: dvb_usb_generic_rw() fails rarely with error code -32
57	57	* (EPIPE, Broken pipe). Function supports currently msleep() as a
58	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	60	* short, under < 20ms, sleeps. Repeating failed message would be
61	61	* better choice as not to add unwanted delays...
62	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	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	2309	* The assumption here is that regulators will never be enabled in
2310	2310	* atomic context and therefore sleeping functions can be used.

include/linux/iopoll.h+2−2

@@ -21,7 +21,7 @@ · 20 unmodified lines
21	21	* @cond: Break condition (usually involving @val)
22	22	* @sleep_us: Maximum time to sleep between reads in us (0
23	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	25	* @timeout_us: Timeout in us, 0 means never timeout
26	26	*
27	27	* Returns 0 on success and -ETIMEDOUT upon a timeout. In either
@@ -60,7 +60,7 @@ · 32 unmodified lines
60	60	* @cond: Break condition (usually involving @val)
61	61	* @delay_us: Time to udelay between reads in us (0 tight-loops). Should
62	62	* be less than ~10us since udelay is used (see
63		− * Documentation/timers/timers-howto.txt).
	63	+ * Documentation/timers/timers-howto.rst).
64	64	* @timeout_us: Timeout in us, 0 means never timeout
65	65	*
66	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	112	* @cond: Break condition (usually involving @val)
113	113	* @sleep_us: Maximum time to sleep between reads in us (0
114	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	116	* @timeout_us: Timeout in us, 0 means never timeout
117	117	*
118	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	154	* @cond: Break condition (usually involving @val)
155	155	* @sleep_us: Maximum time to sleep between reads in us (0
156	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	158	* @timeout_us: Timeout in us, 0 means never timeout
159	159	*
160	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	5712	# ignore udelay's < 10, however
5713	5713	if (! ($delay < 10) ) {
5714	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	5717	if ($delay > 2000) {
5718	5718	WARN("LONG_UDELAY",
@@ -5724,7 +5724,7 @@ sub process { · 5 unmodified lines
5724	5724	if ($line =~ /\bmsleep\s*$(\d+)$;/) {
5725	5725	if ($1 < 20) {
5726	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	6115	my $max = $7;
6116	6116	if ($min eq $max) {
6117	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	6119	} elsif ($min =~ /^\d+$/ && $max =~ /^\d+$/ &&
6120	6120	$min > $max) {
6121	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	349	* @cond: Break condition (usually involving @val)
350	350	* @sleep_us: Maximum time to sleep between reads in us (0
351	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	353	* @timeout_us: Timeout in us, 0 means never timeout
354	354	*
355	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