1 ============================================== 1 ===================================================================
2 delays - Information on the various kernel del 2 delays - Information on the various kernel delay / sleep mechanisms
3 ============================================== 3 ===================================================================
4 4
5 This document seeks to answer the common quest 5 This document seeks to answer the common question: "What is the
6 RightWay (TM) to insert a delay?" 6 RightWay (TM) to insert a delay?"
7 7
8 This question is most often faced by driver wr 8 This question is most often faced by driver writers who have to
9 deal with hardware delays and who may not be t 9 deal with hardware delays and who may not be the most intimately
10 familiar with the inner workings of the Linux 10 familiar with the inner workings of the Linux Kernel.
11 11
12 12
13 Inserting Delays 13 Inserting Delays
14 ---------------- 14 ----------------
15 15
16 The first, and most important, question you ne 16 The first, and most important, question you need to ask is "Is my
17 code in an atomic context?" This should be fo 17 code in an atomic context?" This should be followed closely by "Does
18 it really need to delay in atomic context?" If 18 it really need to delay in atomic context?" If so...
19 19
20 ATOMIC CONTEXT: 20 ATOMIC CONTEXT:
21 You must use the `*delay` family of fu 21 You must use the `*delay` family of functions. These
22 functions use the jiffy estimation of 22 functions use the jiffy estimation of clock speed
23 and will busy wait for enough loop cyc 23 and will busy wait for enough loop cycles to achieve
24 the desired delay: 24 the desired delay:
25 25
26 ndelay(unsigned long nsecs) 26 ndelay(unsigned long nsecs)
27 udelay(unsigned long usecs) 27 udelay(unsigned long usecs)
28 mdelay(unsigned long msecs) 28 mdelay(unsigned long msecs)
29 29
30 udelay is the generally preferred API; 30 udelay is the generally preferred API; ndelay-level
31 precision may not actually exist on ma 31 precision may not actually exist on many non-PC devices.
32 32
33 mdelay is macro wrapper around udelay, 33 mdelay is macro wrapper around udelay, to account for
34 possible overflow when passing large a 34 possible overflow when passing large arguments to udelay.
35 In general, use of mdelay is discourag 35 In general, use of mdelay is discouraged and code should
36 be refactored to allow for the use of 36 be refactored to allow for the use of msleep.
37 37
38 NON-ATOMIC CONTEXT: 38 NON-ATOMIC CONTEXT:
39 You should use the `*sleep[_range]` fa 39 You should use the `*sleep[_range]` family of functions.
40 There are a few more options here, whi 40 There are a few more options here, while any of them may
41 work correctly, using the "right" slee 41 work correctly, using the "right" sleep function will
42 help the scheduler, power management, 42 help the scheduler, power management, and just make your
43 driver better :) 43 driver better :)
44 44
45 -- Backed by busy-wait loop: 45 -- Backed by busy-wait loop:
46 46
47 udelay(unsigned long usecs) 47 udelay(unsigned long usecs)
48 48
49 -- Backed by hrtimers: 49 -- Backed by hrtimers:
50 50
51 usleep_range(unsigned long min 51 usleep_range(unsigned long min, unsigned long max)
52 52
53 -- Backed by jiffies / legacy_timers 53 -- Backed by jiffies / legacy_timers
54 54
55 msleep(unsigned long msecs) 55 msleep(unsigned long msecs)
56 msleep_interruptible(unsigned 56 msleep_interruptible(unsigned long msecs)
57 57
58 Unlike the `*delay` family, the underl 58 Unlike the `*delay` family, the underlying mechanism
59 driving each of these calls varies, th 59 driving each of these calls varies, thus there are
60 quirks you should be aware of. 60 quirks you should be aware of.
61 61
62 62
63 SLEEPING FOR "A FEW" USECS ( < ~10us? 63 SLEEPING FOR "A FEW" USECS ( < ~10us? ):
64 * Use udelay 64 * Use udelay
65 65
66 - Why not usleep? 66 - Why not usleep?
67 On slower systems, (em 67 On slower systems, (embedded, OR perhaps a speed-
68 stepped PC!) the overh 68 stepped PC!) the overhead of setting up the hrtimers
69 for usleep *may* not b 69 for usleep *may* not be worth it. Such an evaluation
70 will obviously depend 70 will obviously depend on your specific situation, but
71 it is something to be 71 it is something to be aware of.
72 72
73 SLEEPING FOR ~USECS OR SMALL MSECS ( 1 73 SLEEPING FOR ~USECS OR SMALL MSECS ( 10us - 20ms):
74 * Use usleep_range 74 * Use usleep_range
75 75
76 - Why not msleep for (1ms - 20 76 - Why not msleep for (1ms - 20ms)?
77 Explained originally h 77 Explained originally here:
78 https://lore.k 78 https://lore.kernel.org/r/15327.1186166232@lwn.net
79 79
80 msleep(1~20) may not d 80 msleep(1~20) may not do what the caller intends, and
81 will often sleep longe 81 will often sleep longer (~20 ms actual sleep for any
82 value given in the 1~2 82 value given in the 1~20ms range). In many cases this
83 is not the desired beh 83 is not the desired behavior.
84 84
85 - Why is there no "usleep" / W 85 - Why is there no "usleep" / What is a good range?
86 Since usleep_range is 86 Since usleep_range is built on top of hrtimers, the
87 wakeup will be very pr 87 wakeup will be very precise (ish), thus a simple
88 usleep function would 88 usleep function would likely introduce a large number
89 of undesired interrupt 89 of undesired interrupts.
90 90
91 With the introduction 91 With the introduction of a range, the scheduler is
92 free to coalesce your 92 free to coalesce your wakeup with any other wakeup
93 that may have happened 93 that may have happened for other reasons, or at the
94 worst case, fire an in 94 worst case, fire an interrupt for your upper bound.
95 95
96 The larger a range you 96 The larger a range you supply, the greater a chance
97 that you will not trig 97 that you will not trigger an interrupt; this should
98 be balanced with what 98 be balanced with what is an acceptable upper bound on
99 delay / performance fo 99 delay / performance for your specific code path. Exact
100 tolerances here are ve 100 tolerances here are very situation specific, thus it
101 is left to the caller 101 is left to the caller to determine a reasonable range.
102 102
103 SLEEPING FOR LARGER MSECS ( 10ms+ ) 103 SLEEPING FOR LARGER MSECS ( 10ms+ )
104 * Use msleep or possibly mslee 104 * Use msleep or possibly msleep_interruptible
105 105
106 - What's the difference? 106 - What's the difference?
107 msleep sets the curren 107 msleep sets the current task to TASK_UNINTERRUPTIBLE
108 whereas msleep_interru 108 whereas msleep_interruptible sets the current task to
109 TASK_INTERRUPTIBLE bef 109 TASK_INTERRUPTIBLE before scheduling the sleep. In
110 short, the difference 110 short, the difference is whether the sleep can be ended
111 early by a signal. In 111 early by a signal. In general, just use msleep unless
112 you know you have a ne 112 you know you have a need for the interruptible variant.
113 113
114 FLEXIBLE SLEEPING (any delay, uninterr 114 FLEXIBLE SLEEPING (any delay, uninterruptible)
115 * Use fsleep 115 * Use fsleep
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.