116 lines · plain
1===================================================================2delays - Information on the various kernel delay / sleep mechanisms3===================================================================4 5This document seeks to answer the common question: "What is the6RightWay (TM) to insert a delay?"7 8This question is most often faced by driver writers who have to9deal with hardware delays and who may not be the most intimately10familiar with the inner workings of the Linux Kernel.11 12 13Inserting Delays14----------------15 16The first, and most important, question you need to ask is "Is my17code in an atomic context?" This should be followed closely by "Does18it really need to delay in atomic context?" If so...19 20ATOMIC CONTEXT:21 You must use the `*delay` family of functions. These22 functions use the jiffy estimation of clock speed23 and will busy wait for enough loop cycles to achieve24 the desired delay:25 26 ndelay(unsigned long nsecs)27 udelay(unsigned long usecs)28 mdelay(unsigned long msecs)29 30 udelay is the generally preferred API; ndelay-level31 precision may not actually exist on many non-PC devices.32 33 mdelay is macro wrapper around udelay, to account for34 possible overflow when passing large arguments to udelay.35 In general, use of mdelay is discouraged and code should36 be refactored to allow for the use of msleep.37 38NON-ATOMIC CONTEXT:39 You should use the `*sleep[_range]` family of functions.40 There are a few more options here, while any of them may41 work correctly, using the "right" sleep function will42 help the scheduler, power management, and just make your43 driver better :)44 45 -- Backed by busy-wait loop:46 47 udelay(unsigned long usecs)48 49 -- Backed by hrtimers:50 51 usleep_range(unsigned long min, unsigned long max)52 53 -- Backed by jiffies / legacy_timers54 55 msleep(unsigned long msecs)56 msleep_interruptible(unsigned long msecs)57 58 Unlike the `*delay` family, the underlying mechanism59 driving each of these calls varies, thus there are60 quirks you should be aware of.61 62 63 SLEEPING FOR "A FEW" USECS ( < ~10us? ):64 * Use udelay65 66 - Why not usleep?67 On slower systems, (embedded, OR perhaps a speed-68 stepped PC!) the overhead of setting up the hrtimers69 for usleep *may* not be worth it. Such an evaluation70 will obviously depend on your specific situation, but71 it is something to be aware of.72 73 SLEEPING FOR ~USECS OR SMALL MSECS ( 10us - 20ms):74 * Use usleep_range75 76 - Why not msleep for (1ms - 20ms)?77 Explained originally here:78 https://lore.kernel.org/r/15327.1186166232@lwn.net79 80 msleep(1~20) may not do what the caller intends, and81 will often sleep longer (~20 ms actual sleep for any82 value given in the 1~20ms range). In many cases this83 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, the87 wakeup will be very precise (ish), thus a simple88 usleep function would likely introduce a large number89 of undesired interrupts.90 91 With the introduction of a range, the scheduler is92 free to coalesce your wakeup with any other wakeup93 that may have happened for other reasons, or at the94 worst case, fire an interrupt for your upper bound.95 96 The larger a range you supply, the greater a chance97 that you will not trigger an interrupt; this should98 be balanced with what is an acceptable upper bound on99 delay / performance for your specific code path. Exact100 tolerances here are very situation specific, thus it101 is left to the caller to determine a reasonable range.102 103 SLEEPING FOR LARGER MSECS ( 10ms+ )104 * Use msleep or possibly msleep_interruptible105 106 - What's the difference?107 msleep sets the current task to TASK_UNINTERRUPTIBLE108 whereas msleep_interruptible sets the current task to109 TASK_INTERRUPTIBLE before scheduling the sleep. In110 short, the difference is whether the sleep can be ended111 early by a signal. In general, just use msleep unless112 you know you have a need for the interruptible variant.113 114 FLEXIBLE SLEEPING (any delay, uninterruptible)115 * Use fsleep116