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 <donghaokun@lixiang.com>

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

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.

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

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