forked from Minki/linux
c6af13d334
Sleeping for a certain amount of time requires use of different functions, depending on the time period. Documentation/timers/timers-howto.rst explains when to use which function, and also checkpatch checks for some potentially problematic cases. So let's create a helper that automatically chooses the appropriate sleep function -> fsleep(), for flexible sleeping If the delay is a constant, then the compiler should be able to ensure that the new helper doesn't create overhead. If the delay is not constant, then the new helper can save some code. Signed-off-by: Heiner Kallweit <hkallweit1@gmail.com> Signed-off-by: David S. Miller <davem@davemloft.net>
116 lines
3.9 KiB
ReStructuredText
116 lines
3.9 KiB
ReStructuredText
===================================================================
|
|
delays - Information on the various kernel delay / sleep mechanisms
|
|
===================================================================
|
|
|
|
This document seeks to answer the common question: "What is the
|
|
RightWay (TM) to insert a delay?"
|
|
|
|
This question is most often faced by driver writers who have to
|
|
deal with hardware delays and who may not be the most intimately
|
|
familiar with the inner workings of the Linux Kernel.
|
|
|
|
|
|
Inserting Delays
|
|
----------------
|
|
|
|
The first, and most important, question you need to ask is "Is my
|
|
code in an atomic context?" This should be followed closely by "Does
|
|
it really need to delay in atomic context?" If so...
|
|
|
|
ATOMIC CONTEXT:
|
|
You must use the `*delay` family of functions. These
|
|
functions use the jiffie estimation of clock speed
|
|
and will busy wait for enough loop cycles to achieve
|
|
the desired delay:
|
|
|
|
ndelay(unsigned long nsecs)
|
|
udelay(unsigned long usecs)
|
|
mdelay(unsigned long msecs)
|
|
|
|
udelay is the generally preferred API; ndelay-level
|
|
precision may not actually exist on many non-PC devices.
|
|
|
|
mdelay is macro wrapper around udelay, to account for
|
|
possible overflow when passing large arguments to udelay.
|
|
In general, use of mdelay is discouraged and code should
|
|
be 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 may
|
|
work correctly, using the "right" sleep function will
|
|
help the scheduler, power management, and just make your
|
|
driver 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_timers
|
|
|
|
msleep(unsigned long msecs)
|
|
msleep_interruptible(unsigned long msecs)
|
|
|
|
Unlike the `*delay` family, the underlying mechanism
|
|
driving each of these calls varies, thus there are
|
|
quirks 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 hrtimers
|
|
for usleep *may* not be worth it. Such an evaluation
|
|
will obviously depend on your specific situation, but
|
|
it 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/250
|
|
|
|
msleep(1~20) may not do what the caller intends, and
|
|
will often sleep longer (~20 ms actual sleep for any
|
|
value given in the 1~20ms range). In many cases this
|
|
is not the desired behavior.
|
|
|
|
- Why is there no "usleep" / What is a good range?
|
|
Since usleep_range is built on top of hrtimers, the
|
|
wakeup will be very precise (ish), thus a simple
|
|
usleep function would likely introduce a large number
|
|
of undesired interrupts.
|
|
|
|
With the introduction of a range, the scheduler is
|
|
free to coalesce your wakeup with any other wakeup
|
|
that may have happened for other reasons, or at the
|
|
worst case, fire an interrupt for your upper bound.
|
|
|
|
The larger a range you supply, the greater a chance
|
|
that you will not trigger an interrupt; this should
|
|
be balanced with what is an acceptable upper bound on
|
|
delay / performance for your specific code path. Exact
|
|
tolerances here are very situation specific, thus it
|
|
is 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_UNINTERRUPTIBLE
|
|
whereas msleep_interruptible sets the current task to
|
|
TASK_INTERRUPTIBLE before scheduling the sleep. In
|
|
short, the difference is whether the sleep can be ended
|
|
early by a signal. In general, just use msleep unless
|
|
you know you have a need for the interruptible variant.
|
|
|
|
FLEXIBLE SLEEPING (any delay, uninterruptible)
|
|
* Use fsleep
|