Documentation/timers/delay_sleep_functions.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Delay and sleep mechanisms
   4 ==========================
   5
   6 This document seeks to answer the common question: "What is the
   7 RightWay (TM) to insert a delay?"
   8
   9 This question is most often faced by driver writers who have to
  10 deal with hardware delays and who may not be the most intimately
  11 familiar with the inner workings of the Linux Kernel.
  12
  13 The following table gives a rough overview about the existing function
  14 'families' and their limitations. This overview table does not replace the
  15 reading of the function description before usage!
  16
  17 .. list-table::
  18    :widths: 20 20 20 20 20
  19    :header-rows: 2
  20
  21    * -
  22      - `*delay()`
  23      - `usleep_range*()`
  24      - `*sleep()`
  25      - `fsleep()`
  26    * -
  27      - busy-wait loop
  28      - hrtimers based
  29      - timer list timers based
  30      - combines the others
  31    * - Usage in atomic Context
  32      - yes
  33      - no
  34      - no
  35      - no
  36    * - precise on "short intervals"
  37      - yes
  38      - yes
  39      - depends
  40      - yes
  41    * - precise on "long intervals"
  42      - Do not use!
  43      - yes
  44      - max 12.5% slack
  45      - yes
  46    * - interruptible variant
  47      - no
  48      - yes
  49      - yes
  50      - no
  51
  52 A generic advice for non atomic contexts could be:
  53
  54 #. Use `fsleep()` whenever unsure (as it combines all the advantages of the
  55    others)
  56 #. Use `*sleep()` whenever possible
  57 #. Use `usleep_range*()` whenever accuracy of `*sleep()` is not sufficient
  58 #. Use `*delay()` for very, very short delays
  59
  60 Find some more detailed information about the function 'families' in the next
  61 sections.
  62
  63 `*delay()` family of functions
  64 ------------------------------
  65
  66 These functions use the jiffy estimation of clock speed and will busy wait for
  67 enough loop cycles to achieve the desired delay. udelay() is the basic
  68 implementation and ndelay() as well as mdelay() are variants.
  69
  70 These functions are mainly used to add a delay in atomic context. Please make
  71 sure to ask yourself before adding a delay in atomic context: Is this really
  72 required?
  73
  74 .. kernel-doc:: include/asm-generic/delay.h
  75         :identifiers: udelay ndelay
  76
  77 .. kernel-doc:: include/linux/delay.h
  78         :identifiers: mdelay
  79
  80
  81 `usleep_range*()` and `*sleep()` family of functions
  82 ----------------------------------------------------
  83
  84 These functions use hrtimers or timer list timers to provide the requested
  85 sleeping duration. In order to decide which function is the right one to use,
  86 take some basic information into account:
  87
  88 #. hrtimers are more expensive as they are using an rb-tree (instead of hashing)
  89 #. hrtimers are more expensive when the requested sleeping duration is the first
  90    timer which means real hardware has to be programmed
  91 #. timer list timers always provide some sort of slack as they are jiffy based
  92
  93 The generic advice is repeated here:
  94
  95 #. Use `fsleep()` whenever unsure (as it combines all the advantages of the
  96    others)
  97 #. Use `*sleep()` whenever possible
  98 #. Use `usleep_range*()` whenever accuracy of `*sleep()` is not sufficient
  99
 100 First check fsleep() function description and to learn more about accuracy,
 101 please check msleep() function description.
 102
 103
 104 `usleep_range*()`
 105 ~~~~~~~~~~~~~~~~~
 106
 107 .. kernel-doc:: include/linux/delay.h
 108         :identifiers: usleep_range usleep_range_idle
 109
 110 .. kernel-doc:: kernel/time/sleep_timeout.c
 111         :identifiers: usleep_range_state
 112
 113
 114 `*sleep()`
 115 ~~~~~~~~~~
 116
 117 .. kernel-doc:: kernel/time/sleep_timeout.c
 118        :identifiers: msleep msleep_interruptible
 119
 120 .. kernel-doc:: include/linux/delay.h
 121         :identifiers: ssleep fsleep