mirror of
https://github.com/apache/nuttx.git
synced 2026-05-18 17:18:28 +08:00
donghaokun
839468f52d
Build Documentation / build-html (push) Has been cancelled
As pull request apache#17200 & apache#17368 introduced support for scheduling sleep, a documentation is needed for different sleep interfaces. This patch adds the description for sleep interfaces currently provided in NuttX, including Scheduled sleep(nxsched_sleep()...), Signal-scheduled sleep(nxsig_sleep()...), and Busy sleep(up_udelay()). Signed-off-by: Haokun Dong <donghaokun@lixiang.com>
116 lines
3.9 KiB
ReStructuredText
116 lines
3.9 KiB
ReStructuredText
=====
|
|
Sleep
|
|
=====
|
|
|
|
NuttX provides three different types of sleep interfaces.
|
|
|
|
Common Sleep Interfaces
|
|
=======================
|
|
|
|
Scheduled Sleep Interfaces (tick-based)
|
|
---------------------------------------
|
|
|
|
Suspend the calling thread for a specified amount of time until the time expires
|
|
or the thread is explicitly woken up through scheduler operations.
|
|
|
|
.. c:function:: void nxsched_ticksleep(unsigned int ticks)
|
|
|
|
Suspends the calling thread from execution for the specified number of system ticks.
|
|
|
|
:param ticks: The number of system ticks to sleep.
|
|
|
|
.. c:function:: void nxsched_usleep(useconds_t usec)
|
|
|
|
Suspends the calling thread from execution for the specified number of microseconds.
|
|
|
|
:param usec: The number of microseconds to sleep.
|
|
|
|
.. c:function:: void nxsched_msleep(unsigned int msec)
|
|
|
|
Suspends the calling thread from execution for the specified number of milliseconds.
|
|
|
|
:param msec: The number of milliseconds to sleep.
|
|
|
|
.. c:function:: void nxsched_sleep(unsigned int sec)
|
|
|
|
Suspends the calling thread from execution for the specified number of seconds.
|
|
|
|
:param sec: The number of seconds to sleep.
|
|
|
|
.. c:function:: int nxsched_nanosleep(const struct timespec *rqtp, struct timespec *rmtp)
|
|
|
|
Suspends the calling thread from execution for the specified rqtp argument. This
|
|
function will return the remaining time via updating rmtp if the sleep is interrupted
|
|
by a signal.
|
|
|
|
:param rqtp: The amount of time to be suspended from execution.
|
|
:param rmtp: If the rmtp argument is non-NULL, the timespec structure referenced
|
|
by it is updated to contain the amount of time remaining.
|
|
|
|
:return: 0 (OK), or negated errno if unsuccessful.
|
|
|
|
.. c:function:: void nxsched_wakeup(struct tcb_s *tcb)
|
|
|
|
This function is used to wake up a thread that is currently in sleeping state
|
|
before its timeout expires.
|
|
|
|
:param tcb: Pointer to the TCB of the task to be awakened.
|
|
|
|
Signal-based Sleep Interfaces (timespec-based)
|
|
----------------------------------------------
|
|
|
|
Suspend the calling thread for a specified amount of time until the
|
|
time expires or a signal is delivered to the calling thread.
|
|
|
|
.. note::
|
|
Implementations are dependent on the signal framework and based on standard
|
|
timespec conversion.
|
|
|
|
.. c:function:: void nxsig_usleep(useconds_t usec)
|
|
|
|
Suspends the calling thread from execution for the specified number of microseconds.
|
|
|
|
:param usec: The number of microseconds to sleep.
|
|
|
|
.. c:function:: void nxsig_sleep(unsigned int sec)
|
|
|
|
Suspends the calling thread from execution for the specified number of seconds.
|
|
|
|
:param sec: The number of seconds to sleep.
|
|
|
|
.. c:function:: int nxsig_nanosleep(const struct timespec *rqtp, struct timespec *rmtp)
|
|
|
|
Suspends the calling thread from execution for the specified rqtp argument. This
|
|
function will return the remaining time via updating rmtp if the sleep is interrupted
|
|
by a signal.
|
|
|
|
:param rqtp: The amount of time to be suspended from execution.
|
|
:param rmtp: If the rmtp argument is non-NULL, the timespec structure referenced
|
|
by it is updated to contain the amount of time remaining.
|
|
|
|
:return: 0 (OK), or negated errno if unsuccessful.
|
|
|
|
Busy Sleep Interfaces
|
|
---------------------
|
|
|
|
Spin in a loop for the requested duration and never yield the CPU. The delay accuracy depends on
|
|
``CONFIG_BOARD_LOOPSPERMSEC``.
|
|
|
|
.. c:function:: void up_mdelay(unsigned int milliseconds)
|
|
|
|
Delay inline for the requested number of milliseconds.
|
|
|
|
:param milliseconds: The number of milliseconds to delay.
|
|
|
|
.. c:function:: void up_udelay(useconds_t microseconds)
|
|
|
|
Delay inline for the requested number of microseconds.
|
|
|
|
:param microseconds: The number of microseconds to delay.
|
|
|
|
.. c:function:: void up_ndelay(unsigned long nanoseconds)
|
|
|
|
Delay inline for the requested number of nanoseconds.
|
|
|
|
:param nanoseconds: The number of nanoseconds to delay.
|