.. SPDX-License-Identifier: GPL-2.0

Delay and 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.

The following table gives a rough overview about the existing function
'families' and their limitations. This overview table does not replace the
reading of the function description before usage!

.. list-table::
   :widths: 20 20 20 20 20
   :header-rows: 2

   * -
     - `*delay()`
     - `usleep_range*()`
     - `*sleep()`
     - `fsleep()`
   * -
     - busy-wait loop
     - hrtimers based
     - timer list timers based
     - combines the others
   * - Usage in atomic Context
     - yes
     - no
     - no
     - no
   * - precise on "short intervals"
     - yes
     - yes
     - depends
     - yes
   * - precise on "long intervals"
     - Do not use!
     - yes
     - max 12.5% slack
     - yes
   * - interruptible variant
     - no
     - yes
     - yes
     - no

A generic advice for non atomic contexts could be:

#. Use `fsleep()` whenever unsure (as it combines all the advantages of the
   others)
#. Use `*sleep()` whenever possible
#. Use `usleep_range*()` whenever accuracy of `*sleep()` is not sufficient
#. Use `*delay()` for very, very short delays

Find some more detailed information about the function 'families' in the next
sections.

`*delay()` family of functions
------------------------------

These functions use the jiffy estimation of clock speed and will busy wait for
enough loop cycles to achieve the desired delay. udelay() is the basic
implementation and ndelay() as well as mdelay() are variants.

These functions are mainly used to add a delay in atomic context. Please make
sure to ask yourself before adding a delay in atomic context: Is this really
required?

.. kernel-doc:: include/asm-generic/delay.h
	:identifiers: udelay ndelay

.. kernel-doc:: include/linux/delay.h
	:identifiers: mdelay


`usleep_range*()` and `*sleep()` family of functions
----------------------------------------------------

These functions use hrtimers or timer list timers to provide the requested
sleeping duration. In order to decide which function is the right one to use,
take some basic information into account:

#. hrtimers are more expensive as they are using an rb-tree (instead of hashing)
#. hrtimers are more expensive when the requested sleeping duration is the first
   timer which means real hardware has to be programmed
#. timer list timers always provide some sort of slack as they are jiffy based

The generic advice is repeated here:

#. Use `fsleep()` whenever unsure (as it combines all the advantages of the
   others)
#. Use `*sleep()` whenever possible
#. Use `usleep_range*()` whenever accuracy of `*sleep()` is not sufficient

First check fsleep() function description and to learn more about accuracy,
please check msleep() function description.


`usleep_range*()`
~~~~~~~~~~~~~~~~~

.. kernel-doc:: include/linux/delay.h
	:identifiers: usleep_range usleep_range_idle

.. kernel-doc:: kernel/time/sleep_timeout.c
	:identifiers: usleep_range_state


`*sleep()`
~~~~~~~~~~

.. kernel-doc:: kernel/time/sleep_timeout.c
       :identifiers: msleep msleep_interruptible

.. kernel-doc:: include/linux/delay.h
	:identifiers: ssleep fsleep