1.. SPDX-License-Identifier: GPL-2.0
  2
  3Delay and sleep mechanisms
  4==========================
  5
  6This document seeks to answer the common question: "What is the
  7RightWay (TM) to insert a delay?"
  8
  9This question is most often faced by driver writers who have to
 10deal with hardware delays and who may not be the most intimately
 11familiar with the inner workings of the Linux Kernel.
 12
 13The following table gives a rough overview about the existing function
 14'families' and their limitations. This overview table does not replace the
 15reading 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
 52A 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
 60Find some more detailed information about the function 'families' in the next
 61sections.
 62
 63`*delay()` family of functions
 64------------------------------
 65
 66These functions use the jiffy estimation of clock speed and will busy wait for
 67enough loop cycles to achieve the desired delay. udelay() is the basic
 68implementation and ndelay() as well as mdelay() are variants.
 69
 70These functions are mainly used to add a delay in atomic context. Please make
 71sure to ask yourself before adding a delay in atomic context: Is this really
 72required?
 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
 84These functions use hrtimers or timer list timers to provide the requested
 85sleeping duration. In order to decide which function is the right one to use,
 86take 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
 93The 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
100First check fsleep() function description and to learn more about accuracy,
101please 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