Documentation/timers/delay_sleep_functions.rst

Source file repositories/reference/linux-study-clean/Documentation/timers/delay_sleep_functions.rst

File Facts

System
Linux kernel
Corpus path
Documentation/timers/delay_sleep_functions.rst
Extension
.rst
Size
3467 bytes
Lines
122
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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

Annotation

Implementation Notes