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