Documentation/timers/timers-howto.rst

   1 ===================================================================
   2 delays - Information on the various kernel delay / sleep mechanisms
   3 ===================================================================
   4
   5 This document seeks to answer the common question: "What is the
   6 RightWay (TM) to insert a delay?"
   7
   8 This question is most often faced by driver writers who have to
   9 deal with hardware delays and who may not be the most intimately
  10 familiar with the inner workings of the Linux Kernel.
  11
  12
  13 Inserting Delays
  14 ----------------
  15
  16 The first, and most important, question you need to ask is "Is my
  17 code in an atomic context?"  This should be followed closely by "Does
  18 it really need to delay in atomic context?" If so...
  19
  20 ATOMIC 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
  38 NON-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