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