delays - Information on the various kernel delay / sleep mechanisms

delays - Information on the various kernel delay / sleep mechanisms-------------------------------------------------------------------This document seeks to answer the common question: "What is theRightWay (TM) to insert a delay?"This question is most often faced by driver writers who have todeal with hardware delays and who may not be the most intimatelyfamiliar with the inner workings of the Linux Kernel.Inserting Delays----------------The first, and most important, question you need to ask is "Is mycode in an atomic context?"  This should be followed closely by "Doesit really need to delay in atomic context?" If so...ATOMIC CONTEXT:You must use the *delay family of functions. Thesefunctions use the jiffie estimation of clock speedand will busy wait for enough loop cycles to achievethe desired delay:ndelay(unsigned long nsecs)udelay(unsigned long usecs)mdelay(unsigned long msecs)udelay is the generally preferred API; ndelay-levelprecision may not actually exist on many non-PC devices.mdelay is macro wrapper around udelay, to account forpossible overflow when passing large arguments to udelay.In general, use of mdelay is discouraged and code shouldbe refactored to allow for the use of msleep.NON-ATOMIC CONTEXT:You should use the *sleep[_range] family of functions.There are a few more options here, while any of them maywork correctly, using the "right" sleep function willhelp the scheduler, power management, and just make yourdriver better :)-- Backed by busy-wait loop:udelay(unsigned long usecs)-- Backed by hrtimers:usleep_range(unsigned long min, unsigned long max)-- Backed by jiffies / legacy_timersmsleep(unsigned long msecs)msleep_interruptible(unsigned long msecs)Unlike the *delay family, the underlying mechanismdriving each of these calls varies, thus there arequirks you should be aware of.SLEEPING FOR "A FEW" USECS ( < ~10us? ):* Use udelay- Why not usleep?On slower systems, (embedded, OR perhaps a speed-stepped PC!) the overhead of setting up the hrtimersfor usleep *may* not be worth it. Such an evaluationwill obviously depend on your specific situation, butit is something to be aware of.SLEEPING FOR ~USECS OR SMALL MSECS ( 10us - 20ms):* Use usleep_range- Why not msleep for (1ms - 20ms)?Explained originally here:http://lkml.org/lkml/2007/8/3/250msleep(1~20) may not do what the caller intends, andwill often sleep longer (~20 ms actual sleep for anyvalue given in the 1~20ms range). In many cases thisis not the desired behavior.- Why is there no "usleep" / What is a good range?Since usleep_range is built on top of hrtimers, thewakeup will be very precise (ish), thus a simpleusleep function would likely introduce a large numberof undesired interrupts.With the introduction of a range, the scheduler isfree to coalesce your wakeup with any other wakeupthat may have happened for other reasons, or at theworst case, fire an interrupt for your upper bound.The larger a range you supply, the greater a chancethat you will not trigger an interrupt; this shouldbe balanced with what is an acceptable upper bound ondelay / performance for your specific code path. Exacttolerances here are very situation specific, thus itis left to the caller to determine a reasonable range.SLEEPING FOR LARGER MSECS ( 10ms+ )* Use msleep or possibly msleep_interruptible- What's the difference?msleep sets the current task to TASK_UNINTERRUPTIBLEwhereas msleep_interruptible sets the current task toTASK_INTERRUPTIBLE before scheduling the sleep. Inshort, the difference is whether the sleep can be endedearly by a signal. In general, just use msleep unlessyou know you have a need for the interruptible variant.