This is an automated email from the ASF dual-hosted git repository.
simbit18 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 839468f52d7 docs/sched/sched: Add documentation for different sleep
interfaces 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()).
839468f52d7 is described below
commit 839468f52d782ab7377196bb407bf79c5a89472f
Author: donghaokun <[email protected]>
AuthorDate: Wed Dec 3 15:22:15 2025 +0800
docs/sched/sched: Add documentation for different sleep interfaces
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 <[email protected]>
---
Documentation/reference/os/index.rst | 1 +
Documentation/reference/os/sleep.rst | 115 +++++++++++++++++++++++++++++++++++
include/nuttx/sched.h | 6 +-
sched/sched/sched_sleep.c | 6 +-
4 files changed, 124 insertions(+), 4 deletions(-)
diff --git a/Documentation/reference/os/index.rst
b/Documentation/reference/os/index.rst
index f47b09bfb6e..094ea5d5813 100644
--- a/Documentation/reference/os/index.rst
+++ b/Documentation/reference/os/index.rst
@@ -23,6 +23,7 @@ in other header files.
paging.rst
shm.rst
smp.rst
+ sleep.rst
time_clock.rst
wqueue.rst
events.rst
diff --git a/Documentation/reference/os/sleep.rst
b/Documentation/reference/os/sleep.rst
new file mode 100644
index 00000000000..bfa6ef41392
--- /dev/null
+++ b/Documentation/reference/os/sleep.rst
@@ -0,0 +1,115 @@
+=====
+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.
diff --git a/include/nuttx/sched.h b/include/nuttx/sched.h
index e5f5b68a031..a565bd373d3 100644
--- a/include/nuttx/sched.h
+++ b/include/nuttx/sched.h
@@ -1821,14 +1821,16 @@ void nxsched_sleep(unsigned int sec);
* Name: nxsched_nanosleep
*
* Description:
- * Internal nanosleep implementation used by the scheduler. This function
+ * Internal nanosleep implementation used by the scheduler. This function
* converts the requested sleep interval into system ticks, performs a
* tick-based blocking sleep, and optionally returns the remaining time if
* the sleep is interrupted by a signal.
*
* Input Parameters:
* rqtp - Requested sleep interval (may be NULL)
- * rmtp - Remaining time returned when interrupted (optional, may be NULL)
+ * rmtp - If the rmtp argument is non-NULL, the timespec structure
+ * referenced by it is updated to contain the amount of time
+ * remaining.
*
* Returned Value:
* Returns OK (0) on success. Returns -EINVAL for an invalid timespec
diff --git a/sched/sched/sched_sleep.c b/sched/sched/sched_sleep.c
index 6d2dc424574..16f898b7c83 100644
--- a/sched/sched/sched_sleep.c
+++ b/sched/sched/sched_sleep.c
@@ -226,14 +226,16 @@ void nxsched_sleep(unsigned int sec)
* Name: nxsched_nanosleep
*
* Description:
- * Internal nanosleep implementation used by the scheduler. This function
+ * Internal nanosleep implementation used by the scheduler. This function
* converts the requested sleep interval into system ticks, performs a
* tick-based blocking sleep, and optionally returns the remaining time if
* the sleep is interrupted by a signal.
*
* Input Parameters:
* rqtp - Requested sleep interval (may be NULL)
- * rmtp - Remaining time returned when interrupted (optional, may be NULL)
+ * rmtp - If the rmtp argument is non-NULL, the timespec structure
+ * referenced by it is updated to contain the amount of time
+ * remaining.
*
* Returned Value:
* Returns OK (0) on success. Returns -EINVAL for an invalid timespec
