1===================================================================
  2delays - Information on the various kernel delay / sleep mechanisms
  3===================================================================
  4
  5This document seeks to answer the common question: "What is the
  6RightWay (TM) to insert a delay?"
  7
  8This question is most often faced by driver writers who have to
  9deal with hardware delays and who may not be the most intimately
 10familiar with the inner workings of the Linux Kernel.
 11
 12
 13Inserting Delays
 14----------------
 15
 16The first, and most important, question you need to ask is "Is my
 17code in an atomic context?"  This should be followed closely by "Does
 18it really need to delay in atomic context?" If so...
 19
 20ATOMIC CONTEXT:
 21	You must use the `*delay` family of functions. These
 22	functions use the jiffie estimation of clock speed
 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)
 28	mdelay(unsigned long msecs)
 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
 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 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:
 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_timers
 54
 55		msleep(unsigned long msecs)
 56		msleep_interruptible(unsigned long msecs)
 57
 58	Unlike the `*delay` family, the underlying mechanism
 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:
 78				https://lore.kernel.org/r/15327.1186166232@lwn.net
 79
 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.
113
114	FLEXIBLE SLEEPING (any delay, uninterruptible)
115		* Use fsleep