[lwp]add comments for lwp system calls. (#9934)

1 files changed, 4500 insertions, 36 deletions

diff --git a/components/lwp/lwp_syscall.c b/components/lwp/lwp_syscall.c
index 96bad92b51..429861f50e 100644
--- a/components/lwp/lwp_syscall.c
+++ b/components/lwp/lwp_syscall.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -329,7 +329,7 @@ static void _crt_thread_entry(void *parameter)
     tid = rt_thread_self();
 
     user_stack = (rt_size_t)tid->user_stack + tid->user_stack_size;
-    user_stack &= ~7; //align 8
+    user_stack &= ~7; /* align 8 */
 
 #ifdef ARCH_MM_MMU
     arch_crt_start_umode(parameter, tid->user_entry, (void *)user_stack, (char *)tid->stack_addr + tid->stack_size);
@@ -339,7 +339,16 @@ static void _crt_thread_entry(void *parameter)
 #endif /* ARCH_MM_MMU */
 }
 
-/* exit group */
+/**
+ * @brief Terminates all threads in the current thread group.
+ *
+ * This system call ends execution for all threads within the same thread group,
+ * releasing resources such as memory and file descriptors. It is typically used
+ * in multithreaded environments to ensure a clean exit for the entire process.
+ *
+ * @param value The exit code to be returned to the parent process.
+ * @return sysret_t: return value of the system call execution.
+ */
 sysret_t sys_exit_group(int value)
 {
     sysret_t rc = 0;
@@ -360,7 +369,20 @@ sysret_t sys_exit_group(int value)
     return rc;
 }
 
-/* thread exit */
+/**
+ * @brief Terminates the calling thread and exits the process.
+ *
+ * This system call ends the execution of the calling thread and the process
+ * it belongs to.
+ *
+ * @param status The exit code to be returned to the parent process.
+ *               A value of 0 typically indicates successful execution, while
+ *               non-zero values indicate an error or specific exit condition.
+ * @return sysret_t: return value of the system call execution.
+ *
+ * @note Unlike `sys_exit_group`, which terminates all threads in a thread group,
+ *       `sys_exit` only terminates the calling thread and the process.
+ */
 sysret_t sys_exit(int status)
 {
     sysret_t rc = 0;
@@ -380,7 +402,24 @@ sysret_t sys_exit(int status)
     return rc;
 }
 
-/* syscall: "read" ret: "ssize_t" args: "int" "void *" "size_t" */
+/**
+ * @brief Reads data from a file descriptor into a buffer.
+ *
+ * This system call reads up to `nbyte` bytes of data from the file descriptor
+ * specified by `fd` into the buffer pointed to by `buf`.
+ *
+ * @param fd The file descriptor to read from. This should be a valid file
+ *           descriptor obtained through system calls like `open()` or `socket()`.
+ * @param buf A pointer to the buffer where the read data will be stored. The buffer
+ *            must have enough space to accommodate up to `nbyte` bytes.
+ * @param nbyte The maximum number of bytes to read. If the file contains fewer
+ *              bytes than `nbyte`, only the available bytes will be read.
+ * @return The number of bytes actually read, which may be less than `nbyte` if fewer
+ *         bytes are available or if the end of the file is reached. Returns `0` if
+ *         the end of the file is encountered. On error, returns `errno`.
+ * @warning Ensure the buffer `buf` has sufficient space to hold the requested number
+ *          of bytes, as failing to do so may result in undefined behavior.
+ */
 ssize_t sys_read(int fd, void *buf, size_t nbyte)
 {
 #ifdef ARCH_MM_MMU
@@ -428,7 +467,30 @@ ssize_t sys_read(int fd, void *buf, size_t nbyte)
 #endif
 }
 
-/* syscall: "write" ret: "ssize_t" args: "int" "const void *" "size_t" */
+/**
+ * @brief Writes data from a buffer to a file descriptor.
+ *
+ * This system call writes up to `nbyte` bytes of data from the buffer pointed
+ * to by `buf` to the file descriptor specified by `fd`.
+ *
+ * @param fd The file descriptor to write to. This should be a valid file
+ *           descriptor obtained through system calls like `open()` or `socket()`.
+ * @param buf A pointer to the buffer containing the data to be written. The
+ *            buffer must remain valid and accessible for the duration of the
+ *            write operation.
+ * @param nbyte The number of bytes to write from the buffer. If the file descriptor
+ *              refers to a device or a socket, the actual number of bytes written
+ *              may be less than `nbyte`.
+ * @return The number of bytes actually written. This may be less than `nbyte` if
+ *         the underlying resource cannot accept more data at the moment. On error,
+ *         returns `errno`.
+ *
+ * @warning Ensure the buffer `buf` contains at least `nbyte` valid bytes to
+ *          avoid undefined behavior. Additionally, verify that `fd` is writable
+ *          to prevent errors.
+ *
+ * @see sys_read(), write()
+ */
 ssize_t sys_write(int fd, const void *buf, size_t nbyte)
 {
 #ifdef ARCH_MM_MMU
@@ -470,14 +532,67 @@ ssize_t sys_write(int fd, const void *buf, size_t nbyte)
 #endif
 }
 
-/* syscall: "lseek" ret: "off_t" args: "int" "off_t" "int" */
+/**
+ * @brief Repositions the file offset of the open file descriptor.
+ *
+ * This system call sets the file offset for the open file descriptor `fd`
+ * to a new position based on the `offset` and `whence` parameters. It is used
+ * for seeking within files, enabling random access to file content.
+ *
+ * @param fd The file descriptor whose offset is to be modified. The descriptor
+ *           must refer to a file capable of seeking (e.g., regular files, but
+ *           not pipes or sockets).
+ * @param offset The new offset value relative to the position specified by `whence`.
+ *               Can be a positive or negative value, depending on the seek direction.
+ * @param whence The reference point for the new offset. Must be one of the following:
+ *               - `SEEK_SET`: Set the offset to `offset` bytes from the beginning of the file.
+ *               - `SEEK_CUR`: Set the offset to its current position plus `offset`.
+ *               - `SEEK_END`: Set the offset to the size of the file plus `offset`.
+ * @return On success, returns the resulting offset location as measured in bytes
+ *         from the beginning of the file. On failure, returns `errno`.
+ *
+ * @warning Ensure the file descriptor `fd` supports seeking. Using this function
+ *          on non-seekable file descriptors (e.g., pipes or sockets) will result in an error.
+ *
+ * @see sys_read(), sys_write(), lseek()
+ */
 size_t sys_lseek(int fd, size_t offset, int whence)
 {
     ssize_t ret = lseek(fd, offset, whence);
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
-/* syscall: "open" ret: "int" args: "const char *" "int" "..." */
+/**
+ * @brief Opens or creates a file, returning a file descriptor.
+ *
+ * This system call opens the file specified by `name` with the specified
+ * access mode and flags. If the file does not exist and the `O_CREAT` flag
+ * is provided, it will create the file with the specified mode.
+ *
+ * @param name The path to the file to be opened. This can be an absolute or
+ *             relative path.
+ * @param flag Flags controlling how the file is opened. Common values include:
+ *             - `O_RDONLY`: Open the file for read-only access.
+ *             - `O_WRONLY`: Open the file for write-only access.
+ *             - `O_RDWR`: Open the file for both reading and writing.
+ *             - `O_CREAT`: Create the file if it does not exist (requires a mode argument).
+ *             - `O_TRUNC`: Truncate the file to zero length if it exists.
+ *             - `O_APPEND`: Open the file in append mode.
+ * @param ... Optional. If the `O_CREAT` flag is specified, an additional
+ *            `mode_t` argument must be provided, defining the file permissions
+ *            (e.g., `0644` for user-read/write and group/world-read).
+ * @return On success, returns the file descriptor.
+ *         On failure, returns `errno`.
+ *
+ * @note The file descriptor returned can be used with other system calls like
+ *       `sys_read()`, `sys_write()`, and `sys_close()`.
+ *
+ * @warning When using the `O_CREAT` flag, ensure to provide the `mode` argument
+ *          to avoid undefined behavior. Additionally, verify that the process
+ *          has the necessary permissions to access or create the file.
+ *
+ * @see sys_close(), sys_read(), sys_write(), open()
+ */
 sysret_t sys_open(const char *name, int flag, ...)
 {
 #ifdef ARCH_MM_MMU
@@ -548,7 +663,40 @@ sysret_t sys_open(const char *name, int flag, ...)
 #endif
 }
 
-/* syscall: "openat" ret: "int" args: "const char *" "mode_t" "mode" */
+/**
+ * @brief Opens or creates a file relative to a directory file descriptor.
+ *
+ * This system call opens the file specified by `name`, relative to the directory
+ * indicated by `dirfd`, with the specified flags and mode. It provides more
+ * flexibility than `sys_open` for handling files in specific directory contexts.
+ *
+ * @param dirfd The file descriptor of the directory relative to which the file is opened.
+ *              Special values include:
+ *              - `AT_FDCWD`: Use the current working directory as the base.
+ * @param name The path to the file to be opened. If `name` is absolute, `dirfd` is ignored.
+ * @param flag Flags controlling how the file is opened. Common values include:
+ *             - `O_RDONLY`: Open the file for read-only access.
+ *             - `O_WRONLY`: Open the file for write-only access.
+ *             - `O_RDWR`: Open the file for both reading and writing.
+ *             - `O_CREAT`: Create the file if it does not exist.
+ *             - `O_TRUNC`: Truncate the file to zero length if it exists.
+ *             - `O_APPEND`: Open the file in append mode.
+ *             - `O_EXCL`: Ensure the file is created exclusively (used with `O_CREAT`).
+ * @param mode The permissions to set if the file is created (e.g., `0644` for user read/write
+ *             and group/world read). This parameter is ignored unless `O_CREAT` is specified.
+ * @return On success, returns the file descriptor.
+ *         On failure, returns `errno`.
+ *
+ * @note The `sys_openat` system call is particularly useful for implementing secure
+ *       directory traversal and operations, as it avoids race conditions when working
+ *       with relative paths.
+ *
+ * @warning Ensure that `dirfd` is a valid directory file descriptor if a relative
+ *          `name` is provided. Combining `O_CREAT` and `mode` requires proper handling
+ *          to avoid unintended permission settings.
+ *
+ * @see sys_open(), sys_read(), sys_write(), sys_close()
+ */
 sysret_t sys_openat(int dirfd, const char *name, int flag, mode_t mode)
 {
 #ifdef ARCH_MM_MMU
@@ -588,20 +736,97 @@ sysret_t sys_openat(int dirfd, const char *name, int flag, mode_t mode)
 #endif
 }
 
-/* syscall: "close" ret: "int" args: "int" */
+/**
+ * @brief Closes a file descriptor.
+ *
+ * This system call closes the file descriptor specified by `fd`, releasing any
+ * resources associated with it. Once closed, the file descriptor can no longer
+ * be used for operations such as reading or writing, and it may be reassigned
+ * by subsequent calls to functions like `sys_open()`.
+ *
+ * @param fd The file descriptor to be closed. This must be a valid open file descriptor.
+ * @return On success, returns 0. On failure, returns `errno`.
+ *
+ * @note Closing a file descriptor that is already closed results in an error.
+ *       Additionally, if the file descriptor refers to a file or resource shared
+ *       among multiple processes or threads, only the reference count is decremented,
+ *       and the resource itself is not released until all references are closed.
+ *
+ * @warning Always ensure `fd` is valid before calling this function. Attempting
+ *          to close an invalid or already closed descriptor may lead to undefined
+ *          behavior or errors.
+ *
+ * @see sys_open(), sys_read(), sys_write(), close()
+ */
 sysret_t sys_close(int fd)
 {
     int ret = close(fd);
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
-/* syscall: "ioctl" ret: "int" args: "int" "u_long" "..." */
+/**
+ * @brief Performs control operations on a file descriptor.
+ *
+ * This system call allows a program to manipulate the behavior of a device or file
+ * associated with the file descriptor `fd` by issuing a control command (`cmd`).
+ * The function provides an interface to interact with device drivers, such as modifying
+ * the settings of a device or performing custom operations.
+ *
+ * @param fd The file descriptor representing the device or file on which the ioctl
+ *           command will be performed. This should be a valid, open file descriptor.
+ * @param cmd The control command to be executed. The exact behavior depends on the
+ *            device and the command. Commands are usually defined by the device driver
+ *            or the kernel and can vary widely.
+ * @param data A pointer to a buffer used for passing data to and from the command.
+ *             The contents of the buffer depend on the specific command. For input
+ *             commands, it may contain the data to be written to the device. For output
+ *             commands, it may hold the data returned by the device.
+ * @return On success, returns 0. On failure, returns `errno`.
+ *
+ * @note The actual functionality of `sys_ioctl` depends heavily on the specific `cmd`
+ *       and the type of device associated with the file descriptor `fd`. Each device
+ *       may have a different set of valid ioctl commands.
+ *
+ * @warning Ensure that `fd` refers to a valid file descriptor for a device that supports
+ *          ioctl commands. Providing an invalid command or using an unsupported device
+ *          may lead to undefined behavior or errors.
+ *
+ * @see sys_open(), sys_read(), sys_write(), ioctl()
+ */
 sysret_t sys_ioctl(int fd, unsigned long cmd, void* data)
 {
     int ret = ioctl(fd, cmd, data);
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Retrieves information about a file associated with a file descriptor.
+ *
+ * This system call retrieves the status information about the file referred to
+ * by the file descriptor `file` and stores it in the structure pointed to by `buf`.
+ * It is typically used to obtain metadata such as file size, permissions, type,
+ * and timestamps.
+ *
+ * @param file The file descriptor referring to an open file. It must be a valid file
+ *             descriptor returned by `sys_open()` or similar system calls.
+ * @param buf A pointer to a `struct stat` that will be populated with the file's
+ *            status information, including attributes like size, access times,
+ *            permissions, and more.
+ * @return On success, returns `0`. On failure, returns `errno` to indicate the error.
+ *
+ * @note The structure `struct stat` typically includes the following fields:
+ *       - `st_size`: Size of the file in bytes.
+ *       - `st_mode`: File type and permissions.
+ *       - `st_mtime`: Last modification time.
+ *       - `st_atime`: Last access time.
+ *       - `st_ctime`: Time of last status change.
+ *
+ * @warning Ensure that `file` is a valid, open file descriptor. Invalid file
+ *          descriptors or unsupported file types may lead to errors when using
+ *          this function.
+ *
+ * @see sys_open(), sys_close(), stat(), fstat()
+ */
 sysret_t sys_fstat(int file, struct stat *buf)
 {
 #ifdef ARCH_MM_MMU
@@ -637,6 +862,36 @@ sysret_t sys_fstat(int file, struct stat *buf)
 #endif
 }
 
+/**
+ * @brief Monitors multiple file descriptors to see if they are ready for I/O.
+ *
+ * This system call monitors the file descriptors specified in `fds` for any
+ * I/O events such as readiness for reading, writing, or exceptional conditions.
+ * It waits up to the specified timeout and returns with information about which
+ * file descriptors are ready for the requested operations.
+ *
+ * @param fds An array of `struct pollfd` structures, each specifying a file descriptor
+ *            to be monitored and the events to be checked for. On return, each structure
+ *            will contain the result of the poll operation for that file descriptor.
+ * @param nfds The number of elements in the `fds` array.
+ * @param timeout The maximum time (in milliseconds) to wait for events. If `timeout`
+ *                is `-1`, the call will block indefinitely. If `timeout` is `0`,
+ *                the call will return immediately.
+ * @return On success, returns the number of file descriptors with events that are ready,
+ *         or `0` if the timeout expired with no events. On error, returns `-1` and sets `errno`.
+ *
+ * @note The `pollfd` structure used for each file descriptor contains the following fields:
+ *       - `fd`: The file descriptor to be monitored.
+ *       - `events`: The events to monitor (e.g., `POLLIN`, `POLLOUT`).
+ *       - `revents`: The events that actually occurred.
+ *
+ * @warning Ensure that `fds` contains valid file descriptors. Invalid descriptors or
+ *          unsupported types (such as sockets) may result in errors. Also, be mindful
+ *          of the timeout behavior - passing `0` will cause an immediate return, and passing
+ *          `-1` will block indefinitely.
+ *
+ * @see sys_select(), poll(), select()
+ */
 sysret_t sys_poll(struct pollfd *fds, nfds_t nfds, int timeout)
 {
     int ret = -1;
@@ -674,6 +929,43 @@ sysret_t sys_poll(struct pollfd *fds, nfds_t nfds, int timeout)
 #endif /* ARCH_MM_MMU */
 }
 
+/**
+ * @brief Monitors multiple file descriptors for readiness to perform I/O operations.
+ *
+ * This system call allows a program to monitor multiple file descriptors to see if
+ * they are ready for reading, writing, or have exceptional conditions. It waits
+ * for one or more of the file descriptors to become ready or for the specified
+ * timeout to expire.
+ *
+ * @param nfds The highest-numbered file descriptor in any of the sets, plus one.
+ *             This is the number of file descriptors to monitor.
+ * @param readfds A pointer to an `fd_set` structure specifying the file descriptors
+ *                to be checked for readability. If a file descriptor is ready to
+ *                read, it will be set in the returned `fd_set`.
+ * @param writefds A pointer to an `fd_set` structure specifying the file descriptors
+ *                 to be checked for writability. If a file descriptor is ready to
+ *                 write, it will be set in the returned `fd_set`.
+ * @param exceptfds A pointer to an `fd_set` structure specifying the file descriptors
+ *                  to be checked for exceptional conditions (e.g., out-of-band data).
+ *                  If a file descriptor has exceptional conditions, it will be set in
+ *                  the returned `fd_set`.
+ * @param timeout A pointer to a `struct timeval` that specifies the maximum time
+ *                to wait for an event. If `NULL`, the call blocks indefinitely. If
+ *                `timeout` is `0`, the call will return immediately.
+ * @return On success, returns the number of file descriptors that are ready for
+ *         the requested operations, or `0` if the timeout expired without any events.
+ *         On error, returns `-1` and sets `errno`.
+ *
+ * @note The `fd_set` structures should be initialized using the `FD_ZERO` macro
+ *       and populated using the `FD_SET` macro. After the call, the `fd_set` structures
+ *       will contain the file descriptors that are ready for the requested operations.
+ *
+ * @warning Ensure that the `fd_set` structures are properly initialized and that
+ *          `nfds` correctly reflects the number of file descriptors to monitor.
+ *          Passing invalid file descriptors or incorrect `nfds` can lead to undefined behavior.
+ *
+ * @see sys_poll(), sys_read(), sys_write(), poll(), select()
+ */
 sysret_t sys_select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
 {
 #ifdef ARCH_MM_MMU
@@ -778,6 +1070,32 @@ quit:
 #endif
 }
 
+/**
+ * @brief Removes a file or symbolic link from the filesystem.
+ *
+ * This system call deletes the file or symbolic link specified by `pathname`.
+ * After the call, the file will be unlinked from the filesystem, meaning it will
+ * no longer be accessible via its pathname. If the file is still open, it will
+ * remain available to processes that have it open until all file descriptors are
+ * closed. If the file is a regular file and has no other hard links, it will be
+ * removed from the disk once all references to it are closed.
+ *
+ * @param pathname The path to the file or symbolic link to be removed. It can be
+ *                 an absolute or relative path.
+ * @return On success, returns `0`. On failure, returns `errno` to indicate
+ *         the error.
+ *
+ * @note If the file is currently being used by a process (i.e., the file descriptor
+ *       is still open), it will not be immediately removed from the disk. The actual
+ *       removal occurs once the file is no longer in use. Symbolic links are removed
+ *       as soon as the call is executed.
+ *
+ * @warning Ensure that the file or link to be removed exists and that the `pathname`
+ *          is correctly specified. The operation will fail if the file is open and
+ *          in use by other processes or if the pathname does not exist.
+ *
+ * @see sys_open(), sys_remove(), unlink()
+ */
 sysret_t sys_unlink(const char *pathname)
 {
 #ifdef ARCH_MM_MMU
@@ -817,7 +1135,31 @@ sysret_t sys_unlink(const char *pathname)
 #endif
 }
 
-/* syscall: "nanosleep" ret: "int" args: "const struct timespec *" "struct timespec *" */
+/**
+ * @brief Suspends execution for a specified amount of time.
+ *
+ * This system call suspends the execution of the calling thread for the duration
+ * specified by the `rqtp` argument. The `rqtp` argument is a pointer to a `struct timespec`
+ * that defines the sleep time in seconds and nanoseconds. If the sleep is interrupted by a signal,
+ * the function may return early with the remaining time in `rmtp`, which is an optional argument.
+ *
+ * @param rqtp A pointer to a `struct timespec` that specifies the requested sleep time.
+ *             The structure contains two fields: `tv_sec` (seconds) and `tv_nsec` (nanoseconds).
+ * @param rmtp A pointer to a `struct timespec` where the remaining time will be stored if the
+ *             sleep is interrupted by a signal. This can be `NULL` if the remaining time is not needed.
+ * @return On success, returns `0`. On failure, returns `errno` to indicate the error.
+ *
+ * @note The `timespec` structure has two fields:
+ *       - `tv_sec`: The number of whole seconds to sleep.
+ *       - `tv_nsec`: The number of nanoseconds to sleep after the seconds. This value should be
+ *         in the range [0, 1,000,000,000) nanoseconds.
+ *
+ * @warning Ensure that the values in `rqtp` are within valid ranges. A `tv_nsec` value greater than
+ *          or equal to 1,000,000,000 will result in an error. If `rmtp` is provided, the caller
+ *          must ensure the buffer is large enough to store the remaining time.
+ *
+ * @see sys_sleep(), clock_nanosleep(), nanosleep()
+ */
 sysret_t sys_nanosleep(const struct timespec *rqtp, struct timespec *rmtp)
 {
     int ret = 0;
@@ -848,7 +1190,35 @@ sysret_t sys_nanosleep(const struct timespec *rqtp, struct timespec *rmtp)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
-/* syscall: "gettimeofday" ret: "int" args: "struct timeval *" "struct timezone *" */
+/**
+ * @brief Retrieves the current time and timezone information.
+ *
+ * This system call retrieves the current time in seconds and microseconds since
+ * the Unix epoch (1970-01-01 00:00:00 UTC) and stores it in the `tp` argument.
+ * It also retrieves the timezone information, if requested, and stores it in the
+ * `tzp` argument. The time returned is the local time of the system unless
+ * UTC is specified.
+ *
+ * @param tp A pointer to a `struct timeval` where the current time will be stored.
+ *           The `struct timeval` contains two fields:
+ *           - `tv_sec`: The number of seconds since the Unix epoch.
+ *           - `tv_usec`: The number of microseconds past `tv_sec`.
+ * @param tzp A pointer to a `struct timezone` where the timezone information will
+ *            be stored. This structure contains two fields:
+ *            - `tz_minuteswest`: The number of minutes west of UTC.
+ *            - `tz_dsttime`: A flag indicating the type of daylight saving time (DST) adjustment.
+ *            If `tzp` is `NULL`, timezone information is not provided.
+ * @return On success, returns `0`. On failure, returns error code.
+ *
+ * @note The `struct timeval` represents the current time in seconds and microseconds,
+ *       while `struct timezone` provides information on the timezone relative to UTC
+ *       and any daylight saving adjustments.
+ *
+ * @warning Ensure that `tp` and `tzp` are valid pointers before calling the function.
+ *          If you don't need timezone information, you can pass `NULL` for `tzp`.
+ *
+ * @see sys_time(), time(), gettimeofday()
+ */
 sysret_t sys_gettimeofday(struct timeval *tp, struct timezone *tzp)
 {
 #ifdef ARCH_MM_MMU
@@ -881,11 +1251,62 @@ sysret_t sys_gettimeofday(struct timeval *tp, struct timezone *tzp)
     return 0;
 }
 
+/**
+ * @brief Sets the system's current time and timezone information.
+ *
+ * @param tv A pointer to a `struct timeval` that contains the new system time to set.
+ *           The `struct timeval` consists of:
+ *           - `tv_sec`: The number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).
+ *           - `tv_usec`: The number of microseconds past `tv_sec`.
+ * @param tzp A pointer to a `struct timezone` that contains the new timezone settings.
+ *            The `struct timezone` consists of:
+ *            - `tz_minuteswest`: The number of minutes west of UTC.
+ *            - `tz_dsttime`: The type of daylight saving time adjustment.
+ *            If `tzp` is `NULL`, the timezone information is not changed.
+ * @return On success, returns `0`. On failure, returns error code.
+ *
+ * @note haven't supported now.
+ *
+ * @see sys_gettimeofday(), settimeofday(), time()
+ */
 sysret_t sys_settimeofday(const struct timeval *tv, const struct timezone *tzp)
 {
     return 0;
 }
 
+/**
+ * @brief Replaces the current process with a new process.
+ *
+ * This system call loads a new program into the current process's address space,
+ * replacing the current program with the one specified by `filename`. It passes the
+ * arguments `argv` and environment variables `envp` to the new program. If the execution
+ * is successful, the current process is completely replaced, and no code after the
+ * `sys_exec` call is executed. If an error occurs, the system call returns, and the
+ * current process continues executing.
+ *
+ * @param filename The path to the executable file to be run. This can be an absolute
+ *                 or relative path.
+ * @param argc The number of arguments passed to the new program. This includes the
+ *             executable name itself as the first argument.
+ * @param argv An array of strings (character pointers), where each string is an argument
+ *             passed to the new program. The first element (`argv[0]`) is conventionally
+ *             the name of the executable.
+ * @param envp An array of strings representing the environment variables for the new
+ *             process. The array is terminated by a `NULL` pointer.
+ * @return This function does not return on success, as the current process is replaced.
+ *         On failure, it returns error code to indicate the error.
+ *
+ * @note The new process inherits most of the attributes of the current process, such
+ *       as file descriptors, unless explicitly modified. It is important that `argv`
+ *       and `envp` are properly formatted, and the `filename` points to a valid executable.
+ *
+ * @warning If `filename` is invalid or not an executable, or if the arguments or
+ *          environment variables are incorrectly set, the system call will fail and
+ *          return `-1`. Ensure that the executable file is accessible and that `argv`
+ *          and `envp` are properly constructed.
+ *
+ * @see execve(), execvp(), execv(), execle()
+ */
 sysret_t sys_exec(char *filename, int argc, char **argv, char **envp)
 {
     int ret = 0;
@@ -917,6 +1338,40 @@ sysret_t sys_exec(char *filename, int argc, char **argv, char **envp)
     return ret;
 }
 
+/**
+ * @brief Sends a signal to a process or a group of processes.
+ *
+ * This system call sends the signal specified by `signo` to the process or process group
+ * identified by `pid`. If `pid` is positive, the signal is sent to the process with the
+ * specified process ID. If `pid` is `0`, the signal is sent to all processes in the
+ * same process group as the caller. If `pid` is `-1`, the signal is sent to all processes
+ * except for the caller. If `pid` is less than `-1`, the signal is sent to all processes
+ * in the process group with the process group ID equal to `-pid`.
+ *
+ * @param pid The process ID or process group ID to which the signal is to be sent.
+ *            - A positive value sends the signal to the process with that ID.
+ *            - `0` sends the signal to all processes in the same process group as the caller.
+ *            - `-1` sends the signal to all processes except the caller.
+ *            - A negative value sends the signal to all processes in the process group
+ *              with the process group ID equal to `-pid`.
+ * @param signo The signal to send. This is an integer value that specifies the signal
+ *              type. Common signal values include:
+ *              - `SIGTERM` (terminate process)
+ *              - `SIGKILL` (force kill process)
+ *              - `SIGSTOP` (suspend process)
+ *              - `SIGCONT` (resume process)
+ * @return On success, returns `0`. On failure, it returns error code to indicate the error.
+ *
+ * @note Signals are a mechanism for inter-process communication, allowing processes
+ *       to send notifications or requests to other processes. The behavior of signals
+ *       depends on the signal type and how the receiving process handles them.
+ *
+ * @warning The `signo` value must be a valid signal number. Passing an invalid signal
+ *          number or an invalid `pid` may result in an error. Additionally, some signals
+ *          (e.g., `SIGKILL`) cannot be caught or ignored by processes.
+ *
+ * @see signal(), killpg(), raise()
+ */
 sysret_t sys_kill(int pid, int signo)
 {
     rt_err_t kret = 0;
@@ -1023,11 +1478,52 @@ sysret_t sys_kill(int pid, int signo)
     return sysret;
 }
 
+/**
+ * @brief Retrieves the process ID of the calling process.
+ *
+ * This system call returns the process ID (PID) of the calling process. The PID is a
+ * unique identifier assigned by the operating system to each running process. It can
+ * be used to refer to or manipulate the process in subsequent system calls.
+ *
+ * @return The PID of the calling process. On failure, returns `-1` and sets `errno`
+ *         to indicate the error (although this function typically does not fail).
+ *
+ * @note The PID returned by this function is a positive integer, and it remains
+ *       unique during the lifetime of the process. This value can be used to manage
+ *       the process, including sending signals or querying process information.
+ *
+ * @warning This function does not take any arguments and is typically used when
+ *          a process needs to obtain its own PID for management or logging purposes.
+ *
+ * @see getppid(), getuid(), getgid()
+ */
 sysret_t sys_getpid(void)
 {
     return lwp_getpid();
 }
 
+/**
+ * @brief Retrieves the parent process ID of the calling process.
+ *
+ * This system call returns the process ID (PID) of the parent process of the calling process.
+ * The parent process is the process that created the calling process, typically through a
+ * system call like `fork()`. This information can be useful for process management and
+ * for determining the hierarchy of processes.
+ *
+ * @return The PID of the parent process. If the calling process has no parent (for example,
+ *         the init process), it typically returns `1` as the PID of the system's "root" process.
+ *         On failure, returns `-1` and sets `errno` to indicate the error (although this function
+ *         typically does not fail).
+ *
+ * @note The `getppid()` function is commonly used when a process needs to know which
+ *       process is responsible for it, or for managing relationships between parent and child processes.
+ *
+ * @warning This function does not take any arguments and is typically used when the
+ *          process requires information about its parent. It should not be confused with `getpid()`,
+ *          which retrieves the PID of the calling process itself.
+ *
+ * @see getpid(), getuid(), getgid()
+ */
 sysret_t sys_getppid(void)
 {
     rt_lwp_t process;
@@ -1044,7 +1540,31 @@ sysret_t sys_getppid(void)
     }
 }
 
-/* syscall: "getpriority" ret: "int" args: "int" "id_t" */
+/**
+ * @brief Retrieves the priority of a process or process group.
+ *
+ * This system call returns the priority of a process or a process group, depending on
+ * the value of the `which` argument.
+ *
+ * @param which The entity for which the priority is being requested. Possible values include:
+ *              - `PRIO_PROCESS`: Retrieves the priority of the process specified by `who`.
+ *              - `PRIO_PGRP`: Retrieves the priority of the process group specified by `who`. (Currently not supported.)
+ *              - `PRIO_USER`: Retrieves the priority of the user specified by `who` (the user ID). (Currently not supported.)
+ * @param who The ID of the process, process group, or user. The meaning of this parameter
+ *            depends on the value of `which`:
+ *            - When `which` is `PRIO_PROCESS`, `who` is the process ID (PID) of the process.
+ *            - When `which` is `PRIO_PGRP`(Currently not supported.), `who` is the process group ID (PGID).
+ *            - When `which` is `PRIO_USER`(Currently not supported.), `who` is the user ID (UID) of the user whose
+ *              priority is being queried.
+ * @return On success, returns the priority value (a negative integer indicates a lower
+ *         priority).
+ *
+ * @warning Ensure that `which` and `who` are correctly specified to avoid errors.
+ *          Invalid values for `which` or `who` may result in an error, and the function
+ *          will return `-1`.
+ *
+ * @see setpriority(), getpid(), getppid()
+ */
 sysret_t sys_getpriority(int which, id_t who)
 {
     long prio = 0xff;
@@ -1068,7 +1588,36 @@ sysret_t sys_getpriority(int which, id_t who)
     return prio;
 }
 
-/* syscall: "setpriority" ret: "int" args: "int" "id_t" "int" */
+/**
+ * @brief Sets the priority of a process, process group, or user.
+ *
+ * This system call sets the priority of a process, process group, or user, depending
+ * on the value of the `which` argument. The priority is used by the operating system
+ * for scheduling processes. Lower numerical values represent higher priority in many
+ * systems, and the priority range may be system-specific.
+ *
+ * @param which The entity for which the priority is being set. Possible values include:
+ *              - `PRIO_PROCESS`: Sets the priority of the process specified by `who`.
+ *              - `PRIO_PGRP`: Sets the priority of the process group specified by `who`.(Currently not supported.)
+ *              - `PRIO_USER`: Sets the priority of the user specified by `who` (the user ID).(Currently not supported.)
+ * @param who The ID of the process, process group, or user for which the priority is being set.
+ *            The meaning of this parameter depends on the value of `which`:
+ *            - When `which` is `PRIO_PROCESS`, `who` is the process ID (PID) of the process.
+ *            - When `which` is `PRIO_PGRP`(Currently not supported.)  , `who` is the process group ID (PGID).
+ *            - When `which` is `PRIO_USER`(Currently not supported.)  , `who` is the user ID (UID) of the user whose priority
+ *              is being set.
+ * @param prio The priority value to set.
+ * @return On success, returns `0`. On failure, returns `-1`.
+ *
+ * @note This function modifies the priority of the specified process, process group, or user.
+ *       The priority value is system-specific and may vary based on the system's scheduling
+ *       policies. Ensure that the specified priority is within the acceptable range.
+ *
+ * @warning Ensure that `which`, `who`, and `prio` are valid. Invalid values for these
+ *          parameters can result in errors, and the system call will return `-1`.
+ *
+ * @see getpriority(), getpid(), getppid()
+ */
 sysret_t sys_setpriority(int which, id_t who, int prio)
 {
     if (which == PRIO_PROCESS)
@@ -1099,6 +1648,36 @@ sysret_t sys_setpriority(int which, id_t who, int prio)
     return -1;
 }
 
+/**
+ * @brief Creates a semaphore.
+ *
+ * This system call creates a new semaphore with the specified `name` and initializes
+ * its value. The semaphore is used for synchronizing access to shared resources in
+ * concurrent programming. The semaphore's behavior is defined by the value (`value`)
+ * and any flags (`flag`) that specify additional properties or settings.
+ *
+ * @param name The name of the semaphore. This is a string used to identify the semaphore
+ *             in the system. The name must be unique if the system requires it for reference.
+ * @param value The initial value of the semaphore. The value typically represents the
+ *              number of available resources or tokens. The semaphore will be initialized
+ *              with this value.
+ * @param flag The flag that specifies the attributes or properties of the semaphore.
+ *             Flags can be used to define various characteristics of the semaphore,
+ *             such as whether it is binary or counting, whether it is shared, etc.
+ *
+ * @return On success, returns a handle or reference to the created semaphore. On failure,
+ *         returns `NULL`.
+ *
+ * @note Semaphores are commonly used in multithreading and multiprocessing environments
+ *       to synchronize access to shared resources and ensure proper order of execution.
+ *       The behavior of the semaphore depends on its type and the system's implementation.
+ *
+ * @warning Ensure that the `name` is unique and appropriate for your system's naming
+ *          conventions. Invalid values for `value` or `flag` may lead to errors in semaphore
+ *          creation.
+ *
+ * @see sem_wait(), sem_post(), sem_destroy()
+ */
 rt_sem_t sys_sem_create(const char *name, rt_uint32_t value, rt_uint8_t flag)
 {
     int len = 0;
@@ -1134,21 +1713,113 @@ rt_sem_t sys_sem_create(const char *name, rt_uint32_t value, rt_uint8_t flag)
     return sem;
 }
 
+/**
+ * @brief Deletes a semaphore and releases associated resources.
+ *
+ * This system call deletes an existing semaphore identified by the given handle `sem`.
+ * It releases any resources associated with the semaphore and ensures that it is no longer
+ * available for further synchronization operations. After deletion, the semaphore handle
+ * is invalid and should not be used.
+ *
+ * @param sem The semaphore handle to be deleted. This handle is obtained when the semaphore
+ *            is created using `sys_sem_create()` or similar functions.
+ *
+ * @return On success, returns `0`. On failure, returns error code.
+ *
+ * @note Deleting a semaphore is a critical operation that should be performed only when
+ *       the semaphore is no longer needed and no tasks are currently waiting or posting
+ *       to it. Deleting a semaphore while it is still in use may lead to undefined behavior.
+ *
+ * @warning Ensure that no tasks are using or blocking on the semaphore before deleting it.
+ *          Using a deleted semaphore will result in undefined behavior and potential system errors.
+ *
+ * @see sys_sem_create(), sem_wait(), sem_post()
+ */
 sysret_t sys_sem_delete(rt_sem_t sem)
 {
     return lwp_user_object_delete(lwp_self(), (rt_object_t)sem);
 }
 
+/**
+ * @brief Attempts to take (acquire) a semaphore.
+ *
+ * This system call attempts to acquire a semaphore, blocking the calling task until the
+ * semaphore becomes available or the specified timeout expires. If the semaphore is already
+ * available, the calling task will immediately take it and proceed. If the semaphore is not
+ * available, the task will block until the semaphore becomes available or the timeout period
+ * has elapsed. The `time` parameter specifies the maximum amount of time the task will block
+ * waiting for the semaphore.
+ *
+ * @param sem The semaphore handle to be taken. This handle is obtained when the semaphore
+ *            is created using `sys_sem_create()` or similar functions.
+ * @param time The maximum time to wait for the semaphore to become available. If the semaphore
+ *             is not acquired within this time period, the function will return with an error.
+ *             A value of `0` means no waiting (non-blocking), while a negative value may indicate
+ *             an infinite wait, depending on the system's implementation.
+ *
+ * @return On success, returns `0` if the semaphore was successfully taken. On failure, returns error code.
+ *
+ * @warning Ensure that the semaphore handle is valid and has been properly created before
+ *          calling this function. If the semaphore is deleted or invalid, the behavior of
+ *          this function is undefined.
+ *
+ * @see sys_sem_create(), sys_sem_delete(), sem_post()
+ */
 sysret_t sys_sem_take(rt_sem_t sem, rt_int32_t time)
 {
     return rt_sem_take_interruptible(sem, time);
 }
 
+/**
+ * @brief Releases a semaphore and wakes up any waiting tasks.
+ *
+ * This system call releases a semaphore, incrementing its value and allowing any tasks
+ * that are blocked (waiting) on the semaphore to proceed. If there are tasks waiting for
+ * the semaphore, one of them will be unblocked and allowed to take the semaphore.
+ * The release operation does not block the calling task, and it will return immediately.
+ *
+ * @param sem The semaphore handle to be released. This handle is obtained when the semaphore
+ *            is created using `sys_sem_create()` or similar functions.
+ *
+ * @return On success, returns `0`. On failure, returns error code.
+ *
+ * @warning Ensure that the semaphore handle is valid before calling this function. If the semaphore
+ *          is deleted or invalid, the behavior of this function is undefined.
+ *
+ * @see sys_sem_create(), sys_sem_delete(), sys_sem_take()
+ */
 sysret_t sys_sem_release(rt_sem_t sem)
 {
     return rt_sem_release(sem);
 }
 
+/**
+ * @brief Creates a mutex.
+ *
+ * This system call creates a new mutex with the specified `name` and initializes it
+ * with the given `flag`. The mutex is used for synchronizing access to shared resources
+ * between tasks. Mutexes are typically used to ensure that only one task can access
+ * a critical section of code or a resource at a time. The `flag` parameter allows
+ * for setting certain properties of the mutex, such as whether it is recursive or whether
+ * it can be used by multiple tasks.
+ *
+ * @param name The name of the mutex. This is a string used to uniquely identify the mutex
+ *             within the system. The name must be unique if the system requires it.
+ * @param flag The flag that specifies the attributes or properties of the mutex. Flags can
+ *             define various mutex behaviors, such as whether the mutex is recursive (allows
+ *             the same task to lock it multiple times) or whether it can be shared across
+ *             different parts of the system.
+ *
+ * @return On success, returns a handle to the created mutex. On failure, returns `-RT_NULL`.
+ *
+ * @note Mutexes are typically used to prevent race conditions and ensure mutual exclusion
+ *       when multiple tasks or threads are accessing shared resources.
+ *
+ * @warning Ensure that the `name` is unique and appropriate according to the system's
+ *          naming conventions. Invalid values for `flag` or `name` may result in errors.
+ *
+ * @see sys_mutex_delete(), sys_mutex_lock(), sys_mutex_unlock()
+ */
 rt_mutex_t sys_mutex_create(const char *name, rt_uint8_t flag)
 {
     int len = 0;
@@ -1188,28 +1859,150 @@ rt_mutex_t sys_mutex_create(const char *name, rt_uint8_t flag)
     return mutex;
 }
 
+/**
+ * @brief Deletes a mutex and releases associated resources.
+ *
+ * This system call deletes an existing mutex identified by the given handle `mutex`.
+ * It releases any resources associated with the mutex and ensures that it is no longer
+ * available for further synchronization operations. After deletion, the mutex handle
+ * becomes invalid and should not be used. This operation also ensures that no tasks
+ * can block or attempt to lock the mutex after it has been deleted.
+ *
+ * @param mutex The mutex handle to be deleted. This handle is obtained when the mutex
+ *              is created using `sys_mutex_create()` or similar functions.
+ *
+ * @return On success, returns `0`. On failure, returns error code.
+ *
+ * @warning Ensure that the mutex handle is valid before calling this function. Deleting
+ *          an already deleted or invalid mutex will result in undefined behavior.
+ *
+ * @see sys_mutex_create(), sys_mutex_lock(), sys_mutex_unlock()
+ */
 sysret_t sys_mutex_delete(rt_mutex_t mutex)
 {
     return lwp_user_object_delete(lwp_self(), (rt_object_t)mutex);
 }
 
+/**
+ * @brief Attempts to acquire (lock) a mutex.
+ *
+ * This system call attempts to acquire a mutex, blocking the calling task until the
+ * mutex becomes available or the specified timeout expires. If the mutex is available,
+ * the calling task will immediately acquire it and proceed. If the mutex is already locked
+ * by another task, the calling task will block until the mutex is released or the timeout
+ * period elapses. The `time` parameter specifies the maximum amount of time the task will
+ * block while waiting for the mutex.
+ *
+ * @param mutex The mutex handle to be locked. This handle is obtained when the mutex is
+ *              created using `sys_mutex_create()` or similar functions.
+ * @param time The maximum time to wait for the mutex to become available. If the mutex
+ *             is not acquired within this time period, the function will return an error.
+ *             A value of `0` means no waiting (non-blocking), while a negative value may
+ *             indicate an infinite wait.
+ *
+ * @return On success, returns `0` if the mutex was successfully acquired. On failure, returns error code.
+ *
+ * @warning Ensure that the mutex handle is valid and has been properly created before
+ *          calling this function. If the mutex is deleted or invalid, the behavior of
+ *          this function is undefined.
+ *
+ * @see sys_mutex_create(), sys_mutex_delete(), sys_mutex_unlock()
+ */
 sysret_t sys_mutex_take(rt_mutex_t mutex, rt_int32_t time)
 {
     return rt_mutex_take_interruptible(mutex, time);
 }
 
+/**
+ * @brief Releases (unlocks) a mutex.
+ *
+ * This system call releases a mutex that was previously acquired (locked) by the calling task.
+ * If any other task is waiting for the mutex, one of them will be unblocked and allowed to
+ * acquire the mutex. The release operation does not block the calling task, and it will return
+ * immediately after unlocking the mutex.
+ *
+ * @param mutex The mutex handle to be released. This handle is obtained when the mutex is
+ *              created using `sys_mutex_create()` or similar functions.
+ *
+ * @return On success, returns `0`. On failure, returns error code.
+ *
+ * @warning Ensure that the mutex handle is valid before calling this function. Attempting
+ *          to release a mutex that has not been locked or is already released can result
+ *          in undefined behavior.
+ *
+ * @see sys_mutex_create(), sys_mutex_delete(), sys_mutex_take()
+ */
 sysret_t sys_mutex_release(rt_mutex_t mutex)
 {
     return rt_mutex_release(mutex);
 }
 
 #ifdef ARCH_MM_MMU
-/* memory allocation */
+/**
+ * @brief Adjusts the end of the data segment (heap) of the calling process.
+ *
+ * This system call changes the location of the program break, which defines the end of
+ * the data segment (heap) of the calling process. It provides a unified interface for adjusting
+ * the heap size. The `addr` parameter specifies the new location for the program break.
+ *
+ * @param addr The new program break location. If `addr` is `NULL`, the current program
+ *             break is returned. If a valid address is provided, the program break will
+ *             be adjusted to this address. The address must be page-aligned, and changes
+ *             must stay within the process's allowed address space.
+ *
+ * @return On success, returns the new program break.
+ *
+ * @note This function is typically used to manage heap space in a process. The program
+ *       break adjustment can impact memory allocations and deallocations in the heap.
+ *
+ * @warning The `addr` must be a valid address within the process's allocated memory
+ *          space. Attempting to set an invalid program break address may result in
+ *          undefined behavior or memory corruption.
+ *
+ * @see malloc(), free(), sys_sbrk()
+ */
 rt_base_t sys_brk(void *addr)
 {
     return lwp_brk(addr);
 }
 
+/**
+ * @brief Maps a file or device into memory.
+ *
+ * This system call implements the `mmap2` system call, which maps a file or device into memory.
+ * It provides a way for processes to access file contents directly in memory, bypassing
+ * the need for explicit read or write operations. This function supports advanced memory
+ * mapping options such as shared or private mappings, specific protection flags, and
+ * offset alignment.
+ *
+ * @param addr The starting address for the memory mapping. If `NULL`, the kernel chooses
+ *             the address. If not `NULL`, the address must be page-aligned and meet
+ *             platform-specific alignment constraints.
+ * @param length The length of the memory mapping in bytes. This value is rounded up to
+ *               the nearest page size.
+ * @param prot The memory protection flags. Possible values include:
+ *             - `PROT_READ`: Pages can be read.
+ *             - `PROT_WRITE`: Pages can be written.
+ *             - `PROT_EXEC`: Pages can be executed.
+ *             - `PROT_NONE`: Pages cannot be accessed.
+ *             These flags can be combined using bitwise OR (`|`).
+ * @param flags Flags that determine the type and behavior of the mapping. Possible values include:
+ *              - `MAP_SHARED`: Updates are visible to other processes that map this file.
+ *              - `MAP_PRIVATE`: Updates are not visible to other processes and are not written to the file.
+ *              - `MAP_FIXED`: Use the exact address specified in `addr`.
+ *              - `MAP_ANONYMOUS`: The mapping is not backed by a file and uses zero-initialized memory.
+ * @param fd The file descriptor of the file to map. If `MAP_ANONYMOUS` is set in `flags`,
+ *           `fd` is ignored and should be set to `-1`.
+ * @param pgoffset The offset in the file where the mapping starts, specified in pages (not bytes).
+ *                 This allows finer-grained control over the starting point of the mapping.
+ *
+ * @return On success, returns a pointer to the mapped memory region.
+ *
+ * @warning Ensure that the combination of `addr`, `length`, `prot`, `flags`, and `fd` is valid.
+ *          Improper use may lead to undefined behavior or memory access violations.
+ *
+ * @see mmap(), munmap(), msync()
+ */
 void *sys_mmap2(void *addr, size_t length, int prot,
         int flags, int fd, size_t pgoffset)
 {
@@ -1245,11 +2038,62 @@ void *sys_mmap2(void *addr, size_t length, int prot,
     return rc < 0 ? (char *)rc : (char *)rc + offset;
 }
 
+/**
+ * @brief Unmaps a memory region previously mapped with mmap or mmap2.
+ *
+ * This system call implements the `munmap` system call, which removes a mapping
+ * for a region of memory that was previously created using `mmap` or `mmap2`.
+ *
+ * @param addr The starting address of the memory region to unmap. This address
+ *             must be page-aligned and refer to a region previously mapped.
+ * @param length The length of the memory region to unmap, in bytes. This value
+ *               is rounded up to the nearest page size internally if needed.
+ *
+ * @return On success, returns `0`. On failure, returns error code.
+ *
+ * @warning
+ * - Ensure the specified memory region corresponds to a valid, active mapping.
+ *   Providing invalid parameters may result in undefined behavior.
+ * - Unmapping a region that is still in use by another thread or process can
+ *   cause concurrency issues or data corruption.
+ *
+ * @see mmap(), mmap2(), msync()
+ */
 sysret_t sys_munmap(void *addr, size_t length)
 {
     return lwp_munmap(lwp_self(), addr, length);
 }
 
+/**
+ * @brief Changes the size or location of an existing memory mapping.
+ *
+ * This system call implements the `mremap` system call, allowing the resizing
+ * or relocation of a previously created memory mapping. It is typically used
+ * to dynamically adjust memory allocation for mapped regions without unmapping
+ * and remapping them explicitly.
+ *
+ * @param old_address The starting address of the existing memory mapping to be resized
+ *                    or relocated. This must be the address returned by a previous
+ *                    `mmap` or `mremap` call.
+ * @param old_size The current size of the memory mapping, in bytes. It must match
+ *                 the size of the original mapping.
+ * @param new_size The new desired size of the memory mapping, in bytes. The size will
+ *                 be rounded up to the nearest page size if necessary.
+ * @param flags Options to control the behavior of the remapping. Possible values include:
+ *              - `MREMAP_MAYMOVE`: Allows the kernel to move the mapping to a new
+ *                address if the current region cannot be resized in place.
+ *              - `MREMAP_FIXED`: Requires the mapping to be relocated to the
+ *                specified `new_address`. This flag must be used with caution.
+ * @param new_address If `MREMAP_FIXED` is set in `flags`, this specifies the address
+ *                    for the new mapping. Otherwise, it is ignored.
+ *
+ * @return On success, returns a pointer to the resized or relocated memory mapping.
+ *
+ * @warning
+ * - Ensure that the `old_address` and `old_size` correspond to a valid, existing mapping.
+ *
+ * @see mmap(), munmap(), msync()
+ */
 void *sys_mremap(void *old_address, size_t old_size,
              size_t new_size, int flags, void *new_address)
 {
@@ -1262,6 +2106,31 @@ sysret_t sys_madvise(void *addr, size_t len, int behav)
 }
 #endif
 
+/**
+ * @brief Creates an event object for inter-thread or inter-process communication.
+ *
+ * @param name A string representing the name of the event. If `NULL`, the event will
+ *             be created without a name. Named events can be identified and accessed
+ *             globally if supported by the system.
+ * @param flag Specifies the behavior of the event. Possible values include:
+ *             - `RT_IPC_FLAG_FIFO`: Events are handled in a first-in, first-out order.
+ *             - `RT_IPC_FLAG_PRIO`: Events are handled in priority order.
+ *
+ * @return On success, returns a handle (`rt_event_t`) to the created event. On failure,
+ *         returns `-RT_NULL` to indicate that the event could not be created.
+ *
+ * @note
+ * - The event object must be explicitly deleted using `sys_event_delete` when it is
+ *   no longer needed to free system resources.
+ *
+ * @warning
+ * - Ensure that sufficient system resources (e.g., memory) are available to create
+ *   the event. If resources are insufficient, the function will fail.
+ * - Named events can potentially lead to naming conflicts if multiple events with
+ *   the same name are created. Use unique names to avoid such issues.
+ *
+ * @see sys_event_delete(), sys_event_send(), sys_event_recv()
+ */
 rt_event_t sys_event_create(const char *name, rt_uint8_t flag)
 {
     int len = 0;
@@ -1298,16 +2167,103 @@ rt_event_t sys_event_create(const char *name, rt_uint8_t flag)
     return event;
 }
 
+/**
+ * @brief Deletes a system event object.
+ *
+ * This system call removes the specified system event object, releasing
+ * any resources associated with it. After deletion, the event object
+ * should not be used.
+ *
+ * @param[in] event The handle to the event object to be deleted.
+ *                  Must be a valid `rt_event_t` object.
+ *
+ * @return sysret_t Returns a status code indicating the result of the
+ *                   operation:
+ *                   - `0` if the operation was successful.
+ *                   - An appropriate error code otherwise.
+ *
+ * @note Ensure that the event is no longer being accessed by any
+ *       threads or tasks before calling this function.
+ *
+ * @warning Deleting an event that is in use or invalid may lead to
+ *          undefined behavior.
+ * @see sys_event_create(), sys_event_send(), sys_event_recv()
+ */
 sysret_t sys_event_delete(rt_event_t event)
 {
     return lwp_user_object_delete(lwp_self(), (rt_object_t)event);
 }
 
+/**
+ * @brief Sends an event to the specified event object.
+ *
+ * This system call sends an event to the specified event object, setting
+ * the specified bits in the event object's set. The event can be used
+ * to signal other threads or tasks that a particular condition has
+ * occurred.
+ *
+ * @param[in] event The handle to the event object to which the event
+ *                  will be sent. Must be a valid `rt_event_t` object.
+ * @param[in] set The bits to set in the event object's set. The bits
+ *                are specified as a bitmask, where each bit represents
+ *                a different event condition.
+ *
+ * @return sysret_t Returns a status code indicating the result of the
+ *                   operation:
+ *                   - `0` if the operation was successful.
+ *                   - An appropriate error code otherwise.
+ *
+ * @note The event object must be created before sending events to it.
+ *
+ * @warning Ensure that the event object is valid and has been created
+ *          before calling this function.
+ * @see sys_event_create(), sys_event_recv()
+ */
 sysret_t sys_event_send(rt_event_t event, rt_uint32_t set)
 {
     return rt_event_send(event, set);
 }
 
+/**
+ * @brief Receives an event from the specified event object.
+ *
+ * This system call waits for an event to be received from the specified
+ * event object. The function blocks until the specified event bits are
+ * set in the event object's set or the specified timeout period has
+ * elapsed. If the event is received, the function returns the set of
+ * bits that were set in the event object.
+ *
+ * @param[in] event The handle to the event object from which the event
+ *                  will be received. Must be a valid `rt_event_t` object.
+ * @param[in] set The bits to wait for in the event object's set. The
+ *                bits are specified as a bitmask, where each bit
+ *                represents a different event condition.
+ * @param[in] opt The options for receiving the event. Possible values
+ *                include:
+ *                - `EV_EVENT_ANY`: Wait for any of the specified bits
+ *                  to be set.
+ *                - `EV_EVENT_ALL`: Wait for all of the specified bits
+ *                  to be set.
+ * @param[in] timeout The maximum time to wait for the event to be
+ *                    received, in milliseconds. A value of `0` means
+ *                    no waiting (non-blocking), while a negative value
+ *                    may indicate an infinite wait.
+ * @param[out] recved A pointer to a variable that will receive the set
+ *                    of bits that were set in the event object. If the
+ *                    event is received, this variable will be updated
+ *                    with the set of bits.
+ *
+ * @return sysret_t Returns a status code indicating the result of the
+ *                   operation:
+ *                   - `0` if the operation was successful.
+ *                   - An appropriate error code otherwise.
+ *
+ * @note The event object must be created before receiving events from it.
+ *
+ * @warning Ensure that the event object is valid and has been created
+ *          before calling this function.
+ * @see sys_event_create(), sys_event_send()
+ */
 sysret_t sys_event_recv(rt_event_t   event,
                        rt_uint32_t  set,
                        rt_uint8_t   opt,
@@ -1331,6 +2287,38 @@ sysret_t sys_event_recv(rt_event_t   event,
     return ret;
 }
 
+/**
+ * @brief Creates a mailbox for inter-thread or inter-process communication.
+ *
+ * This system call creates a mailbox object with the specified name and size.
+ * The mailbox is used to exchange messages between threads or tasks in a
+ * synchronized manner. The mailbox can be used to send and receive messages
+ * of a specified size.
+ *
+ * @param[in] name A string representing the name of the mailbox. If `NULL`,
+ *                 the mailbox will be created without a name. Named mailboxes
+ *                 can be identified and accessed globally if supported by the system.
+ * @param[in] size The size of the mailbox, which determines the maximum number
+ *                 of messages that can be stored in the mailbox at any given time.
+ * @param[in] flag The behavior of the mailbox. Possible values include:
+ *                 - `RT_IPC_FLAG_FIFO`: Messages are handled in a first-in, first-out order.
+ *                 - `RT_IPC_FLAG_PRIO`: Messages are handled in priority order.
+ *
+ * @return rt_mailbox_t Returns a handle to the created mailbox object.
+ *                      On failure, returns `-RT_NULL`.
+ *
+ * @note
+ * - The mailbox object must be explicitly deleted using `sys_mb_delete` when it is
+ *   no longer needed to free system resources.
+ *
+ * @warning
+ * - Ensure that sufficient system resources (e.g., memory) are available to create
+ *   the mailbox. If resources are insufficient, the function will fail.
+ * - Named mailboxes can potentially lead to naming conflicts if multiple mailboxes
+ *   with the same name are created. Use unique names to avoid such issues.
+ *
+ * @see sys_mb_delete(), sys_mb_send(), sys_mb_recv()
+ */
 rt_mailbox_t sys_mb_create(const char *name, rt_size_t size, rt_uint8_t flag)
 {
     int len = 0;
@@ -1367,16 +2355,95 @@ rt_mailbox_t sys_mb_create(const char *name, rt_size_t size, rt_uint8_t flag)
     return mb;
 }
 
+/**
+ * @brief Deletes a mailbox object.
+ *
+ * This system call deletes the specified mailbox object, releasing any resources
+ * associated with it. After deletion, the mailbox object should not be used.
+ *
+ * @param[in] mb The handle to the mailbox object to be deleted.
+ *               Must be a valid `rt_mailbox_t` object.
+ *
+ * @return sysret_t Returns a status code indicating the result of the operation:
+ *                   - `0` if the operation was successful.
+ *                   - An appropriate error code otherwise.
+ *
+ * @note Ensure that the mailbox is no longer being accessed by any threads or tasks
+ *       before calling this function.
+ *
+ * @warning Deleting a mailbox that is in use or invalid may lead to undefined behavior.
+ *
+ * @see sys_mb_create(), sys_mb_send(), sys_mb_recv()
+ */
 sysret_t sys_mb_delete(rt_mailbox_t mb)
 {
     return lwp_user_object_delete(lwp_self(), (rt_object_t)mb);
 }
 
+/**
+ * @brief Sends a message to a mailbox object.
+ *
+ * This system call posts a message (a single value) to the specified mailbox.
+ * If the mailbox is full, the function will return an error code immediately without waiting time.
+ *
+ * @param[in] mb    The handle to the mailbox object where the message
+ *                  will be sent. Must be a valid `rt_mailbox_t` object.
+ * @param[in] value The value to be sent to the mailbox. Typically, this
+ *                  is a pointer or an integral value that represents
+ *                  the message content.
+ *
+ * @return sysret_t Returns a status code indicating the result of the
+ *                   operation:
+ *                   - `0` if the message was successfully sent.
+ *                   - `-RT_EFULL` if the mailbox is full.
+ *                   - An appropriate error code for other failures.
+ *
+ * @note Ensure the mailbox has been properly initialized before calling
+ *       this function. Sending messages to an uninitialized or invalid
+ *       mailbox may result in undefined behavior.
+ *
+ * @warning If the mailbox is full and the function blocks, ensure
+ *          proper handling to avoid potential deadlocks.
+ *
+ * @see sys_mb_create(), sys_mb_recv(), sys_mb_send_wait()
+ */
 sysret_t sys_mb_send(rt_mailbox_t mb, rt_ubase_t value)
 {
     return rt_mb_send(mb, value);
 }
 
+/**
+ * @brief Sends a message to a mailbox object with a timeout.
+ *
+ * This system call attempts to post a message (a single value) to the specified mailbox.
+ * If the mailbox is full, the function will wait for a specified timeout period
+ * for space to become available. If the timeout expires before the message is sent,
+ * the function returns an error.
+ *
+ * @param[in] mb       The handle to the mailbox object where the message
+ *                     will be sent. Must be a valid `rt_mailbox_t` object.
+ * @param[in] value    The value to be sent to the mailbox. Typically, this
+ *                     is a pointer or an integral value representing the
+ *                     message content.
+ * @param[in] timeout  The maximum time to wait for space to become available
+ *                     in the mailbox, in milliseconds.
+ *                     - a negative value can be used to wait indefinitely.
+ *                     - `0` can be used for non-blocking behavior.
+ *
+ * @return sysret_t Returns a status code indicating the result of the
+ *                   operation:
+ *                   - `0` if the message was successfully sent.
+ *                   - `-RT_ETIMEOUT` if the operation timed out.
+ *                   - `-RT_EFULL` if the mailbox is full and `timeout` is `0`.
+ *                   - An appropriate error code for other failures.
+ *
+ * @note Ensure the mailbox has been properly initialized before calling this function.
+ *       Passing an uninitialized or invalid mailbox handle may result in undefined behavior.
+ *
+ * @warning Using a negative value without appropriate logic may lead to indefinite blocking,
+ *          potentially causing deadlocks.
+ * @see sys_mb_send()
+ */
 sysret_t sys_mb_send_wait(rt_mailbox_t mb,
                          rt_ubase_t  value,
                          rt_int32_t   timeout)
@@ -1384,6 +2451,34 @@ sysret_t sys_mb_send_wait(rt_mailbox_t mb,
     return rt_mb_send_wait(mb, value, timeout);
 }
 
+/**
+ * @brief Receives a message from a mailbox with a timeout.
+ *
+ * This system call attempts to receive a message from the specified mailbox.
+ * If the mailbox is empty, the function will wait for a specified timeout
+ * period for a message to arrive. If no message is received within the timeout,
+ * an error is returned.
+ *
+ * @param[in]  mb       The handle to the mailbox object from which the message
+ *                      is to be received. Must be a valid `rt_mailbox_t` object.
+ * @param[out] value    Pointer to a variable where the received message will
+ *                      be stored. Must not be NULL.
+ * @param[in]  timeout  The maximum time to wait for a message, in milliseconds.
+ *                      - a negative value: Wait indefinitely until a message is available.
+ *                      - `0`: Non-blocking mode. If no message is available, return immediately.
+ *
+ * @return sysret_t Returns a status code indicating the result of the operation:
+ *                   - `0`: The message was successfully received.
+ *                   - `-RT_ETIMEOUT`: The operation timed out before a message was received.
+ *                   - Other error codes may indicate failures.
+ *
+ * @note Ensure the mailbox is properly initialized and the `value` pointer
+ *       is valid before calling this function. Passing an invalid mailbox
+ *       or NULL `value` pointer may lead to undefined behavior.
+ *
+ * @warning Using a negative value without proper safeguards may cause
+ *          indefinite blocking, potentially resulting in deadlocks.
+ */
 sysret_t sys_mb_recv(rt_mailbox_t mb, rt_ubase_t *value, rt_int32_t timeout)
 {
     int ret = 0;
@@ -1416,6 +2511,29 @@ rt_weak int syslog_ctrl(int type, char *buf, int len)
     return -EINVAL;
 }
 
+/**
+ * @brief Sends a log message to the system log.
+ *
+ * This system call sends a message to the system log for recording or debugging purposes.
+ *
+ * @param[in] type  The type of the log message, typically representing the severity
+ *                  or category (e.g., debug, info, warning, error). This should be
+ *                  a valid predefined log type.
+ * @param[in] buf   A pointer to a buffer containing the log message. Must be a
+ *                  null-terminated string and a valid pointer.
+ * @param[in] len   The length of the log message to be sent, excluding the null
+ *                  terminator. If the length exceeds the system log's limit,
+ *                  the message may be truncated.
+ *
+ * @return sysret_t Returns a status code indicating the result of the operation:
+ *                   - `0`: The log message was successfully recorded.
+ *                   - Other error codes may indicate additional failures.
+ *
+ * @note Ensure the log type is a valid predefined value supported by the system.
+ *       The buffer must remain valid and accessible during the execution of this function.
+ *
+ * @warning Sending excessively large or frequent log messages may impact system performance.
+ */
 sysret_t sys_syslog(int type, char *buf, int len)
 {
     char *tmp;
@@ -1439,6 +2557,36 @@ sysret_t sys_syslog(int type, char *buf, int len)
     return ret;
 }
 
+/**
+ * @brief Creates a message queue.
+ *
+ * This system call creates a new message queue with a specified name, message size,
+ * maximum number of messages, and associated flags. The message queue allows
+ * messages of a given size to be sent and received between tasks or threads.
+ *
+ * @param[in]  name      The name of the message queue. It should be a unique
+ *                       identifier and a null-terminated string.
+ * @param[in]  msg_size  The size of each message in the queue. This defines
+ *                       the maximum size for individual messages that can
+ *                       be sent or received.
+ * @param[in]  max_msgs  The maximum number of messages the queue can hold.
+ *                       If the queue is full, further send operations may
+ *                       block or return an error depending on the flags.
+ * @param[in]  flag      Flags that control the behavior of the message queue.
+ *                       This can specify whether the queue is blocking,
+ *                       non-blocking, or has other specific attributes.
+ *
+ * @return rt_mq_t  Returns the handle to the created message queue, or `NULL`
+ *                  if the creation failed (e.g., due to invalid parameters
+ *                  or insufficient resources).
+ *
+ * @note Ensure that the message queue name is unique. The size of the messages
+ *       and the number of messages should be chosen based on the application
+ *       requirements.
+ *
+ * @warning Creating too many message queues or setting an overly large
+ *          `max_msgs` may lead to resource exhaustion.
+ */
 rt_mq_t sys_mq_create(const char *name,
                      rt_size_t   msg_size,
                      rt_size_t   max_msgs,
@@ -1479,11 +2627,58 @@ rt_mq_t sys_mq_create(const char *name,
     return mq;
 }
 
+/**
+ * @brief Deletes a message queue.
+ *
+ * This system call deletes the specified message queue and releases any resources
+ * associated with it. After calling this function, the message queue handle
+ * becomes invalid and should not be used.
+ *
+ * @param[in] mq  The handle to the message queue to be deleted.
+ *               Must be a valid `rt_mq_t` object.
+ *
+ * @return sysret_t Returns a status code indicating the result of the operation:
+ *                   - `0`: The message queue was successfully deleted.
+ *                   - An appropriate error code for other failures.
+ *
+ * @note Ensure that no tasks or threads are using the message queue before
+ *       deleting it to avoid undefined behavior or data loss.
+ *
+ * @warning Deleting an active message queue that is being used by tasks or
+ *          threads may lead to resource leaks or corruption. Ensure proper
+ *          synchronization before deletion.
+ */
 sysret_t sys_mq_delete(rt_mq_t mq)
 {
     return lwp_user_object_delete(lwp_self(), (rt_object_t)mq);
 }
 
+/**
+ * @brief Sends a message to a message queue.
+ *
+ * This system call sends a message to the specified message queue. The message
+ * is copied into the queue's buffer. If the queue is full, the behavior will
+ * depend on the flags set during queue creation (e.g., whether it is blocking
+ * or non-blocking).
+ *
+ * @param[in] mq     The handle to the message queue where the message will be sent.
+ *                   Must be a valid `rt_mq_t` object.
+ * @param[in] buffer A pointer to the message data to be sent. This must not be NULL.
+ * @param[in] size   The size of the message to be sent, in bytes. This should be
+ *                   less than or equal to the maximum message size defined when
+ *                   the queue was created.
+ *
+ * @return sysret_t  Returns a status code indicating the result of the operation:
+ *                    - `0`: The message was successfully sent to the queue.
+ *                    - An appropriate error code for other failures.
+ *
+ * @note Ensure that the message size does not exceed the maximum allowed message
+ *       size when the queue was created. Passing an invalid queue handle or buffer
+ *       may result in undefined behavior.
+ *
+ * @warning Sending messages to a full queue in blocking mode may cause the calling
+ *          task or thread to block indefinitely if not properly handled.
+ */
 sysret_t sys_mq_send(rt_mq_t mq, void *buffer, rt_size_t size)
 {
     int ret = 0;
@@ -1513,6 +2708,34 @@ sysret_t sys_mq_send(rt_mq_t mq, void *buffer, rt_size_t size)
     return ret;
 }
 
+/**
+ * @brief Sends an urgent message to a message queue.
+ *
+ * This system call sends a message to the specified message queue with higher priority,
+ * meaning it will be placed at the front of the queue, bypassing normal message
+ * order. The message is copied into the queue's buffer. If the queue is full,
+ * the behavior will depend on the flags set during queue creation (e.g., whether
+ * it is blocking or non-blocking).
+ *
+ * @param[in] mq     The handle to the message queue where the message will be sent.
+ *                   Must be a valid `rt_mq_t` object.
+ * @param[in] buffer A pointer to the message data to be sent. This must not be NULL.
+ * @param[in] size   The size of the message to be sent, in bytes. This should be
+ *                   less than or equal to the maximum message size defined when
+ *                   the queue was created.
+ *
+ * @return sysret_t  Returns a status code indicating the result of the operation:
+ *                    - `0`: The urgent message was successfully sent to the queue.
+ *                    - `-RT_EFULL`: The queue is full and the message could not be sent.
+ *                    - An appropriate error code for other failures.
+ *
+ * @note Ensure that the message size does not exceed the maximum allowed message
+ *       size when the queue was created. The urgent message will be processed before
+ *       other normal messages in the queue.
+ *
+ * @warning Sending urgent messages to a full queue in blocking mode may cause the
+ *          calling task or thread to block indefinitely if not properly handled.
+ */
 sysret_t sys_mq_urgent(rt_mq_t mq, void *buffer, rt_size_t size)
 {
     int ret = 0;
@@ -1542,6 +2765,36 @@ sysret_t sys_mq_urgent(rt_mq_t mq, void *buffer, rt_size_t size)
     return ret;
 }
 
+/**
+ * @brief Receives a message from a message queue.
+ *
+ * This system call attempts to receive a message from the specified message queue.
+ * The message is copied into the provided buffer. If no message is available
+ * in the queue, the function will block for a specified timeout period before
+ * returning. If the timeout expires without receiving a message, an error is returned.
+ *
+ * @param[in]  mq       The handle to the message queue from which the message
+ *                      will be received. Must be a valid `rt_mq_t` object.
+ * @param[out] buffer   A pointer to the buffer where the received message will
+ *                      be stored. Must not be NULL and large enough to hold the
+ *                      message.
+ * @param[in]  size     The size of the buffer, in bytes. This should be at least
+ *                      the size of a message in the queue.
+ * @param[in]  timeout  The maximum time to wait for a message, in milliseconds.
+ *                      - a negative value: Wait indefinitely until a message is available.
+ *                      - `0`: Non-blocking mode. If no message is available, return immediately.
+ *
+ * @return sysret_t Returns a status code indicating the result of the operation:
+ *                   - `0`: The message was successfully received.
+ *                   - `-RT_ETIMEOUT`: The operation timed out before a message was received.
+ *                   - Other error codes may indicate additional failures.
+ *
+ * @note Ensure the buffer is large enough to store the message received from the queue.
+ *       If the buffer is too small, the function may fail or behave unexpectedly.
+ *
+ * @warning Using a negative value without proper safeguards may cause indefinite
+ *          blocking, potentially resulting in deadlocks if no message is received.
+ */
 sysret_t sys_mq_recv(rt_mq_t    mq,
                     void      *buffer,
                     rt_size_t  size,
@@ -1576,6 +2829,34 @@ static void timer_timeout_callback(void *parameter)
     rt_sem_release(sem);
 }
 
+/**
+ * @brief Creates a timer.
+ *
+ * This system call creates a timer that can be used to trigger events or
+ * actions after a specified timeout or interval. The timer will operate in a
+ * real-time manner and can be configured to trigger once or repeatedly. The
+ * created timer can be started, stopped, or deleted as required.
+ *
+ * @param[in]  name   The name of the timer. It should be a unique string identifier.
+ *                    The name is used for debugging and logging purposes.
+ * @param[in]  data   A pointer to user-defined data that will be passed to the timer's
+ *                    callback function when it is triggered. This may be used to carry
+ *                    context or other necessary information for the callback.
+ * @param[in]  period The timer period in milliseconds. The timer will trigger every
+ *                    `period` milliseconds, or after the specified timeout.
+ * @param[in]  flag   Flags that control the behavior of the timer. These can specify
+ *                    whether the timer is one-shot (triggers once) or periodic
+ *                    (triggers repeatedly).
+ *
+ * @return rt_timer_t Returns the handle to the created timer, or `NULL` if the creation failed.
+ *
+ * @note The timer callback function must be implemented to handle the event triggered
+ *       by the timer. Ensure that the `data` parameter, if used, is properly handled
+ *       in the callback.
+ *
+ * @warning Ensure the timer's period and flags are configured correctly to avoid
+ *          undesired behavior, especially if the timer is periodic.
+ */
 rt_timer_t sys_rt_timer_create(const char *name,
                                void *data,
                                rt_tick_t time,
@@ -1615,21 +2896,102 @@ rt_timer_t sys_rt_timer_create(const char *name,
     return timer;
 }
 
+/**
+ * @brief Deletes a timer.
+ *
+ * This system call deletes the specified timer and releases any resources
+ * associated with it. Once the timer is deleted, its handle becomes invalid,
+ * and any further operations on the timer should be avoided.
+ *
+ * @param[in] timer  The handle to the timer to be deleted. Must be a valid `rt_timer_t` object.
+ *
+ * @return sysret_t Returns a status code indicating the result of the operation:
+ *                   - `0`: The timer was successfully deleted.
+ *                   - Other error codes may indicate additional failures.
+ *
+ * @note Ensure that the timer is not active or being used before deleting it to avoid
+ *       any unexpected behavior or resource leaks.
+ *
+ * @warning Deleting an active timer may lead to undefined behavior, especially
+ *          if the timer is in the middle of triggering or executing its callback.
+ */
 sysret_t sys_rt_timer_delete(rt_timer_t timer)
 {
     return lwp_user_object_delete(lwp_self(), (rt_object_t)timer);
 }
 
+/**
+ * @brief Starts a timer.
+ *
+ * This system call starts the specified timer, causing it to begin counting down
+ * based on its configured period. Once the timer reaches the set period, it triggers the
+ * associated callback function. The behavior depends on whether the timer is configured
+ * as one-shot or periodic.
+ *
+ * @param[in] timer  The handle to the timer to be started. Must be a valid `rt_timer_t` object.
+ *
+ * @return sysret_t  Returns a status code indicating the result of the operation:
+ *                    - `0`: The timer was successfully started.
+ *                    - Other error codes may indicate additional failures.
+ *
+ * @note Ensure that the timer has been created and is in a valid state before attempting to start it.
+ *
+ * @warning Starting a timer that is already running may lead to undefined behavior. Ensure that the
+ *          timer is stopped or not in use before starting it.
+ */
 sysret_t sys_rt_timer_start(rt_timer_t timer)
 {
     return rt_timer_start(timer);
 }
 
+/**
+ * @brief Stops a timer.
+ *
+ * This system call stops the specified timer, halting its countdown and
+ * preventing it from triggering further callbacks. If the timer is periodic,
+ * stopping it will prevent further periodic triggers until it is started again.
+ *
+ * @param[in] timer  The handle to the timer to be stopped. Must be a valid `rt_timer_t` object.
+ *
+ * @return sysret_t  Returns a status code indicating the result of the operation:
+ *                    - `0`: The timer was successfully stopped.
+ *                    - Other error codes may indicate additional failures.
+ *
+ * @note Ensure that the timer is in a valid state before attempting to stop it.
+ *       Stopping an inactive or already stopped timer may not have any effect.
+ *
+ * @warning Stopping a timer that is actively triggering or in use may disrupt its expected
+ *          behavior. Ensure proper synchronization or state management when stopping
+ *          the timer during active use.
+ */
 sysret_t sys_rt_timer_stop(rt_timer_t timer)
 {
     return rt_timer_stop(timer);
 }
 
+/**
+ * @brief Controls various properties of a timer.
+ *
+ * This system call provides control over various aspects of a timer, such as
+ * modifying its configuration, querying its status, or changing its behavior.
+ * The specific behavior is determined by the command (`cmd`) and any associated arguments (`arg`).
+ *
+ * @param[in]  timer  The handle to the timer to be controlled. Must be a valid `rt_timer_t` object.
+ * @param[in]  cmd    The command to execute. The meaning of this parameter depends on the command value.
+ *                    Common commands might include modifying the timer period, changing its callback,
+ *                    or querying its current state.
+ * @param[in]  arg    A pointer to any additional arguments needed for the command. The type and content
+ *                    of this argument depend on the specific command being executed.
+ *
+ * @return sysret_t  Returns a status code indicating the result of the operation:
+ *                    - `0`: The timer control operation was successful.
+ *                    - Other error codes may indicate additional failures.
+ *
+ * @note Ensure that the provided command (`cmd`) is valid for the specific timer implementation.
+ *       Incorrect commands or arguments may lead to unexpected behavior or errors.
+ *
+ * @warning Using invalid or unsupported commands may cause undefined behavior or crashes.
+ */
 sysret_t sys_rt_timer_control(rt_timer_t timer, int cmd, void *arg)
 {
     return rt_timer_control(timer, cmd, arg);
@@ -1647,6 +3009,31 @@ struct ksigevent
 /* to protect unsafe implementation in current rt-smart toolchain */
 RT_STATIC_ASSERT(sigevent_compatible, offsetof(struct ksigevent, sigev_tid) == offsetof(struct sigevent, sigev_notify_function));
 
+/**
+ * @brief Creates a per-process timer.
+ *
+ * This system call creates a new timer associated with the specified clock, and
+ * initializes the timer with the provided event notification attributes.
+ * Once created, the timer can be started, stopped, or controlled as needed.
+ * The timer will trigger when the specified expiration time or interval is reached.
+ *
+ * @param[in]  clockid   The clock to be used for the timer. Common clock values include:
+ *                       - `CLOCK_REALTIME`: System real-time clock.
+ *                       - `CLOCK_MONOTONIC`: Monotonic clock that cannot be set and is not affected by system time changes.
+ *                       - Other clock IDs can be used depending on the platform and requirements.
+ * @param[in]  sevp      A pointer to a `sigevent` structure that specifies how the process
+ *                       should be notified when the timer expires. This can include notification
+ *                       types such as signal delivery, thread notification, or posting to a queue.
+ * @param[out] timerid   A pointer to a `timer_t` variable where the created timer's ID will be stored.
+ *                       The timer ID will be used for subsequent timer operations (e.g., starting, stopping).
+ *
+ * @return sysret_t      Returns a status code indicating the result of the operation:
+ *                       - `0`: The timer was successfully created.
+ *                       - Other error codes may indicate additional failures.
+ *
+ * @warning Ensure that the provided `sigevent` structure is properly configured, as invalid or
+ *          unsupported notification types may result in unexpected behavior.
+ */
 sysret_t sys_timer_create(clockid_t clockid, struct sigevent *restrict sevp, timer_t *restrict timerid)
 {
     int ret = 0;
@@ -1689,12 +3076,62 @@ sysret_t sys_timer_create(clockid_t clockid, struct sigevent *restrict sevp, tim
     return ret;
 }
 
+/**
+ * @brief Deletes a timer.
+ *
+ * This system call deletes the specified timer and releases any resources associated
+ * with it. Once the timer is deleted, it can no longer be used, and any further
+ * operations on the timer (such as starting or stopping) will result in an error.
+ *
+ * @param[in] timerid  The ID of the timer to be deleted. This is the timer handle
+ *                     returned by `sys_timer_create`.
+ *
+ * @return sysret_t    Returns a status code indicating the result of the operation:
+ *                     - `0`: The timer was successfully deleted.
+ *                     - Other error codes may indicate additional failures.
+ *
+ * @note After calling this function, the timer ID becomes invalid, and it should
+ *       not be used in any further operations.
+ *
+ * @warning Make sure the timer is not active or in use when attempting to delete it,
+ *          as deleting an active timer may cause unexpected behavior or resource leaks.
+ */
 sysret_t sys_timer_delete(timer_t timerid)
 {
     int ret = timer_delete(timerid);
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Changes the time or interval of an existing timer.
+ *
+ * This system call modifies the expiration time or interval of a previously created
+ * timer. It can either set a new expiration time for the timer or update the
+ * interval for periodic timers. The timer can be started or modified based on
+ * the flags provided. The current (old) timer settings can be retrieved if
+ * requested.
+ *
+ * @param[in]  timerid      The ID of the timer to modify. This is the timer handle
+ *                          returned by `sys_timer_create`.
+ * @param[in]  flags        Flags that control the behavior of the operation. Common
+ *                          values include:
+ *                          - `TIMER_ABSTIME`: Specifies that `new_value` contains
+ *                            an absolute time. Otherwise, it is treated as relative.
+ * @param[in]  new_value    A pointer to the `itimerspec` structure specifying
+ *                          the new time settings for the timer. The structure includes:
+ *                          - `it_value`: The initial expiration time (relative or absolute).
+ *                          - `it_interval`: The period for periodic timers.
+ * @param[out] old_value    A pointer to an `itimerspec` structure where the previous
+ *                          timer settings will be stored. If NULL, the old value is ignored.
+ *
+ * @return sysret_t         Returns a status code indicating the result of the operation:
+ *                          - `0`: The timer time/interval was successfully updated.
+ *                          - Other error codes may indicate additional failures.
+ *
+ * @warning Modifying a timer that is currently active can cause timing-related issues
+ *          if not handled correctly. Make sure the timer is in an appropriate state
+ *          before making changes.
+ */
 sysret_t sys_timer_settime(timer_t timerid, int flags,
                            const struct itimerspec *restrict new_value,
                            struct itimerspec *restrict old_value)
@@ -1719,6 +3156,27 @@ sysret_t sys_timer_settime(timer_t timerid, int flags,
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Retrieves the current time and interval of a timer.
+ *
+ * This system call fetches the current expiration time (`it_value`) and interval (`it_interval`)
+ * of a previously created timer. It allows the caller to determine the current state of the timer,
+ * whether it is one-shot or periodic, and the remaining time before expiration.
+ *
+ * @param[in]  timerid      The ID of the timer to query. This is the timer handle
+ *                          returned by `sys_timer_create`.
+ * @param[out] curr_value   A pointer to an `itimerspec` structure where the current timer values
+ *                          will be stored. This structure includes:
+ *                          - `it_value`: The remaining time until the timer expires.
+ *                          - `it_interval`: The interval between subsequent expirations (for periodic timers).
+ *
+ * @return sysret_t         Returns a status code indicating the result of the operation:
+ *                          - `0`: The current time/interval was successfully retrieved.
+ *                          - Other error codes may indicate additional failures.
+ *
+ * @warning Ensure that the timer ID is valid before calling this function, as invalid timer IDs
+ *          will result in errors.
+ */
 sysret_t sys_timer_gettime(timer_t timerid, struct itimerspec *curr_value)
 {
     int ret = 0;
@@ -1734,6 +3192,24 @@ sysret_t sys_timer_gettime(timer_t timerid, struct itimerspec *curr_value)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Retrieves the overrun count for a periodic timer.
+ *
+ * This system call retrieves the number of times a periodic timer has "overrun." An overrun occurs
+ * when a timer expires before the previous expiration has been acknowledged or handled. For periodic
+ * timers, this indicates how many times the timer's expiration has been missed due to delayed processing
+ * or handling.
+ *
+ * @param[in]  timerid      The ID of the timer to query. This is the timer handle
+ *                          returned by `sys_timer_create`.
+ *
+ * @return sysret_t         Returns a status code indicating the result of the operation:
+ *                          - `0`: The overrun count was successfully retrieved.
+ *                         - Other error codes may indicate additional failures.
+ *
+ * @warning Ensure that the timer ID is valid before calling this function, as invalid timer IDs
+ *          will result in errors.
+ */
 sysret_t sys_timer_getoverrun(timer_t timerid)
 {
     int ret = 0;
@@ -1741,6 +3217,24 @@ sysret_t sys_timer_getoverrun(timer_t timerid)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Creates a new thread.
+ *
+ * This system call creates a new thread within the calling process. The newly created
+ * thread starts executing the function specified by the `arg` argument, which typically
+ * contains the necessary arguments or function pointer for the thread's execution.
+ *
+ * @param[in] arg     An array of arguments that will be passed to the function executed
+ *                    by the new thread. This can include function pointers, structures,
+ *                    or any necessary data the thread will need to execute its work.
+ *
+ * @return rt_thread_t    Returns a handle to the newly created thread. If the thread
+ *                        creation fails, `NULL` is returned.
+ *
+ * @warning Ensure that the system has sufficient resources to create a new thread.
+ *          Thread creation failures can occur if system limits are exceeded or resources
+ *          are unavailable.
+ */
 rt_thread_t sys_thread_create(void *arg[])
 {
     void *user_stack = 0;
@@ -1964,6 +3458,26 @@ fail:
     return (long)err;
 }
 
+/**
+ * @brief Creates a new process or thread (clone).
+ *
+ * This system call creates a new process or thread by duplicating the calling process.
+ * The new process/thread begins execution by calling the function specified in the
+ * `arg[]` array, which typically contains the necessary arguments or function pointer.
+ * It is used to implement process/thread creation in the system and is often a lower-level
+ * operation in process management.
+ *
+ * @param[in] arg   An array of arguments passed to the new process or thread. This could
+ *                  include function pointers, structures, or any necessary data the
+ *                  new process/thread will need to execute its work.
+ *
+ * @return long     Returns a status code or the process/thread ID of the newly created
+ *                  process/thread. On success, it may return a positive value (such as a
+ *                  thread ID). On failure, a negative value indicating the error is returned.
+ *
+ * @warning Be cautious when using this function as improper management of process/thread
+ *          creation can lead to resource exhaustion, deadlocks, or other synchronization issues.
+ */
 rt_weak long sys_clone(void *arg[])
 {
     return _sys_clone(arg);
@@ -2169,6 +3683,27 @@ fail:
 
 /* arm needs to wrap fork/clone call to preserved lr & caller saved regs */
 
+/**
+ * @brief Creates a child process by duplicating the calling process.
+ *
+ * This system call creates a new child process by duplicating the calling process. The
+ * new child process is a copy of the parent process, except for the returned value.
+ * The child process starts executing from the point of the fork, but the return value
+ * differs between the parent and child: the parent receives the process ID (PID) of the
+ * child, and the child receives a return value of 0.
+ *
+ * @return sysret_t    Returns a status code indicating the result of the operation:
+ *                      - A positive value (the child's PID) is returned to the parent.
+ *                      - A value of 0 is returned to the child process.
+ *                      - A negative value indicates an error (e.g., resource limits exceeded).
+ *
+ * @note This function is commonly used in operating systems to create new processes.
+ *
+ * @warning Be aware that improper management of child processes (such as failing to handle
+ *          process termination or excessive forking) can lead to resource exhaustion or
+ *          other system issues. Ensure proper process handling in the parent and child
+ *          processes to avoid leaks and inconsistencies.
+ */
 rt_weak sysret_t sys_fork(void)
 {
     return _sys_fork();
@@ -2187,6 +3722,32 @@ rt_weak sysret_t sys_vfork(void)
         lwp_new->member = tmp;\
     } while (0)
 
+/**
+ * @brief Executes a program in the current process.
+ *
+ * This system call replaces the current process image with a new program specified by the
+ * `path` argument. It loads the program located at the given `path` and passes the arguments
+ * (`argv`) and environment variables (`envp`) to it. This effectively replaces the calling
+ * process with a new one, and if successful, it never returns. If there is an error, the current
+ * process continues to execute, and an error code is returned.
+ *
+ * @param[in]  path   The path to the executable file to be executed. This should be an
+ *                    absolute or relative file path to the program.
+ * @param[in]  argv   An array of arguments to pass to the new program. The first element
+ *                    (`argv[0]`) should typically be the name of the program, and the array
+ *                    should be terminated with a `NULL` pointer.
+ * @param[in]  envp   An array of environment variables to pass to the new program. This is
+ *                    typically in the form of `key=value` strings, with the array terminated
+ *                    by a `NULL` pointer.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The program was successfully executed (this value is
+ *                      never returned since the process is replaced).
+ *                   - Other error codes may indicate issues with the program execution
+ *
+ * @note If `execve` is successful, it does not return to the calling function. The process
+ *       image is replaced by the new program.
+ */
 sysret_t sys_execve(const char *path, char *const argv[], char *const envp[])
 {
     rt_err_t error = -1;
@@ -2387,6 +3948,27 @@ quit:
 }
 #endif /* ARCH_MM_MMU */
 
+/**
+ * @brief Deletes a thread.
+ *
+ * This system call is used to delete an existing thread. The specified thread is terminated,
+ * and its resources are released. If the thread is currently running, it will be forcefully
+ * terminated. The thread identifier (`thread`) refers to the thread that is to be deleted.
+ *
+ * @param[in] thread   The identifier of the thread to be deleted.
+ *
+ * @return sysret_t    Returns a status code:
+ *                      - `SYSRET_OK`: The thread was successfully deleted.
+ *                     - Other error codes may indicate additional failures.
+ *
+ * @note This function should be used carefully, as forcefully terminating a thread may
+ *       lead to resource leaks or inconsistent state if the thread is performing critical
+ *       operations at the time of termination.
+ *
+ * @warning Ensure that the thread being deleted has completed its necessary operations
+ *          and that there are no outstanding resources or critical tasks before deleting
+ *          it. Otherwise, it might lead to undefined behavior or resource leaks.
+ */
 sysret_t sys_thread_delete(rt_thread_t thread)
 {
 #ifdef ARCH_MM_MMU
@@ -2412,11 +3994,47 @@ __exit:
 #endif
 }
 
+/**
+ * @brief Starts a previously created thread.
+ *
+ * This system call is used to start a thread that was created but has not yet started running.
+ * It initiates the thread's execution, allowing it to begin performing its assigned task.
+ * The `thread` parameter refers to the thread that is to be started.
+ *
+ * @param[in] thread   The identifier of the thread to be started.
+ *
+ * @return sysret_t    Returns a status code:
+ *                      - `0`: The thread was successfully started.
+ *                      - Other error codes may indicate additional failures.
+ *
+ * @warning Ensure that the thread has been correctly initialized and is in a valid state
+ *          before calling this function to avoid undefined behavior. Improper initialization
+ *          could lead to issues such as the thread not running as expected.
+ */
 sysret_t sys_thread_startup(rt_thread_t thread)
 {
     return rt_thread_startup(thread);
 }
 
+/**
+ * @brief Retrieves the identifier of the current thread.
+ *
+ * This system call returns the thread identifier of the currently executing thread. It allows
+ * a thread to obtain its own identifier, which can be useful for various thread management
+ * tasks such as self-identification, logging, or checking the thread's status.
+ *
+ * @return rt_thread_t  The identifier of the current thread.
+ *                      If no thread is currently executing, a null or invalid thread ID
+ *                      might be returned depending on the system's implementation.
+ *
+ * @note This function is typically used when a thread needs to identify itself, especially
+ *       in cases where thread management is performed dynamically or the thread identifier
+ *       is required for synchronization or debugging purposes.
+ *
+ * @warning Be aware that in environments where there is no concept of threads or if the
+ *          current context is not a thread (e.g., during interrupt handling or early system
+ *          initialization), the return value might be invalid.
+ */
 rt_thread_t sys_thread_self(void)
 {
     return rt_thread_self();
@@ -2424,6 +4042,26 @@ rt_thread_t sys_thread_self(void)
 
 /* sys channel */
 
+/**
+ * @brief Opens a communication channel.
+ *
+ * This system call is used to open a communication channel with a specified name and set of flags.
+ * The channel allows for inter-process or inter-thread communication, depending on the underlying system.
+ * The `name` parameter specifies the name of the channel, while the `flags` parameter allows
+ * configuration of the channel's behavior (e.g., read/write permissions, blocking or non-blocking mode).
+ *
+ * @param[in] name   The name of the communication channel to be opened.
+ * @param[in] flags  The flags to configure the behavior of the channel. These flags may
+ *                   define various properties such as access mode (e.g., read-only, write-only)
+ *                   or synchronization mode (e.g., blocking, non-blocking).
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The channel was successfully opened.
+ *                    - Other error codes may indicate issues with the channel opening process.
+ *
+ * @warning Ensure that the correct flags are passed to configure the channel as required,
+ *          as improper configuration might lead to access issues, data loss, or undefined behavior.
+ */
 sysret_t sys_channel_open(const char *name, int flags)
 {
     rt_size_t ret = 0;
@@ -2455,11 +4093,55 @@ sysret_t sys_channel_open(const char *name, int flags)
     return ret;
 }
 
+/**
+ * @brief Closes an open communication channel.
+ *
+ * This system call is used to close an already open communication channel specified by the file descriptor `fd`.
+ * After closing, the channel can no longer be used for communication, and any resources associated with
+ * the channel will be released. This function is necessary for proper resource management, ensuring that
+ * system resources (e.g., memory or file handles) are freed when no longer needed.
+ *
+ * @param[in] fd     The file descriptor of the communication channel to be closed.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `SYSRET_OK`: The channel was successfully closed.
+ *                    - Other error codes may indicate issues with the channel closing process.
+ *
+ * @note This function should be called after communication is finished and the channel is no longer
+ *       needed, to release any system resources associated with it.
+ *
+ * @warning Calling this function on an invalid or already closed file descriptor may lead to
+ *          undefined behavior or errors. Ensure that the file descriptor is valid and that the
+ *          channel is not already closed before attempting to close it.
+ */
 sysret_t sys_channel_close(int fd)
 {
     return lwp_channel_close(FDT_TYPE_LWP, fd);
 }
 
+/**
+ * @brief Sends a message through a communication channel.
+ *
+ * This system call is used to send a message through a specified communication channel identified
+ * by the file descriptor `fd`. The message to be sent is provided in the `data` parameter.
+ * It allows inter-process or inter-thread communication by transmitting the given message over
+ * the open channel.
+ *
+ * @param[in] fd     The file descriptor of the communication channel to send the message to.
+ * @param[in] data   The message data to be sent. This parameter is typically a structure
+ *                   containing the message content and metadata.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The message was successfully sent.
+ *                    - Other error codes may indicate issues with the message sending process.
+ *
+ * @note Ensure the channel is open and properly configured for sending messages before
+ *       calling this function. Additionally, confirm that the `data` structure is valid and
+ *       initialized with the appropriate content.
+ *
+ * @warning Failure to verify the channel's readiness or the validity of the data may lead
+ *          to errors, data loss, or undefined behavior.
+ */
 sysret_t sys_channel_send(int fd, rt_channel_msg_t data)
 {
     rt_size_t ret = 0;
@@ -2487,6 +4169,32 @@ sysret_t sys_channel_send(int fd, rt_channel_msg_t data)
     return ret;
 }
 
+/**
+ * @brief Sends a message through a communication channel and waits for a response with a timeout.
+ *
+ * This system call sends a message (`data`) through a specified communication channel identified by the file descriptor `fd`.
+ * It then waits for a response (`data_ret`) within the specified timeout period. This is a synchronous operation
+ * commonly used in request-response communication patterns between processes or threads.
+ *
+ * @param[in]  fd        The file descriptor of the communication channel to send the message to.
+ * @param[in]  data      The message data to be sent. This is typically a structure containing
+ *                       the message content and metadata.
+ * @param[out] data_ret  The buffer to store the response message received from the channel.
+ * @param[in]  time      The timeout period (in milliseconds) to wait for the response.
+ *                       If set to a negative value, the function will wait indefinitely.
+ *
+ * @return sysret_t      Returns a status code:
+ *                        - `0`: The message was successfully sent, and a response was received.
+ *                        - Other error codes may indicate issues with the communication process.
+ *
+ * @note This function combines sending and receiving operations into a single atomic action.
+ *       It is useful for scenarios requiring synchronous communication with a defined timeout
+ *       to handle cases where a response may not be immediately available.
+ *
+ * @warning Ensure that the channel is open and properly configured for bidirectional communication.
+ *          Verify that the `data` structure is valid and initialized, and the `data_ret` buffer is large
+ *          enough to store the expected response to avoid memory issues or data corruption.
+ */
 sysret_t sys_channel_send_recv_timeout(int fd, rt_channel_msg_t data, rt_channel_msg_t data_ret, rt_int32_t time)
 {
     rt_size_t ret = 0;
@@ -2521,6 +4229,29 @@ sysret_t sys_channel_send_recv_timeout(int fd, rt_channel_msg_t data, rt_channel
     return ret;
 }
 
+/**
+ * @brief Sends a reply message through a communication channel.
+ *
+ * This system call is used to send a reply (`data`) through a communication channel identified
+ * by the file descriptor `fd`. It is typically called in response to a received request
+ * within a request-response communication pattern. The reply is sent to the requesting entity
+ * through the same channel.
+ *
+ * @param[in] fd     The file descriptor of the communication channel to send the reply to.
+ * @param[in] data   The reply message to be sent. This is typically a structure containing
+ *                   the reply content and metadata.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The reply was successfully sent.
+ *                    - Other error codes may indicate issues with the reply sending process.
+ *
+ * @note This function is usually called in a server or responder context, where a request
+ *       is received, processed, and the result is sent back to the requester. Ensure that
+ *       the channel is open and configured to send replies before calling this function.
+ *
+ * @warning Ensure the `data` structure is valid and properly initialized before sending.
+ *          Sending invalid or corrupted data may lead to unexpected behavior or communication failures.
+ */
 sysret_t sys_channel_reply(int fd, rt_channel_msg_t data)
 {
     rt_size_t ret = 0;
@@ -2548,6 +4279,32 @@ sysret_t sys_channel_reply(int fd, rt_channel_msg_t data)
     return ret;
 }
 
+/**
+ * @brief Receives a message from a communication channel with a timeout.
+ *
+ * This system call attempts to receive a message from a specified communication channel identified
+ * by the file descriptor `fd`. The received message is stored in the `data` buffer. If no message
+ * is available within the specified timeout period, the function returns with a timeout status.
+ *
+ * @param[in]  fd     The file descriptor of the communication channel to receive the message from.
+ * @param[out] data   The buffer to store the received message. This parameter is typically a
+ *                    structure containing the message content and metadata.
+ * @param[in]  time   The timeout period (in milliseconds) to wait for a message.
+ *                    A negative value indicates that the function will wait indefinitely.
+ *
+ * @return sysret_t   Returns a status code:
+ *                     - `0`: A message was successfully received.
+ *                     - `-ETIMEDOUT`: The operation timed out before a message was received.
+ *                     - Other error codes may indicate issues with the message receiving process.
+ *
+ * @note This function is useful in scenarios where blocking indefinitely is not desirable,
+ *       allowing the caller to specify a timeout for receiving messages. It is commonly
+ *       used in event-driven or time-sensitive communication systems.
+ *
+ * @warning Ensure that the channel is open and configured for receiving messages before calling
+ *          this function. The `data` buffer must be valid and large enough to store the expected
+ *          message to avoid memory corruption or data loss.
+ */
 sysret_t sys_channel_recv_timeout(int fd, rt_channel_msg_t data, rt_int32_t time)
 {
     rt_size_t ret = 0;
@@ -2574,11 +4331,35 @@ static int critical_init(void)
 }
 INIT_DEVICE_EXPORT(critical_init);
 
+/**
+ * @brief Enters a critical section to prevent context switching or interrupts.
+ *
+ * @note Critical sections are typically used to protect shared resources or perform
+ *       non-interruptible operations. Ensure to exit the critical section as soon as
+ *       possible by calling `sys_exit_critical` to avoid system performance degradation
+ *       or deadlocks.
+ *
+ * @warning Failure to exit a critical section (e.g., due to an exception or missing
+ *          `sys_exit_critical` call) may lead to system instability or a complete halt.
+ */
 void sys_enter_critical(void)
 {
     rt_sem_take(&critical_lock, RT_WAITING_FOREVER);
 }
 
+/**
+ * @brief Exits a critical section and restores the system's previous state.
+ *
+ * @note Exiting the critical section as soon as the protected operation is completed
+ *       is essential to avoid performance degradation or system deadlocks. Ensure
+ *       that every call to `sys_enter_critical` is matched with a corresponding
+ *       `sys_exit_critical` call.
+ *
+ * @warning Calling this function without a prior `sys_enter_critical` may result
+ *          in undefined behavior or system instability. Use carefully in nested
+ *          critical sections and ensure proper tracking of critical section depth
+ *          if required.
+ */
 void sys_exit_critical(void)
 {
     rt_sem_release(&critical_lock);
@@ -2602,6 +4383,29 @@ static int sys_log_enable(int argc, char** argv)
 }
 MSH_CMD_EXPORT_ALIAS(sys_log_enable, sys_log, sys_log 1(enable)/0(disable));
 
+/**
+ * @brief Logs a message to the system logging mechanism.
+ *
+ * This system call writes a log message to the system log for diagnostic or informational purposes.
+ * The message is specified by the `log` parameter, and its size is given by the `size` parameter.
+ * The logging mechanism is typically used for tracking system events, debugging, or reporting errors.
+ *
+ * @param[in] log   A pointer to the message to be logged. The message should be a valid character
+ *                  array or string.
+ * @param[in] size  The size of the log message in bytes. This specifies the number of bytes to write
+ *                  from the `log` buffer.
+ *
+ * @return sysret_t Returns a status code:
+ *                   - `0`: The log message was successfully written.
+ *                   - Other error codes may indicate issues with the logging process.
+ *
+ * @note Ensure that the `log` pointer is valid and points to a properly initialized memory buffer.
+ *       Truncation may occur if the logging system has a size limitation. Logging should not be used
+ *       in performance-critical paths as it may introduce latency.
+ *
+ * @warning Passing a `NULL` pointer or an invalid `size` may lead to undefined behavior. Ensure the
+ *          logging system is properly initialized before invoking this function.
+ */
 sysret_t sys_log(const char* log, int size)
 {
     char *klog = RT_NULL;
@@ -2634,6 +4438,29 @@ sysret_t sys_log(const char* log, int size)
     return 0;
 }
 
+/**
+ * @brief Retrieves information about a file or directory.
+ *
+ * This system call obtains metadata about the specified file or directory and stores it in
+ * the `buf` structure. The metadata includes attributes such as file size, permissions,
+ * ownership, and timestamps.
+ *
+ * @param[in]  file  A pointer to the path of the file or directory to be queried.
+ *                   The path should be a null-terminated string.
+ * @param[out] buf   A pointer to a `struct stat` structure where the file's metadata
+ *                   will be stored. This structure must be allocated by the caller.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The operation completed successfully, and the metadata
+ *                      has been written to `buf`.
+ *                    - Other error codes may indicate issues with the file path.
+ *
+ * @note The `file` path must be valid and accessible by the calling process. Ensure that
+ *       the `buf` pointer points to a properly allocated memory region.
+ *
+ * @warning Passing a `NULL` pointer for `file` or `buf` may result in undefined behavior.
+ *          Check all inputs before invoking this function to avoid potential issues.
+ */
 sysret_t sys_stat(const char *file, struct stat *buf)
 {
     int ret = 0;
@@ -2678,6 +4505,31 @@ sysret_t sys_stat(const char *file, struct stat *buf)
     return ret;
 }
 
+/**
+ * @brief Retrieves metadata about a file or symbolic link.
+ *
+ * This system call obtains metadata for the specified file or symbolic link and stores
+ * it in the `buf` structure. Unlike `sys_stat`, if the specified path refers to a
+ * symbolic link, this function retrieves information about the link itself, not the
+ * target it points to.
+ *
+ * @param[in]  file  A pointer to the path of the file or symbolic link to be queried.
+ *                   The path must be a null-terminated string.
+ * @param[out] buf   A pointer to a `struct stat` structure where the metadata will be
+ *                   stored. This structure must be allocated by the caller.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The operation completed successfully, and the metadata
+ *                      has been written to `buf`.
+ *                   - Other error codes may indicate issues with the file path.
+ *
+ * @note This function is particularly useful for handling symbolic links when you want
+ *       to get information about the link itself rather than the target file or directory.
+ *       The `file` path must be valid and accessible by the calling process.
+ *
+ * @warning Passing a `NULL` pointer for `file` or `buf` may result in undefined behavior.
+ *          Always check inputs for validity before invoking this function.
+ */
 sysret_t sys_lstat(const char *file, struct stat *buf)
 {
     int ret = 0;
@@ -2741,26 +4593,153 @@ void sys_hw_interrupt_enable(uint32_t level)
 }
 
 #ifdef ARCH_MM_MMU
+/**
+ * @brief Allocates or retrieves a shared memory segment.
+ *
+ * This system call allocates a new shared memory segment or retrieves an existing one
+ * based on the specified `key`. Shared memory allows processes to communicate by
+ * sharing a region of memory.
+ *
+ * @param[in] key     A unique identifier for the shared memory segment. If `key` matches
+ *                    an existing segment, it will be retrieved. If `create` is set and the
+ *                    segment does not exist, a new one will be created.
+ * @param[in] size    The size (in bytes) of the shared memory segment. If creating a new
+ *                    segment, this specifies its size. If retrieving an existing segment,
+ *                    `size` is ignored.
+ * @param[in] create  A flag indicating whether to create the segment if it does not exist:
+ *                    - `1`: Create the shared memory segment if it does not exist.
+ *                    - `0`: Only retrieve an existing segment.
+ *
+ * @return sysret_t   Returns a status code:
+ *                    - `0`: The shared memory segment was successfully created or
+ *                      retrieved.
+ *                    - Other error codes may indicate issues with the shared memory
+ *
+ * @note Shared memory segments identified by the same `key` are accessible across
+ *       processes. Ensure proper synchronization mechanisms (e.g., semaphores) are in
+ *       place to manage access to the shared memory.
+ *
+ * @warning Using a `NULL` or invalid `key` may result in undefined behavior. When creating
+ *          a new segment, ensure that `size` is non-zero and meaningful.
+ */
 sysret_t sys_shmget(size_t key, size_t size, int create)
 {
     return lwp_shmget(key, size, create);
 }
 
+/**
+ * @brief Removes a shared memory segment.
+ *
+ * This system call removes the specified shared memory segment identified by its `id`.
+ * Once removed, the segment will no longer be accessible, and any memory associated
+ * with it will be freed. It is typically used to clean up shared memory resources
+ * when they are no longer needed.
+ *
+ * @param[in] id  The identifier of the shared memory segment to be removed. This identifier
+ *                was obtained when the segment was created or retrieved using `sys_shmget`.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The shared memory segment was successfully removed.
+ *                    - Other error codes may indicate issues with the shared memory removal.
+ *
+ * @note This function should be called only when all processes that were using the shared
+ *       memory segment have finished accessing it. Removing the segment while it is in use
+ *       by another process may result in undefined behavior or memory corruption.
+ *
+ * @warning Ensure that the shared memory segment is no longer needed by any process before
+ *          calling this function to avoid premature removal and potential data loss.
+ */
 sysret_t sys_shmrm(int id)
 {
     return lwp_shmrm(id);
 }
 
+/**
+ * @brief Attaches a shared memory segment to the calling process's address space.
+ *
+ * This system call maps a shared memory segment identified by `id` into the calling
+ * process's address space. The segment can then be accessed using the returned virtual
+ * address. If the segment was previously detached or created, it will be made available
+ * for reading and writing.
+ *
+ * @param[in] id         The identifier of the shared memory segment to be attached.
+ *                       This identifier was obtained when the segment was created
+ *                       or retrieved using `sys_shmget`.
+ * @param[in] shm_vaddr  A pointer to the desired virtual address where the shared
+ *                       memory segment should be mapped. If `NULL`, the system will
+ *                       choose an appropriate address.
+ *
+ * @return void*        Returns the virtual address where the shared memory segment
+ *                      is mapped. On success, this will be the address in the
+ *                      calling process's address space. If the attachment fails,
+ *                      `NULL` is returned.
+ *
+ * @note Once the shared memory segment is attached, it can be accessed like any
+ *       regular memory, but it should be used with caution, especially in multi-process
+ *       environments. Ensure that proper synchronization mechanisms (e.g., semaphores)
+ *       are used to manage concurrent access.
+ *
+ * @warning Ensure that the shared memory segment is properly allocated and not in use
+ *          by other processes before attaching it. Passing invalid `id` or an inaccessible
+ *          segment may result in undefined behavior.
+ */
 void* sys_shmat(int id, void* shm_vaddr)
 {
     return lwp_shmat(id, shm_vaddr);
 }
 
+/**
+ * @brief Detaches a shared memory segment from the calling process's address space.
+ *
+ * This system call detaches the shared memory segment previously attached to the calling
+ * process's address space using `sys_shmat`. After calling this function, the shared
+ * memory will no longer be accessible via the returned address.
+ *
+ * @param[in] shm_vaddr  A pointer to the virtual address where the shared memory
+ *                       segment was previously mapped. This address was returned
+ *                       by the `sys_shmat` function.
+ *
+ * @return sysret_t      Returns a status code:
+ *                       - `0`: The shared memory segment was successfully detached.
+ *                       - Other error codes may indicate issues with the detachment process.
+ *
+ * @note It is important to ensure that no processes are using the shared memory segment
+ *       before detaching it. Detaching the segment while it is still being accessed
+ *       may lead to undefined behavior.
+ *
+ * @warning Ensure that `shm_vaddr` corresponds to a valid attached address returned
+ *          by `sys_shmat`. Passing an incorrect or uninitialized address may result
+ *          in undefined behavior.
+ */
 sysret_t sys_shmdt(void* shm_vaddr)
 {
     return lwp_shmdt(shm_vaddr);
 }
 #elif defined RT_LWP_USING_SHM
+
+/**
+ * @brief Allocates a new shared memory segment.
+ *
+ * This system call allocates a new shared memory segment of the specified size and
+ * returns a pointer to the allocated memory. The allocated segment can be used for
+ * inter-process communication or shared memory access. The segment is typically
+ * managed by the system, and it can be accessed by other processes with appropriate
+ * synchronization.
+ *
+ * @param[in] size  The size (in bytes) of the shared memory segment to be allocated.
+ *
+ * @return void*    Returns a pointer to the allocated shared memory segment.
+ *                  If the allocation fails, `RT_NULL` is returned.
+ *
+ * @note The allocated shared memory segment can be used like regular memory,
+ *       but it should be accessed with proper synchronization mechanisms (e.g.,
+ *       semaphores or mutexes) to avoid race conditions or data corruption in
+ *       multi-process environments.
+ *
+ * @warning Ensure that the `size` parameter is a valid, non-zero value, and that
+ *          there is enough system memory to allocate the requested size.
+ *          Failure to do so may result in errors or resource exhaustion.
+ */
 void *sys_shm_alloc(int size)
 {
     if (size < 0)
@@ -2770,6 +4749,30 @@ void *sys_shm_alloc(int size)
     return lwp_shm_alloc((rt_size_t)size);
 }
 
+/**
+ * @brief Retains an existing shared memory segment.
+ *
+ * This system call retains an existing shared memory segment that was previously
+ * allocated or attached, ensuring it remains available for further use. It is
+ * typically used to increment the reference count or to ensure the segment is
+ * not removed or deallocated while it is still being used.
+ *
+ * @param[in] mem  A pointer to the shared memory segment to retain. This should be
+ *                 the address previously returned by a memory allocation or
+ *                 attachment function such as `sys_shmat` or `sys_shm_alloc`.
+ *
+ * @return void*   Returns the original pointer `mem` if the retention is successful.
+ *                  If the operation fails, `NULL` is returned.
+ *
+ * @note This function does not affect the actual content of the shared memory segment,
+ *       but ensures the segment is not removed or deallocated while still in use.
+ *       It is generally used in conjunction with `sys_shmdt` or `sys_shmrm` to ensure
+ *       proper resource management.
+ *
+ * @warning Ensure that the provided pointer `mem` corresponds to a valid shared
+ *          memory segment that is currently allocated or attached. Passing an
+ *          invalid or uninitialized pointer may result in undefined behavior.
+ */
 void *sys_shm_retain(void *mem)
 {
     if (!lwp_user_accessable(mem, sizeof (void *)))
@@ -2779,6 +4782,29 @@ void *sys_shm_retain(void *mem)
     return lwp_shm_retain(mem);
 }
 
+/**
+ * @brief Frees a previously allocated shared memory segment.
+ *
+ * This system call frees a shared memory segment that was previously allocated or
+ * retained using functions like `sys_shm_alloc` or `sys_shm_retain`. It ensures
+ * that the shared memory is properly deallocated, making it available for future
+ * allocations or for removal from the system.
+ *
+ * @param[in] mem  A pointer to the shared memory segment to be freed. This should be
+ *                 the address returned by a memory allocation or retention function.
+ *
+ * @return sysret_t  Returns a status code:
+ *                   - `0`: The shared memory segment was successfully freed.
+ *                   - Other error codes may indicate issues with the memory deallocation.
+ *
+ * @note After calling this function, the memory will be deallocated, and any subsequent
+ *       access to the freed memory will result in undefined behavior. Ensure that no
+ *       processes are using the shared memory before calling this function.
+ *
+ * @warning Ensure that `mem` corresponds to a valid shared memory segment that was
+ *          previously allocated or retained. Passing an invalid or already freed
+ *          pointer may result in undefined behavior.
+ */
 sysret_t sys_shm_free(void *mem)
 {
     if (!lwp_user_accessable(mem, sizeof (void *)))
@@ -2791,41 +4817,236 @@ sysret_t sys_shm_free(void *mem)
 #endif
 
 /* device interfaces */
+
+/**
+ * @brief Initializes a device.
+ *
+ * This system call initializes the specified device, preparing it for use. Device initialization
+ * typically involves setting up necessary hardware configurations, registering device drivers,
+ * and ensuring that the device is in a ready state for further operations. This function should
+ * be called before interacting with the device.
+ *
+ * @param[in] dev  A pointer to the device structure that represents the device to be initialized.
+ *                 This structure contains device-specific configuration and state information.
+ *
+ * @return sysret_t  Returns a status code:
+ *                   - `0`: The device was successfully initialized.
+ *                   - Other error codes may indicate issues with the device initialization process.
+ *
+ * @note This function is typically called once during system startup or when a device is
+ *       first accessed. It ensures that all necessary setup steps are completed before
+ *       the device can be used.
+ *
+ * @warning Ensure that the device passed to this function is valid and properly configured
+ *          before initialization. Initializing an invalid or improperly configured device
+ *          may result in unpredictable behavior.
+ */
 sysret_t sys_device_init(rt_device_t dev)
 {
     return rt_device_init(dev);
 }
 
+/**
+ * @brief Registers a device with the system.
+ *
+ * This system call registers a device with the system, making it available for interaction
+ * by the operating system or other components. Registration typically involves associating
+ * the device with a name and setting up the necessary flags for the device's behavior.
+ *
+ * @param[in] dev     A pointer to the device structure that represents the device to be registered.
+ *                    This structure contains the device's configuration, capabilities, and state.
+ * @param[in] name    A string representing the name by which the device will be identified in the system.
+ *                    This name is used for device lookup and reference.
+ * @param[in] flags   A set of flags that configure the behavior of the device, such as enabling
+ *                    or disabling certain features, or specifying the device's mode of operation.
+ *
+ * @return sysret_t   Returns a status code:
+ *                    - `0`: The device was successfully registered.
+ *                    - Other error codes may indicate issues with the device registration process.
+ *
+ * @note This function should be called after the device has been initialized (via `sys_device_init`)
+ *       and before the device is used by the system or other components.
+ *
+ * @warning Ensure that the `name` provided is unique and not already in use by another device in the system.
+ *          Passing invalid `dev` or `flags` may result in unexpected behavior or failure of device registration.
+ */
 sysret_t sys_device_register(rt_device_t dev, const char *name, rt_uint16_t flags)
 {
     return rt_device_register(dev, name, flags);
 }
 
+/**
+ * @brief Controls a device by sending a command.
+ *
+ * This system call sends a control command to the specified device, allowing the system or other
+ * components to modify the device's behavior or state. The command is specified by the `cmd`
+ * parameter, and the arguments for the command are passed via the `arg` parameter.
+ *
+ * @param[in] dev   A pointer to the device structure representing the device to be controlled.
+ *                  The device must have been previously registered and initialized.
+ * @param[in] cmd   The control command to be sent to the device. The meaning and behavior of the
+ *                  command are device-specific and depend on the device type.
+ * @param[in] arg   A pointer to the arguments required by the command. The type and content of
+ *                  the arguments are determined by the command. Some commands may not require
+ *                  arguments, in which case `arg` can be `NULL`.
+ *
+ * @return sysret_t Returns a status code:
+ *                   - `0`: The command was successfully executed on the device.
+ *                   - Other error codes may indicate issues with the command execution or device control.
+ *
+ * @note The set of available commands (`cmd`) and the expected argument types (`arg`) are specific
+ *       to each device. Refer to the device documentation for the supported commands and argument
+ *       formats.
+ *
+ * @warning Ensure that the `dev` pointer is valid and points to a correctly initialized device.
+ *          Providing an invalid device or incorrect command may result in undefined behavior.
+ */
 sysret_t sys_device_control(rt_device_t dev, int cmd, void *arg)
 {
     return rt_device_control(dev, cmd, arg);
 }
 
+/**
+ * @brief Finds a device by its name.
+ *
+ * This system call searches for a device that has been registered with the system using the
+ * specified name. If the device exists, a pointer to the device structure is returned,
+ * allowing further interaction with the device. If no device with the specified name is found,
+ * a `NULL` pointer is returned.
+ *
+ * @param[in] name  The name of the device to search for. This name must match the name used
+ *                  during device registration (e.g., via `sys_device_register`).
+ *
+ * @return rt_device_t  Returns a pointer to the device structure if the device is found.
+ *                      Returns `NULL` if no device with the specified name exists.
+ *
+ * @note The device must have been previously registered with the system using `sys_device_register`.
+ *
+ * @warning Ensure that the provided `name` is a valid string and corresponds to a registered device.
+ *          Passing an invalid or non-registered name will result in `NULL` being returned.
+ */
 rt_device_t sys_device_find(const char* name)
 {
     return rt_device_find(name);
 }
 
+/**
+ * @brief Opens a device for use.
+ *
+ * This system call opens the specified device, making it ready for interaction with the system
+ * or other components. The device must have been previously registered and initialized.
+ * The `oflag` parameter specifies the open mode, which may determine how the device is accessed
+ * (e.g., read, write, or exclusive access).
+ *
+ * @param[in] dev    A pointer to the device structure representing the device to be opened.
+ *                   The device must be registered and initialized before being opened.
+ * @param[in] oflag  The open flags that determine the mode of access to the device. These flags
+ *                   may specify read, write, or other modes of operation, depending on the device's capabilities.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The device was successfully opened.
+ *                    - Other error codes may indicate issues with the device opening process.
+ *
+ * @note The open flags (`oflag`) should be set according to the device's capabilities. For example,
+ *       some devices may support read or write operations, while others may only support one of them.
+ *       Check the device documentation for supported flags.
+ *
+ * @warning Ensure that the device pointer (`dev`) is valid and that the device has been initialized
+ *          properly. Incorrect flags or attempting to open a device that is already in use may result
+ *          in errors or undefined behavior.
+ */
 sysret_t sys_device_open(rt_device_t dev, rt_uint16_t oflag)
 {
     return rt_device_open(dev, oflag);
 }
 
+/**
+ * @brief Closes an open device.
+ *
+ * This system call closes an open device, releasing any resources or locks associated with it
+ * and making it unavailable for further interaction until it is opened again. The device must
+ * have been previously opened using `sys_device_open`. After calling this function, any further
+ * attempts to interact with the device will result in an error unless the device is opened again.
+ *
+ * @param[in] dev  A pointer to the device structure representing the device to be closed.
+ *                 The device must be open before it can be closed.
+ *
+ * @return sysret_t  Returns a status code:
+ *                    - `0`: The device was successfully closed.
+ *                    - Other error codes may indicate issues with the device closing process.
+ *
+ * @note This function should be called when the device is no longer needed or before shutting
+ *       down the system to release device resources properly.
+ *
+ * @warning Ensure that the device has been opened before calling this function. Calling this function
+ *          on an uninitialized or already closed device may result in undefined behavior or errors.
+ */
 sysret_t sys_device_close(rt_device_t dev)
 {
     return rt_device_close(dev);
 }
 
+/**
+ * @brief Reads data from an open device.
+ *
+ * This system call reads data from the specified device, starting at the given position and
+ * storing the data in the provided buffer. The device must be open before this function can be called.
+ * The amount of data to read is determined by the `size` parameter.
+ *
+ * @param[in]  dev     A pointer to the device structure representing the device to read from.
+ *                     The device must be open and ready for reading.
+ * @param[in]  pos     The position within the device from which to begin reading. For devices that
+ *                     support seeking, this value is used to specify the starting point.
+ * @param[out] buffer  A pointer to the buffer where the read data will be stored. This buffer should
+ *                     be large enough to hold the specified amount of data.
+ * @param[in]  size    The number of bytes to read from the device. This value determines how much
+ *                     data is read into the buffer.
+ *
+ * @return rt_ssize_t  Returns the number of bytes actually read from the device:
+ *                      - On success: The number of bytes read, which may be less than `size` if
+ *                        the end of the device is reached or other factors limit the read.
+ *                      - On failure: A negative error code.
+ *
+ * @note The device must be open and in a readable state before calling this function.
+ *       The `pos` parameter allows seeking within the device if it supports such operations.
+ *
+ * @warning Ensure that the buffer provided is large enough to hold the data being read.
+ *          Providing an insufficient buffer may result in undefined behavior.
+ */
 rt_ssize_t sys_device_read(rt_device_t dev, rt_off_t pos, void *buffer, rt_size_t size)
 {
     return rt_device_read(dev, pos, buffer, size);
 }
 
+/**
+ * @brief Writes data to an open device.
+ *
+ * This system call writes data to the specified device, starting at the given position and using
+ * the provided buffer. The device must be open and ready for writing. The amount of data to write
+ * is determined by the `size` parameter.
+ *
+ * @param[in]  dev     A pointer to the device structure representing the device to write to.
+ *                     The device must be open and ready for writing.
+ * @param[in]  pos     The position within the device where the writing should start. For devices
+ *                     that support seeking, this value specifies the location to begin writing.
+ * @param[in]  buffer  A pointer to the buffer containing the data to be written to the device.
+ *                     This buffer should contain the data to be written and should be large enough
+ *                     to accommodate the specified size.
+ * @param[in]  size    The number of bytes to write to the device. This value indicates how much
+ *                     data should be written from the buffer to the device.
+ *
+ * @return rt_ssize_t  Returns the number of bytes actually written to the device:
+ *                      - On success: The number of bytes written, which may be less than `size`
+ *                        if there is an issue with the device or the data was truncated.
+ *                      - On failure: A negative error code.
+ *
+ * @note The device must be open and in a writable state before calling this function.
+ *       The `pos` parameter allows seeking within the device if it supports such operations.
+ *
+ * @warning Ensure that the buffer provided contains valid data and that it is large enough
+ *          to fit the amount of data specified by `size`. Providing an insufficient buffer
+ *          or invalid data may lead to undefined behavior.
+ */
 rt_ssize_t sys_device_write(rt_device_t dev, rt_off_t pos, const void *buffer, rt_size_t size)
 {
     return rt_device_write(dev, pos, buffer, size);
@@ -2833,6 +5054,41 @@ rt_ssize_t sys_device_write(rt_device_t dev, rt_off_t pos, const void *buffer, r
 
 #ifdef RT_USING_SAL
 /* network interfaces */
+
+/**
+ * @brief Accepts a connection on a socket.
+ *
+ * This system call is used to accept a pending connection request on a socket. It extracts the
+ * first connection request from the incoming queue, creates a new socket for the connection,
+ * and stores the address information of the remote peer in the provided address structure.
+ * The original socket must be a listening socket that has been previously bound and set to listen
+ * for incoming connections.
+ *
+ * @param[in]  socket    The listening socket file descriptor that is waiting for incoming connections.
+ *                       This socket must be in a listening state, created using `sys_socket` and
+ *                       bound to an address using `sys_bind`.
+ * @param[out] addr      A pointer to a `musl_sockaddr` structure where the address of the connecting
+ *                       client will be stored. The structure is populated with information such as
+ *                       the client's IP address and port number.
+ * @param[in,out] addrlen A pointer to a socklen_t variable that specifies the size of the `addr`
+ *                        structure on input. On output, it will contain the actual size of the
+ *                        address returned in `addr`.
+ *
+ * @return sysret_t      Returns a socket descriptor for the new connection on success, or
+ *                        `SYSRET_ERROR` on failure:
+ *                        - On success: A new socket descriptor that can be used for further
+ *                          communication with the connected peer.
+ *                        - On failure: A negative error code indicating the reason for the failure.
+ *
+ * @note The socket passed as `socket` must be in a listening state and ready to accept incoming
+ *       connections. The `addr` structure is populated with the client's address details, which can
+ *       be used for further operations, such as identifying the client.
+ *
+ * @warning Ensure that the `addr` structure is sufficiently large to hold the address information.
+ *          The `addrlen` parameter must be set to the size of the `musl_sockaddr` structure before
+ *          calling this function. Calling the function with an incorrectly sized `addrlen` may lead
+ *          to buffer overflows or undefined behavior.
+ */
 sysret_t sys_accept(int socket, struct musl_sockaddr *addr, socklen_t *addrlen)
 {
     int ret = -1;
@@ -2877,6 +5133,32 @@ sysret_t sys_accept(int socket, struct musl_sockaddr *addr, socklen_t *addrlen)
     return ret;
 }
 
+/**
+ * @brief Binds a socket to a local address.
+ *
+ * This system call binds a socket to a specific local address and port. The socket must be created
+ * using `sys_socket` before it can be bound. The `bind` operation allows the application to associate
+ * a socket with a specific address, such as an IP address and port number, which can then be used
+ * for sending or receiving data.
+ *
+ * @param[in]  socket  The socket descriptor to which the address will be bound. This socket must
+ *                     be created using `sys_socket` and should not already be bound to another address.
+ * @param[in]  name    A pointer to a `musl_sockaddr` structure that contains the address to which
+ *                     the socket will be bound. This can represent an IP address and port number.
+ * @param[in]  namelen The size of the `musl_sockaddr` structure in bytes. This value should be set
+ *                     to the actual size of the `name` structure before calling this function.
+ *
+ * @return sysret_t    Returns `0` on success, or a negative error code on failure.
+ *
+ * @note The `socket` must be created before calling this function, and the address provided in `name`
+ *       should be a valid local address for the socket. This operation is typically used for server-side
+ *       sockets that listen for incoming connections or for any socket that needs to specify its local
+ *       address before communication.
+ *
+ * @warning If the specified address is already in use by another socket or if the socket type is incompatible
+ *          with the address, the function will return an error. Ensure that the address is not in use and is
+ *          valid for the socket type.
+ */
 sysret_t sys_bind(int socket, const struct musl_sockaddr *name, socklen_t namelen)
 {
     rt_err_t ret = 0;
@@ -2911,11 +5193,63 @@ sysret_t sys_bind(int socket, const struct musl_sockaddr *name, socklen_t namele
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Shuts down part of a full-duplex connection.
+ *
+ * This system call disables further send or receive operations on a socket. The `how` parameter
+ * specifies which part of the connection should be shut down. This operation is typically used
+ * when the application no longer needs to send or receive data, but wants to keep the connection open
+ * for other purposes (e.g., receiving shutdown acknowledgment).
+ *
+ * @param[in]  socket  The socket descriptor to be shut down. This socket must be an open socket that
+ *                     has been created using `sys_socket`.
+ * @param[in]  how     The shutdown behavior:
+ *                     - `SHUT_RD`: Disables further receives on the socket. The application can no longer
+ *                       receive data from this socket.
+ *                     - `SHUT_WR`: Disables further sends on the socket. The application can no longer
+ *                       send data through this socket.
+ *                     - `SHUT_RDWR`: Disables both sends and receives on the socket. The socket is
+ *                       fully shut down for communication.
+ *
+ * @return sysret_t    Returns `0` on success, or a negative error code (e.g., `SYSRET_ERROR`) on failure.
+ *
+ * @note The `socket` should be open and in a connected state when calling this function. The `how`
+ *       parameter determines which part of the connection is to be shut down, allowing for finer control
+ *       over communication termination.
+ *
+ * @warning Once a socket is shut down with `SHUT_RD`, no further data can be received on it. Similarly,
+ *          after `SHUT_WR`, no more data can be sent. Calling `sys_shutdown` with incompatible `how` values
+ *          or on an invalid socket may result in errors.
+ */
 sysret_t sys_shutdown(int socket, int how)
 {
     return shutdown(socket, how);
 }
 
+/**
+ * @brief Retrieves the address of the peer connected to a socket.
+ *
+ * This system call retrieves the address of the peer (remote endpoint) that is connected to the specified
+ * socket. The socket must be connected (i.e., for stream-oriented protocols such as TCP). The address
+ * of the peer is stored in the `name` structure, and the size of the structure is updated in `namelen`.
+ *
+ * @param[in]  socket    The socket descriptor of the connected socket. This socket must be in a connected
+ *                       state (e.g., after a successful `sys_connect` or `sys_accept` call).
+ * @param[out] name      A pointer to a `musl_sockaddr` structure where the address of the peer will be
+ *                       stored. This structure will be populated with the peer's IP address and port number.
+ * @param[in,out] namelen A pointer to a `socklen_t` variable that specifies the size of the `name` structure
+ *                        on input. On output, it will contain the actual size of the address returned in `name`.
+ *
+ * @return sysret_t      Returns `SYSRET_OK` on success, or a negative error code on failure.
+ *
+ * @note The `socket` must be in a connected state when calling this function. The `name` structure will
+ *       contain the peer's address information, which can be used for logging, debugging, or further
+ *       communication.
+ *
+ * @warning Ensure that the `name` structure is sufficiently large to hold the peer's address information.
+ *          The `namelen` parameter must be set to the size of the `name` structure before calling this function.
+ *          Failing to provide a correctly sized `namelen` could result in buffer overflows or undefined behavior.
+ */
 sysret_t sys_getpeername(int socket, struct musl_sockaddr *name, socklen_t *namelen)
 {
     int ret = -1;
@@ -2960,6 +5294,30 @@ sysret_t sys_getpeername(int socket, struct musl_sockaddr *name, socklen_t *name
     return ret;
 }
 
+/**
+ * @brief Retrieves the local address of the socket.
+ *
+ * This system call retrieves the local address (local endpoint) that is bound to the specified socket.
+ * The socket must be created and, if necessary, bound to a local address using `sys_bind`. The address
+ * of the local endpoint is stored in the `name` structure, and the size of the structure is updated in `namelen`.
+ *
+ * @param[in]  socket    The socket descriptor of the socket. This socket must be created and, if required,
+ *                       bound to a local address.
+ * @param[out] name      A pointer to a `musl_sockaddr` structure where the local address of the socket will
+ *                       be stored. This structure will be populated with the local IP address and port number.
+ * @param[in,out] namelen A pointer to a `socklen_t` variable that specifies the size of the `name` structure
+ *                        on input. On output, it will contain the actual size of the address returned in `name`.
+ *
+ * @return sysret_t      Returns `0` on success, or a negative error code on failure.
+ *
+ * @note The `socket` must be created and, if needed, bound to a local address using `sys_bind`.
+ *       The `name` structure will contain the local address of the socket, which can be used for logging,
+ *       debugging, or further communication.
+ *
+ * @warning Ensure that the `name` structure is sufficiently large to hold the local address information.
+ *          The `namelen` parameter must be set to the size of the `name` structure before calling this function.
+ *          Failing to provide a correctly sized `namelen` could result in buffer overflows or undefined behavior.
+ */
 sysret_t sys_getsockname(int socket, struct musl_sockaddr *name, socklen_t *namelen)
 {
     int ret = -1;
@@ -3002,6 +5360,35 @@ sysret_t sys_getsockname(int socket, struct musl_sockaddr *name, socklen_t *name
     return ret;
 }
 
+/**
+ * @brief Retrieves the value of a socket option.
+ *
+ * This system call retrieves the current value of a socket option for the specified socket. The socket
+ * options allow fine-grained control over various aspects of socket behavior, such as timeouts, buffering,
+ * and connection settings. The option value is stored in the `optval` buffer, and the size of the buffer
+ * is specified by the `optlen` parameter.
+ *
+ * @param[in]  socket    The socket descriptor for which the option value is being retrieved. The socket
+ *                       must be valid and open.
+ * @param[in]  level     The level at which the option is defined. Typically, this is `SOL_SOCKET` for general
+ *                       socket options, or a protocol-specific level (e.g., `IPPROTO_TCP` for TCP options).
+ * @param[in]  optname   The option name. This specifies which socket option to retrieve (e.g., `SO_RCVBUF`
+ *                       for receive buffer size or `SO_RCVBUF` for send buffer size).
+ * @param[out] optval    A pointer to a buffer where the option value will be stored. The buffer's type depends
+ *                       on the option being retrieved.
+ * @param[in,out] optlen A pointer to a `socklen_t` variable that specifies the size of the `optval` buffer on
+ *                       input. On output, it will contain the actual size of the option value retrieved.
+ *
+ * @return sysret_t      Returns `0` on success, or a negative error code on failure.
+ *
+ * @note The `socket` must be valid and open when calling this function. The `level` and `optname` parameters
+ *       define the specific option to be retrieved. The `optval` buffer will contain the option value after
+ *       the function call, and `optlen` will be updated to reflect the size of the retrieved value.
+ *
+ * @warning Ensure that the `optval` buffer is large enough to hold the value for the specified option.
+ *          The `optlen` parameter must be set to the correct size of the buffer before calling this function.
+ *          Failing to provide a correctly sized buffer could result in undefined behavior or buffer overflows.
+ */
 sysret_t sys_getsockopt(int socket, int level, int optname, void *optval, socklen_t *optlen)
 {
     int ret = 0;
@@ -3042,6 +5429,32 @@ sysret_t sys_getsockopt(int socket, int level, int optname, void *optval, sockle
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Sets the value of a socket option.
+ *
+ * This system call sets a socket option for the specified socket. Socket options control various aspects
+ * of socket behavior, such as timeouts, buffer sizes, or connection parameters. The option value is
+ * provided in the `optval` buffer, and its length is specified by the `optlen` parameter.
+ *
+ * @param[in]  socket    The socket descriptor for which the option is being set. The socket must be valid and open.
+ * @param[in]  level     The level at which the option is defined. This can be `SOL_SOCKET` for general socket options,
+ *                       or a protocol-specific level (e.g., `IPPROTO_TCP` for TCP options).
+ * @param[in]  optname   The option name. This specifies which socket option to set (e.g., `SO_RCVBUF` for receive buffer size).
+ * @param[in]  optval    A pointer to the buffer that contains the option value to set. The format of this buffer depends
+ *                       on the option being set.
+ * @param[in]  optlen    The size of the `optval` buffer. This specifies the length of the data to be used when setting
+ *                       the option value.
+ *
+ * @return sysret_t      Returns `0` on success, or a negative error code on failure:
+ *
+ * @note The `socket` must be valid and open. The `level` and `optname` parameters define the specific option to be set,
+ *       and the `optval` buffer should contain the appropriate value for that option. The `optlen` parameter must
+ *       match the size of the `optval` buffer.
+ *
+ * @warning Ensure that the `optval` buffer contains valid data for the specified option. The `optlen` parameter must be
+ *          set to the correct size of the `optval` buffer before calling this function. Failing to provide a correctly
+ *          sized buffer could result in undefined behavior or errors.
+ */
 sysret_t sys_setsockopt(int socket, int level, int optname, const void *optval, socklen_t optlen)
 {
     int ret;
@@ -3070,6 +5483,28 @@ sysret_t sys_setsockopt(int socket, int level, int optname, const void *optval,
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Establishes a connection to a remote socket.
+ *
+ * This system call attempts to establish a connection to a remote socket specified by the `name` parameter.
+ * It is typically used for client-side socket operations to connect to a server. The connection is established
+ * by using the specified socket descriptor and the address of the remote server.
+ *
+ * @param[in]  socket   The socket descriptor for the connection attempt. The socket must be valid and in a
+ *                      `SOCK_STREAM` or `SOCK_DGRAM` state, depending on the protocol.
+ * @param[in]  name     A pointer to a `sockaddr` structure containing the address of the remote host. This address
+ *                      must include the correct IP address and port number for the connection.
+ * @param[in]  namelen  The size of the `sockaddr` structure pointed to by `name`. This should match the size
+ *                      of the address structure (e.g., `sizeof(struct sockaddr_in)` for IPv4).
+ *
+ * @return sysret_t     Returns `0` on success, or a negative error code on failure:
+ *
+ * @note This function may block if the connection is being established, depending on the socket's configuration.
+ *       For non-blocking sockets, it will return immediately, even if the connection has not been established.
+ *
+ * @warning The `socket` must be of a valid type (e.g., `SOCK_STREAM` for TCP or `SOCK_DGRAM` for UDP).
+ *          The `name` parameter must point to a valid `sockaddr` structure that contains a correctly formatted address.
+ */
 sysret_t sys_connect(int socket, const struct musl_sockaddr *name, socklen_t namelen)
 {
     int ret = 0;
@@ -3104,6 +5539,27 @@ sysret_t sys_connect(int socket, const struct musl_sockaddr *name, socklen_t nam
     return ret;
 }
 
+/**
+ * @brief Prepares a socket to accept incoming connection requests.
+ *
+ * This system call marks a socket as a passive socket, indicating that it will be used to accept
+ * incoming connection requests. It is typically used on server-side sockets after binding a
+ * local address and port using `sys_bind()`.
+ *
+ * @param[in]  socket   The socket descriptor to be set up for listening. The socket must be valid
+ *                      and of type `SOCK_STREAM` (for TCP connections).
+ * @param[in]  backlog  The maximum number of pending connections that can be queued. This value
+ *                      is system-dependent and may be limited to a lower maximum.
+ *
+ * @return sysret_t     Returns `0` on success, or a negative error code on failure.
+ *
+ * @note Before calling this function, the socket must be bound to a local address and port using
+ *       `sys_bind()`. Only sockets of type `SOCK_STREAM` can be used for listening. The actual
+ *       maximum queue length may be less than the specified `backlog` value, depending on system limits.
+ *
+ * @warning Ensure that the socket is properly initialized, bound, and of the correct type before calling this function.
+ *          Failure to do so will result in undefined behavior or errors.
+ */
 sysret_t sys_listen(int socket, int backlog)
 {
     return listen(socket, backlog);
@@ -3232,6 +5688,36 @@ static int copy_msghdr_from_user(struct msghdr *kmsg, struct msghdr *umsg,
 }
 #endif /* ARCH_MM_MMU */
 
+/**
+ * @brief Receives a message from a socket using a message header structure.
+ *
+ * This system call is used to receive data and associated metadata from a socket.
+ * It supports both stream-oriented and message-oriented sockets and allows control
+ * over the behavior of the receiving operation via the `flags` parameter.
+ *
+ * @param[in]  socket   The socket descriptor from which the message will be received.
+ *                      The socket must be in a valid and connected state for stream-oriented
+ *                      sockets or bound for message-oriented sockets.
+ * @param[out] msg      A pointer to an `msghdr` structure that specifies message buffers and
+ *                      will receive the incoming data. The structure also stores ancillary
+ *                      data for advanced socket operations.
+ * @param[in]  flags    Modifiers that control the behavior of the receive operation. Common
+ *                      flags include:
+ *                       - `MSG_PEEK`: Peek at the incoming data without removing it from the queue.
+ *                       - `MSG_WAITALL`: Wait for the full request to be satisfied before returning.
+ *                       - `MSG_DONTWAIT`: Perform a non-blocking receive operation.
+ *
+ * @return sysret_t     Returns `0` on success, or a negative error code on failure.
+ *
+ * @note The `msghdr` structure should be initialized properly, including setting up buffers for
+ *       receiving the data. The function can return fewer bytes than expected depending on socket
+ *       type and flags. For stream-oriented sockets, partial data may be received.
+ *
+ * @warning The `socket` must be valid and in an appropriate state. If the socket is non-blocking
+ *          and no data is available, the function will return immediately.
+ *
+ * @see sys_sendmsg()
+ */
 sysret_t sys_recvmsg(int socket, struct msghdr *msg, int flags)
 {
     int flgs, ret = -1;
@@ -3291,6 +5777,40 @@ sysret_t sys_recvmsg(int socket, struct msghdr *msg, int flags)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Receives data from a socket, optionally capturing the source address.
+ *
+ * This system call is used to receive data from a socket. For connectionless sockets, it also
+ * retrieves the address of the sender. It supports both blocking and non-blocking operations
+ * depending on the socket configuration and the specified flags.
+ *
+ * @param[in]  socket   The socket descriptor from which the data will be received. The socket
+ *                      must be valid and appropriately configured (e.g., connected or bound).
+ * @param[out] mem      A pointer to the buffer where the received data will be stored.
+ * @param[in]  len      The maximum number of bytes to receive. This defines the size of the `mem` buffer.
+ * @param[in]  flags    Modifiers that control the behavior of the receive operation. Common
+ *                      flags include:
+ *                       - `MSG_PEEK`: Peek at the incoming data without removing it from the queue.
+ *                       - `MSG_WAITALL`: Wait for the full request to be satisfied before returning.
+ *                       - `MSG_DONTWAIT`: Perform a non-blocking receive operation.
+ * @param[out] from     A pointer to a `musl_sockaddr` structure that will hold the address of
+ *                      the sender. This parameter can be `NULL` if the sender's address is not needed.
+ * @param[in,out] fromlen A pointer to a `socklen_t` variable indicating the size of the `from` buffer.
+ *                        On return, it will be updated with the actual size of the sender's address.
+ *                        This parameter is ignored if `from` is `NULL`.
+ *
+ * @return sysret_t     Returns `0` on success, or a negative error code on failure:
+ *
+ * @note For stream-oriented sockets, this function behaves like `sys_recv()`, and the `from` and
+ *       `fromlen` parameters are ignored. For datagram-oriented sockets, the function fills `from`
+ *       with the address of the sender.
+ *
+ * @warning The `socket` must be valid and configured for receiving data. If the `mem` buffer is
+ *          smaller than the received data, excess data may be discarded. In non-blocking mode,
+ *          if no data is available, the function returns immediately.
+ *
+ * @see sys_sendto(), sys_recv()
+ */
 sysret_t sys_recvfrom(int socket, void *mem, size_t len, int flags,
       struct musl_sockaddr *from, socklen_t *fromlen)
 {
@@ -3365,6 +5885,32 @@ sysret_t sys_recvfrom(int socket, void *mem, size_t len, int flags,
 #endif
 }
 
+/**
+ * @brief Receives data from a connected socket.
+ *
+ * This system call is used to receive data from a socket that is in a connected state.
+ * It supports various flags to modify the behavior of the receive operation.
+ *
+ * @param[in]  socket   The socket descriptor from which the data will be received.
+ *                      The socket must be in a valid and connected state.
+ * @param[out] mem      A pointer to the buffer where the received data will be stored.
+ * @param[in]  len      The maximum number of bytes to receive. This defines the size of the `mem` buffer.
+ * @param[in]  flags    Modifiers that control the behavior of the receive operation. Common flags include:
+ *                       - `MSG_PEEK`: Peek at the incoming data without removing it from the queue.
+ *                       - `MSG_WAITALL`: Wait for the full request to be satisfied before returning.
+ *                       - `MSG_DONTWAIT`: Perform a non-blocking receive operation.
+ *
+ * @return sysret_t     Returns `0` on success, or a negative error code on failure.
+ *
+ * @note The function is designed for connected sockets, such as stream-oriented sockets (e.g., TCP).
+ *       For datagram-oriented sockets (e.g., UDP), use `sys_recvfrom()` to capture the sender's address if needed.
+ *
+ * @warning The `socket` must be valid and in a connected state. If the `mem` buffer is smaller than the
+ *          received data, excess data may be discarded. For non-blocking sockets, the function returns
+ *          immediately if no data is available.
+ *
+ * @see sys_send(), sys_recvfrom()
+ */
 sysret_t sys_recv(int socket, void *mem, size_t len, int flags)
 {
     int flgs = 0;
@@ -3389,6 +5935,38 @@ sysret_t sys_recv(int socket, void *mem, size_t len, int flags)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Sends a message from a socket using scatter-gather I/O.
+ *
+ * This system call sends data from multiple buffers specified in the `msghdr` structure. It is particularly
+ * useful for advanced socket operations requiring ancillary data or scatter-gather I/O.
+ *
+ * @param[in] socket   The socket descriptor through which the data will be sent. The socket must be
+ *                     valid and, for connection-oriented sockets, in a connected state.
+ * @param[in] msg      A pointer to a `msghdr` structure that specifies the message to be sent. This structure includes:
+ *                      - `msg_name`: Optional address of the target (used for connectionless sockets like UDP).
+ *                      - `msg_namelen`: Length of the address in `msg_name`.
+ *                      - `msg_iov`: An array of `iovec` structures pointing to the data buffers.
+ *                      - `msg_iovlen`: The number of elements in the `msg_iov` array.
+ *                      - `msg_control`: Optional ancillary data (e.g., file descriptors).
+ *                      - `msg_controllen`: Length of the ancillary data.
+ *                      - `msg_flags`: Flags for the message (e.g., end-of-record markers).
+ * @param[in] flags    Flags that modify the behavior of the send operation. Common flags include:
+ *                      - `MSG_DONTWAIT`: Perform a non-blocking send operation.
+ *                      - `MSG_EOR`: Indicates the end of a record.
+ *                      - `MSG_NOSIGNAL`: Prevent the function from raising `SIGPIPE` on errors.
+ *
+ * @return sysret_t    Returns `0` on success, or a negative error code on failure.
+ *
+ * @note This function is versatile and supports both connection-oriented (e.g., TCP) and
+ *       connectionless (e.g., UDP) sockets. For simpler use cases, consider using `sys_send()` or `sys_sendto()`.
+ *
+ * @warning The `socket` must be configured correctly for the intended communication. For non-blocking sockets,
+ *          the function may return immediately if the send buffer is full. Ancillary data in `msg_control`
+ *          must be formatted correctly to avoid undefined behavior.
+ *
+ * @see sys_send(), sys_sendto(), sys_recvmsg()
+ */
 sysret_t sys_sendmsg(int socket, const struct msghdr *msg, int flags)
 {
     int flgs, ret = -1;
@@ -3440,6 +6018,35 @@ sysret_t sys_sendmsg(int socket, const struct msghdr *msg, int flags)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Sends data to a specific address using a socket.
+ *
+ * This system call is used to send data from a socket to a specified address. It is commonly
+ * used with connectionless sockets (e.g., UDP) but can also be used with connection-oriented
+ * sockets if the destination address needs to be overridden.
+ *
+ * @param[in] socket   The socket descriptor used for sending data. It must be valid and
+ *                     properly configured for communication.
+ * @param[in] dataptr  A pointer to the buffer containing the data to be sent.
+ * @param[in] size     The size, in bytes, of the data to be sent.
+ * @param[in] flags    Flags that modify the behavior of the send operation. Common flags include:
+ *                      - `MSG_DONTWAIT`: Perform a non-blocking send operation.
+ *                      - `MSG_NOSIGNAL`: Prevent the function from raising `SIGPIPE` on errors.
+ * @param[in] to       A pointer to a `musl_sockaddr` structure that specifies the destination address.
+ *                     This parameter can be `NULL` if the socket is connection-oriented.
+ * @param[in] tolen    The length of the address structure pointed to by `to`.
+ *
+ * @return sysret_t    Returns `0` on success, or a negative error code on failure.
+ *
+ * @note For connectionless sockets (e.g., UDP), `to` and `tolen` must specify a valid destination address.
+ *       For connection-oriented sockets (e.g., TCP), these parameters can be ignored if the connection
+ *       is already established.
+ *
+ * @warning Ensure that the buffer size (`size`) matches the expected size for the data protocol in use.
+ *          For non-blocking sockets, this function may return immediately if the send buffer is full.
+ *
+ * @see sys_send(), sys_sendmsg(), sys_recvfrom()
+ */
 sysret_t sys_sendto(int socket, const void *dataptr, size_t size, int flags,
     const struct musl_sockaddr *to, socklen_t tolen)
 {
@@ -3506,6 +6113,32 @@ sysret_t sys_sendto(int socket, const void *dataptr, size_t size, int flags,
 #endif
 }
 
+/**
+ * @brief Sends data over a connected socket.
+ *
+ * This system call sends data from the specified buffer through a connected socket. It is typically
+ * used with connection-oriented sockets (e.g., TCP) but can also work with connectionless sockets
+ * (e.g., UDP) if a connection is established using `sys_connect()`.
+ *
+ * @param[in] socket   The socket descriptor used for sending data. It must be a valid socket
+ *                     and, for connection-oriented sockets, in a connected state.
+ * @param[in] dataptr  A pointer to the buffer containing the data to be sent.
+ * @param[in] size     The size, in bytes, of the data to be sent.
+ * @param[in] flags    Flags that modify the behavior of the send operation. Common flags include:
+ *                      - `MSG_DONTWAIT`: Perform a non-blocking send operation.
+ *                      - `MSG_NOSIGNAL`: Prevent the function from raising `SIGPIPE` on errors.
+ *
+ * @return sysret_t    Returns `0` on success, or a negative error code on failure.
+ *
+ * @note For connection-oriented sockets, the socket must already be connected using `sys_connect()` or
+ *       `sys_accept()`. For connectionless sockets, use `sys_sendto()` to specify the destination address.
+ *
+ * @warning If the socket is in non-blocking mode and the send buffer is full, this function may return
+ *          immediately with an error. Ensure that the size of the data (`size`) matches the protocol's
+ *          expectations to avoid truncation or overflow issues.
+ *
+ * @see sys_sendto(), sys_sendmsg(), sys_recv()
+ */
 sysret_t sys_send(int socket, const void *dataptr, size_t size, int flags)
 {
     int flgs = 0;
@@ -3535,6 +6168,33 @@ sysret_t sys_send(int socket, const void *dataptr, size_t size, int flags)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Creates a new socket for communication.
+ *
+ * This system call creates a new socket endpoint for communication and returns a file descriptor
+ * that can be used for subsequent socket operations, such as binding, connecting, or data transfer.
+ *
+ * @param[in] domain   Specifies the protocol family to be used for the socket. Common values include:
+ *                      - `AF_INET`: IPv4 Internet protocols.
+ *                      - `AF_INET6`: IPv6 Internet protocols.
+ *                      - `AF_UNIX`: Local communication using UNIX domain sockets.
+ * @param[in] type     Specifies the type of socket to be created. Common values include:
+ *                      - `SOCK_STREAM`: Provides sequenced, reliable, two-way, connection-based byte streams.
+ *                      - `SOCK_DGRAM`: Supports datagrams (connectionless, unreliable messages of fixed maximum length).
+ *                      - `SOCK_RAW`: Provides raw network protocol access.
+ * @param[in] protocol Specifies the specific protocol to be used. Typically set to `0` to use the default
+ *                     protocol for the specified domain and type.
+ *
+ * @return sysret_t    Returns the socket file descriptor on success, or a negative error code on failure.
+ *
+ * @note The returned socket descriptor must be closed using `sys_close()` to release system resources.
+ *
+ * @warning Ensure the combination of `domain`, `type`, and `protocol` is valid. Invalid combinations
+ *          may result in errors. For example, specifying `AF_INET` with `SOCK_DGRAM` is valid for UDP,
+ *          but with `SOCK_STREAM` it is used for TCP.
+ *
+ * @see sys_bind(), sys_connect(), sys_accept(), sys_close()
+ */
 sysret_t sys_socket(int domain, int type, int protocol)
 {
     int fd = -1;
@@ -3564,6 +6224,34 @@ out:
     return (fd < 0 ? GET_ERRNO() : fd);
 }
 
+/**
+ * @brief Creates a pair of connected sockets.
+ *
+ * This system call creates two connected sockets that can be used for bidirectional communication
+ * between processes or threads. The sockets are returned as file descriptors in the `fd` array.
+ *
+ * @param[in] domain   Specifies the protocol family to be used for the sockets. Common values include:
+ *                      - `AF_UNIX`: Local communication using UNIX domain sockets.
+ * @param[in] type     Specifies the type of socket to be created. Common values include:
+ *                      - `SOCK_STREAM`: Provides sequenced, reliable, two-way, connection-based byte streams.
+ *                      - `SOCK_DGRAM`: Supports datagrams (connectionless, unreliable messages of fixed maximum length).
+ * @param[in] protocol Specifies the specific protocol to be used. Typically set to `0` to use the default
+ *                     protocol for the specified domain and type.
+ * @param[out] fd      An array of two integers where the connected socket descriptors will be stored.
+ *                     After a successful call:
+ *                      - `fd[0]`: The first socket descriptor.
+ *                      - `fd[1]`: The second socket descriptor.
+ *
+ * @return sysret_t    Returns `0` on success, or a negative error code on failure.
+ *
+ * @note The sockets in the pair are connected and can be used for inter-process communication
+ *       (IPC) or between threads in the same process.
+ *
+ * @warning Ensure the `domain`, `type`, and `protocol` combination is valid. This function is typically
+ *          supported only for `AF_UNIX` domain.
+ *
+ * @see sys_socket(), sys_close()
+ */
 sysret_t sys_socketpair(int domain, int type, int protocol, int fd[2])
 {
 #ifdef RT_USING_SAL
@@ -3588,6 +6276,25 @@ sysret_t sys_socketpair(int domain, int type, int protocol, int fd[2])
 #endif
 }
 
+/**
+ * @brief Closes an open socket.
+ *
+ * This system call is used to close a previously opened socket. Once the socket is closed, it is no longer
+ * valid for any further operations, such as sending, receiving, or other socket-related functions.
+ *
+ * @param[in] socket  The socket descriptor to be closed. This descriptor must be a valid socket that was
+ *                    previously created with `sys_socket()` or related functions.
+ *
+ * @return sysret_t   Returns `0` on success, or a negative error code on failure.
+ *
+ * @note Once a socket is closed, any attempts to use the socket for communication will result in an error.
+ *       The system will release any resources associated with the socket.
+ *
+ * @warning Make sure that no data is being transferred or pending on the socket before closing it.
+ *          Closing an active socket might lead to data loss.
+ *
+ * @see sys_socket(), sys_shutdown()
+ */
 sysret_t sys_closesocket(int socket)
 {
     return closesocket(socket);
@@ -3595,6 +6302,26 @@ sysret_t sys_closesocket(int socket)
 
 #endif
 
+/**
+ * @brief Finds a thread by its name.
+ *
+ * This system call is used to search for a thread based on its name. It returns a reference to the
+ * thread if found, otherwise it returns `RT_NULL`. The name comparison is case-sensitive.
+ *
+ * @param[in] name    The name of the thread to search for. This should be a valid string that
+ *                    uniquely identifies the thread within the system.
+ *
+ * @return rt_thread_t   The thread object corresponding to the given name, or `RT_NULL` if no
+ *                        matching thread was found.
+ *
+ * @note The thread name is typically assigned when the thread is created, and it can be used to
+ *       identify threads in the system.
+ *
+ * @warning Ensure that the `name` string is correctly set and unique within the system to avoid
+ *          unexpected behavior.
+ *
+ * @see sys_thread_create(), sys_thread_delete()
+ */
 rt_thread_t sys_thread_find(char *name)
 {
     int len = 0;
@@ -3626,11 +6353,49 @@ rt_thread_t sys_thread_find(char *name)
     return thread;
 }
 
+/**
+ * @brief Gets the current system tick count.
+ *
+ * This system call returns the current value of the system tick counter, which is typically incremented
+ * at a fixed interval (e.g., every millisecond or microsecond). The tick count can be used for timing
+ * purposes, such as measuring the elapsed time or triggering time-based events.
+ *
+ * @return rt_tick_t    The current value of the system tick counter.
+ *
+ * @note The system tick counter typically wraps around after reaching its maximum value, so the
+ *       returned tick value may reset after a certain period of time, depending on the configuration
+ *       of the system tick timer.
+ *
+ * @warning Be cautious when using the tick value for time-based calculations, as the counter may
+ *          overflow and wrap around. Ensure that the code handling the tick count properly accounts
+ *          for potential overflow.
+ *
+ * @see sys_tick_init(), sys_tick_delay()
+ */
 rt_tick_t sys_tick_get(void)
 {
     return rt_tick_get();
 }
 
+/**
+ * @brief Delays the current thread for a specified number of milliseconds.
+ *
+ * This system call puts the calling thread to sleep for a given number of milliseconds. It is a blocking
+ * call, meaning the thread will not execute any further instructions until the specified delay has
+ * passed. The delay is achieved by the system's timer mechanism.
+ *
+ * @param[in] ms   The number of milliseconds to delay. The value must be a positive integer.
+ *
+ * @return sysret_t   Returns `0` on success, or a negative error code on failure.
+ *
+ * @note This function is useful for introducing a fixed delay in time-sensitive applications or when
+ *       the thread needs to be paused before continuing execution.
+ *
+ * @warning Be cautious when using this function in real-time or time-critical applications, as
+ *          excessive delays may affect overall system performance or responsiveness.
+ *
+ * @see sys_thread_delay(), sys_thread_sleep()
+ */
 sysret_t sys_thread_mdelay(rt_int32_t ms)
 {
     return rt_thread_mdelay(ms);
@@ -3643,6 +6408,34 @@ struct k_sigaction {
     unsigned mask[2];
 };
 
+/**
+ * @brief Changes the action taken by the system on receiving a signal.
+ *
+ * This system call allows a process to specify how signals should be handled. It allows you to set a
+ * new action for a specific signal, retrieve the old action, and define the signal mask that should
+ * be applied during the execution of the signal handler.
+ *
+ * @param[in] sig         The signal number for which the action is to be set or retrieved.
+ *                        Signal numbers are typically defined as constants (e.g., `SIGINT`, `SIGTERM`).
+ * @param[in] act         A pointer to a `k_sigaction` structure that specifies the new action for the signal.
+ *                        If `act` is `NULL`, the signal's action is not changed.
+ * @param[out] oact       A pointer to a `k_sigaction` structure where the old action will be stored.
+ *                        If `oact` is `NULL`, the old action is not retrieved.
+ * @param[in] sigsetsize  The size of the `sigset_t` structure used in `k_sigaction`. This is to ensure the
+ *                        compatibility with the signal mask size.
+ *
+ * @return sysret_t      Returns `0` on success or a negative error code on failure.
+ *
+ * @note The `k_sigaction` structure allows you to specify the signal handler, signal mask, and flags for
+ *       the signal action. It is important to correctly configure the handler to prevent unexpected
+ *       behavior in the signal handling process.
+ *
+ * @warning Be cautious when modifying signal handling behavior, as incorrect configuration may result
+ *          in unhandled signals or undefined behavior. Signal handlers should be designed to perform
+ *          minimal, safe operations.
+ *
+ * @see sys_signal(), sys_sigprocmask()
+ */
 sysret_t sys_sigaction(int sig, const struct k_sigaction *act,
                        struct k_sigaction *oact, size_t sigsetsize)
 {
@@ -3710,6 +6503,35 @@ static int mask_command_u2k[] = {
     [SIG_SETMASK] = LWP_SIG_MASK_CMD_SET_MASK,
 };
 
+/**
+ * @brief Sets or retrieves the signal mask for the calling process.
+ *
+ * This system call allows the caller to block or unblock signals by modifying the signal mask. The signal
+ * mask determines which signals are blocked and which signals can be delivered to the process. The
+ * function can also be used to retrieve the current signal mask.
+ *
+ * @param[in] how      The action to be taken on the signal mask. It can be one of the following values:
+ *                     - `SIG_BLOCK`: Add the signals in `sigset` to the current mask.
+ *                     - `SIG_UNBLOCK`: Remove the signals in `sigset` from the current mask.
+ *                     - `SIG_SETMASK`: Set the signal mask to the value in `sigset`, replacing the current mask.
+ * @param[in] sigset   A pointer to a `sigset_t` structure that specifies the signals to be blocked or unblocked.
+ *                     This parameter is ignored when `how` is `SIG_SETMASK`, in which case `sigset` is used
+ *                     as the new signal mask.
+ * @param[out] oset    A pointer to a `sigset_t` structure where the previous signal mask will be stored.
+ *                     If `oset` is `NULL`, the previous signal mask will not be returned.
+ * @param[in] size     The size of the `sigset_t` structure, ensuring compatibility with the signal mask.
+ *
+ * @return sysret_t   Returns `0` on success or a negative error code on failure.
+ *
+ * @note Modifying the signal mask prevents signals from being delivered to the process while they are blocked.
+ *       Once the signals are unblocked, they will be delivered to the process if they are pending.
+ *
+ * @warning Be careful when blocking signals, especially critical ones like `SIGKILL`, as it may interfere
+ *          with the normal operation of the system. Ensure that signal masks are managed carefully to avoid
+ *          missing important signals.
+ *
+ * @see sys_sigaction(), sys_sigpending()
+ */
 sysret_t sys_sigprocmask(int how, const sigset_t *sigset, sigset_t *oset, size_t size)
 {
     int ret = -1;
@@ -3777,6 +6599,29 @@ sysret_t sys_sigprocmask(int how, const sigset_t *sigset, sigset_t *oset, size_t
     return (ret < 0 ? -EFAULT: ret);
 }
 
+/**
+ * @brief Retrieves the set of signals that are pending for delivery to the calling process.
+ *
+ * This system call allows a process to query the set of signals that are pending, i.e., signals that have
+ * been sent to the process but have not yet been delivered because the process is blocking those signals
+ * or has not yet handled them. The function returns the set of signals that are waiting to be delivered.
+ *
+ * @param[out] sigset   A pointer to a `sigset_t` structure where the set of pending signals will be stored.
+ *                      The `sigset_t` structure will contain the signals that are pending for delivery.
+ * @param[in] sigsize   The size of the `sigset_t` structure, used to ensure compatibility with the signal set.
+ *
+ * @return sysret_t    Returns `0` on success or a negative error code on failure.
+ *
+ * @note The returned signal set will contain the signals that have been sent to the process but are blocked,
+ *       or that are waiting to be handled. These signals will be delivered once they are unblocked or the
+ *       process handles them.
+ *
+ * @warning Be cautious when querying pending signals, as unblocking too many signals at once may lead
+ *          to unexpected behavior or a flood of signal deliveries. It's recommended to carefully manage
+ *          the signals the process can accept at any given time.
+ *
+ * @see sys_sigaction(), sys_sigprocmask()
+ */
 sysret_t sys_sigpending(sigset_t *sigset, size_t sigsize)
 {
     sysret_t ret = 0;
@@ -3805,6 +6650,33 @@ sysret_t sys_sigpending(sigset_t *sigset, size_t sigsize)
     return ret;
 }
 
+/**
+ * @brief Waits for a signal to be delivered, with a timeout.
+ *
+ * This system call allows a process to wait for one of the signals specified in the `sigset` to be delivered.
+ * The process will block until a signal in the set is received or the specified timeout period expires.
+ * If the signal is received before the timeout, information about the signal will be returned in the `siginfo_t` structure.
+ * If the timeout expires without any signal being delivered, the function will return with an appropriate error code.
+ *
+ * @param[in] sigset   A pointer to a `sigset_t` structure that specifies the set of signals to wait for.
+ *                     The function will block until a signal in this set is received, or the timeout expires.
+ * @param[out] info    A pointer to a `siginfo_t` structure where information about the delivered signal will be stored.
+ *                     If no signal is received before the timeout, this structure will not be filled.
+ * @param[in] timeout  A pointer to a `timespec` structure that specifies the maximum amount of time to wait
+ *                     for a signal to be delivered. If this value is `NULL`, the function will wait indefinitely.
+ * @param[in] sigsize  The size of the `sigset_t` structure, ensuring compatibility with the signal set.
+ *
+ * @return sysret_t   Returns `0` on success or a negative error code on failure.
+ *
+ * @note If the `timeout` is `NULL`, the function will block indefinitely until a signal is delivered.
+ *       If a signal is received, the corresponding information is returned in the `siginfo_t` structure.
+ *       The `sigset` should contain only the signals you are interested in.
+ *
+ * @warning If the timeout expires, no signal will be delivered, and the function will return a timeout error.
+ *          Make sure to handle the timeout case correctly to prevent any unexpected behavior.
+ *
+ * @see sys_sigaction(), sys_sigtimedwait()
+ */
 sysret_t sys_sigtimedwait(const sigset_t *sigset, siginfo_t *info, const struct timespec *timeout, size_t sigsize)
 {
     int sig;
@@ -3872,6 +6744,26 @@ sysret_t sys_sigtimedwait(const sigset_t *sigset, siginfo_t *info, const struct
     return sig;
 }
 
+/**
+ * @brief Sends a signal to a specific thread.
+ *
+ * This system call allows a process to send a signal to a specific thread within the same process.
+ * The signal specified by the `sig` parameter will be delivered to the thread with the ID `tid`.
+ * This function is similar to `kill()`, but it targets a specific thread rather than a process.
+ *
+ * @param[in] tid   The thread ID to which the signal will be sent. This ID identifies the target thread within the same process.
+ * @param[in] sig   The signal number to be sent to the specified thread. The signal can be any valid signal number.
+ *
+ * @return sysret_t Returns `0` on success or a negative error code on failure.
+ *
+ * @note The `sig` parameter must be a valid signal number. It can range from `1` to `31`, or be one of the predefined signal constants like `SIGKILL`, `SIGTERM`, etc.
+ *       If the target thread does not exist or is not eligible to receive the signal, the function will fail.
+ *
+ * @warning If an invalid signal number is provided or the target thread does not exist, an error will be returned.
+ *          Be careful when sending signals, as some signals (e.g., `SIGKILL`) can immediately terminate the target thread.
+ *
+ * @see sys_kill(), sys_sigaction()
+ */
 sysret_t sys_tkill(int tid, int sig)
 {
 #ifdef ARCH_MM_MMU
@@ -3894,6 +6786,33 @@ sysret_t sys_tkill(int tid, int sig)
 #endif
 }
 
+/**
+ * @brief Manipulates the signal mask for the current thread.
+ *
+ * This function allows a thread to modify its signal mask, which controls which signals are blocked (prevented from delivery).
+ * The signal mask can be modified by adding, removing, or setting the signal set as a whole, depending on the `how` parameter.
+ * The `sigset` specifies the signals to be manipulated, and the current signal mask before modification can be retrieved in `oset`.
+ *
+ * @param[in] how     The operation to perform on the signal mask. It can be one of the following values:
+ *                    - `SIG_BLOCK`: Add the signals in `sigset` to the current mask (block those signals).
+ *                    - `SIG_UNBLOCK`: Remove the signals in `sigset` from the current mask (unblock those signals).
+ *                    - `SIG_SETMASK`: Set the signal mask to the signals specified in `sigset` (replace the current mask).
+ * @param[in] sigset  A pointer to an `lwp_sigset_t` structure that specifies the set of signals to be manipulated.
+ *                    Signals in this set will be added, removed, or set in the current thread's signal mask based on the `how` parameter.
+ * @param[out] oset   A pointer to an `lwp_sigset_t` structure where the previous signal mask will be stored.
+ *                    This allows the caller to restore the previous mask if needed.
+ * @param[in] size    The size of the `lwp_sigset_t` structure. This ensures that the correct structure size is used during signal mask manipulation.
+ *
+ * @return sysret_t   Returns `0` on success or a negative error code on failure.
+ *
+ * @note The `sigset` structure should contain only valid signal numbers. If `how` is `SIG_SETMASK`, the entire signal mask will be replaced by the contents of `sigset`.
+ *       If `how` is `SIG_BLOCK` or `SIG_UNBLOCK`, the signals in `sigset` will be added or removed from the current mask, respectively.
+ *
+ * @warning Be cautious when modifying the signal mask, as blocking signals can cause the thread to miss important signals.
+ *          If a signal is blocked, it will not be delivered to the thread until it is unblocked, or the thread is explicitly made to handle it.
+ *
+ * @see sys_sigaction(), sys_thread_sigpending()
+ */
 sysret_t sys_thread_sigprocmask(int how, const lwp_sigset_t *sigset, lwp_sigset_t *oset, size_t size)
 {
     int ret = -1;
@@ -3962,6 +6881,29 @@ sysret_t sys_thread_sigprocmask(int how, const lwp_sigset_t *sigset, lwp_sigset_
 }
 
 #ifndef ARCH_MM_MMU
+
+/**
+ * @brief Sets the signal handler for a specific signal in the current thread.
+ *
+ * This function allows a thread to set a custom signal handler for a specific signal.
+ * When the specified signal is received, the corresponding handler function (`func`) will be invoked.
+ * The handler will be executed in the context of the current thread, allowing it to handle signals as needed.
+ *
+ * @param[in] sig    The signal number for which the handler is being set. This should be a valid signal number.
+ * @param[in] func   The signal handler function to be set. This function will be called when the specified signal is received.
+ *                   The signature of `func` should match the expected format for signal handlers.
+ *
+ * @return sysret_t  Returns `0` on success or a negative error code on failure.
+ *
+ * @note The `func` parameter must be a valid function pointer. It will be called when the signal specified by `sig` is received by the thread.
+ *       The handler function typically has the signature: `void handler(int sig)`, where `sig` is the signal number.
+ *
+ * @warning Setting a custom signal handler may override any default actions for that signal.
+ *          It is important to ensure that the handler function is properly designed to handle the signal appropriately.
+ *          For example, some signals may require special handling (e.g., `SIGKILL` cannot be caught).
+ *
+ * @see sys_signal(), sys_lwp_sigaction()
+ */
 sysret_t sys_lwp_sighandler_set(int sig, lwp_sighandler_t func)
 {
     if (!lwp_user_accessable((void *)func, sizeof(lwp_sighandler_t)))
@@ -3973,6 +6915,28 @@ sysret_t sys_lwp_sighandler_set(int sig, lwp_sighandler_t func)
     return 0;
 }
 
+/**
+ * @brief Sets the signal handler for a specific signal in the target thread.
+ *
+ * This function allows setting a custom signal handler for a specific signal within a particular thread.
+ * When the specified signal is delivered to the thread, the corresponding handler function (`func`) will be invoked.
+ * The handler is executed in the context of the thread that receives the signal.
+ *
+ * @param[in] sig    The signal number for which the handler is being set. This should be a valid signal number.
+ * @param[in] func   The signal handler function to be set. This function will be called when the specified signal is delivered to the target thread.
+ *                   The handler function should have the signature `void func(int sig)`.
+ *
+ * @return sysret_t  Returns `0` on success or a negative error code on failure.
+ *
+ * @note The `func` parameter must be a valid function pointer, and it will be invoked when the signal specified by `sig` is delivered to the target thread.
+ *       The handler function typically has the signature: `void handler(int sig)`, where `sig` is the signal number.
+ *
+ * @warning Setting a custom signal handler may override any default actions for that signal.
+ *          It is important to ensure that the handler function is properly designed to handle the signal appropriately.
+ *          For example, some signals may require special handling (e.g., `SIGKILL` cannot be caught).
+ *
+ * @see sys_thread_sigprocmask(), sys_thread_sigaction(), sys_signal()
+ */
 sysret_t sys_thread_sighandler_set(int sig, lwp_sighandler_t func)
 {
     if (!lwp_user_accessable((void *)func, sizeof(lwp_sighandler_t)))
@@ -3985,6 +6949,36 @@ sysret_t sys_thread_sighandler_set(int sig, lwp_sighandler_t func)
 }
 #endif /* not defined ARCH_MM_MMU */
 
+/**
+ * @brief Waits for the termination of a child process.
+ *
+ * This function makes the calling process wait until one of its child processes terminates or until a
+ * specified condition is met. The function retrieves information about the terminated child process,
+ * including its exit status, and can also handle other process-related events, such as stopping or
+ * continuing execution.
+ *
+ * @param[in] pid     The process ID of the child process to wait for. If `pid` is:
+ *                    - `-1`: Wait for any child process.
+ *                    - `0`: Wait for any child process in the same process group.
+ *                    - > 0: Wait for the child process with the specified process ID.
+ * @param[out] status A pointer to an integer where the exit status of the terminated child process will be stored.
+ *                    This value provides information about the child's termination status, such as normal exit,
+ *                    signal termination, etc.
+ * @param[in] options A bitmask of options that control the behavior of the function. It can include:
+ *                    - `WNOHANG`: Return immediately if no child has exited.
+ *                    - `WUNTRACED`: Report status of stopped child processes.
+ *                    - Other flags can be defined depending on the implementation.
+ *
+ * @return sysret_t  Returns the process ID of the child process that terminated on success, or a negative error code on failure.
+ *
+ * @note The `status` argument provides detailed information about the termination of the child process. To interpret this
+ *       status, macros such as `WIFEXITED()`, `WIFSIGNALED()`, and `WEXITSTATUS()` are commonly used.
+ *
+ * @warning This function should be used carefully when managing child processes, as not properly handling child processes
+ *          may lead to zombie processes.
+ *
+ * @see sys_wait(), sys_waitid()
+ */
 sysret_t sys_waitpid(int32_t pid, int *status, int options)
 {
     int ret = -1;
@@ -4022,6 +7016,38 @@ struct musl_addrinfo
     struct musl_addrinfo *ai_next;
 };
 
+/**
+ * @brief Resolves network addresses and service names into a list of address structures.
+ *
+ * This function provides a mechanism for resolving a host name and service name (or port number)
+ * into a list of address structures suitable for use with socket-based communication. The function
+ * can handle both IPv4 and IPv6 addresses and provides a flexible way to specify different types
+ * of address and service resolution options.
+ *
+ * @param[in] nodename  The host name to be resolved. This can be a DNS name or an IP address in string format.
+ *                      If `nodename` is `NULL`, the function will resolve the local host.
+ * @param[in] servname  The service name (e.g., "http") or port number to be resolved. If `servname` is `NULL`,
+ *                      the function will resolve the port number or address without any service association.
+ * @param[in] hints     A pointer to a `struct musl_addrinfo` that provides hints for the address resolution.
+ *                      It can be used to specify criteria such as the desired address family (IPv4 or IPv6),
+ *                      socket type, protocol, and flags for resolution.
+ * @param[out] res      A pointer to a `struct musl_addrinfo` that will be filled with the resolved address
+ *                      information. The resulting linked list will contain one or more `struct musl_sockaddr`
+ *                      structures, each representing a different address that can be used for communication.
+ *
+ * @return sysret_t     Returns `0` on success, indicating that the address resolution was successful.
+ *                       On failure, returns a negative error code.
+ *
+ * @note The `res` parameter points to a linked list of resolved address structures. Each node in the list
+ *       contains a different resolved address and can be used for socket connection purposes.
+ *       It is important to free the memory allocated for the list after it is no longer needed, using `freeaddrinfo()`.
+ *
+ * @warning The `hints` structure allows you to specify various options for the resolution. However, incorrect
+ *          hints may lead to unexpected or incorrect results. For example, if you request IPv6 addresses but
+ *          the host only supports IPv4, the function may not return the expected results.
+ *
+ * @see freeaddrinfo(), sys_socket(), sys_connect(), sys_gethostbyname(), sys_gethostbyaddr()
+ */
 sysret_t sys_getaddrinfo(const char *nodename,
         const char *servname,
         const struct musl_addrinfo *hints,
@@ -4189,6 +7215,37 @@ exit:
 }
 
 #define HOSTENT_BUFSZ   512
+
+/**
+ * @brief Resolves a host name to an address, with support for specifying the address family.
+ *
+ * This function performs a lookup of the specified host name, and resolves it to an address,
+ * while allowing the caller to specify the desired address family (e.g., IPv4 or IPv6). It is
+ * a reentrant version of `gethostbyname2`, meaning it is safe for use in multi-threaded applications.
+ * The results are returned in a user-provided buffer to avoid memory allocation overhead.
+ *
+ * @param[in] name      The host name to be resolved. This can be a DNS name or an IP address in string format.
+ * @param[in] af        The address family to use for the resolution. Common values are:
+ *                      - `AF_INET` for IPv4 addresses.
+ *                      - `AF_INET6` for IPv6 addresses.
+ * @param[out] ret      A pointer to a `struct hostent` where the resolved host information will be stored.
+ *                      This includes the host name, alias names, address type, and the address itself.
+ * @param[in] buf       A buffer to store additional information required for the `struct hostent` structure.
+ *                      This is needed to ensure the reentrant behavior and avoid memory allocation.
+ * @param[in] buflen    The size of the buffer provided.
+ * @param[out] result   A pointer to a `struct hostent*` that will point to the resolved host entry.
+ *                      This will be set to the value of `ret` upon success.
+ * @param[out] err      A pointer to an integer where error codes will be stored. If the function fails,
+ *                      `err` will contain a non-zero value corresponding to the error.
+ *
+ * @return sysret_t     Returns `0` on success, indicating the resolution was successful.
+ *                       On failure, returns a negative error code that indicates the failure reason.
+ *
+ * @note This function is reentrant and thread-safe, meaning it does not use static memory or global state.
+ *       It relies on the buffers provided by the caller to store the resolved data.
+ *
+ * @see gethostbyname2(), sys_gethostbyname(), sys_socket(), sys_connect(), sys_getaddrinfo()
+ */
 sysret_t sys_gethostbyname2_r(const char *name, int af, struct hostent *ret,
         char *buf, size_t buflen,
         struct hostent **result, int *err)
@@ -4348,6 +7405,29 @@ __exit:
 }
 #endif
 
+/**
+ * @brief Gets the current working directory.
+ *
+ * This function retrieves the absolute pathname of the current working directory
+ * and stores it in the provided buffer. The buffer must be large enough to hold
+ * the directory path, including the null-terminator. If the buffer is too small,
+ * the function will return an error.
+ *
+ * @param[out] buf     A pointer to a buffer where the current working directory
+ *                     path will be stored. The buffer should be large enough
+ *                     to hold the path, including the null-terminator.
+ * @param[in] size     The size of the buffer in bytes. The buffer must be large enough
+ *                     to accommodate the full path.
+ *
+ * @return long        On success, returns the number of bytes written to the buffer
+ *                     (not including the null-terminator). If the buffer is not large
+ *                     enough, returns a negative error code.
+ *
+ * @note The maximum path length depends on the system's configuration.
+ *       Ensure the buffer size is sufficient to hold the entire path.
+ *
+ * @see sys_chdir(), sys_getcwd_r(), sys_realpath()
+ */
 long sys_getcwd(char *buf, size_t size)
 {
     char *tmp = RT_NULL;
@@ -4380,6 +7460,26 @@ long sys_getcwd(char *buf, size_t size)
     return ret;
 }
 
+/**
+ * @brief Changes the current working directory.
+ *
+ * This function changes the current working directory of the calling process
+ * to the directory specified by the given path. The path can be absolute or
+ * relative. If the specified path does not exist or the process does not have
+ * sufficient permissions, the function will return an error.
+ *
+ * @param[in] path     The path to the new working directory. This can be either
+ *                     an absolute or a relative path.
+ *
+ * @return sysret_t    Returns `0` on success, indicating that the working
+ *                     directory was successfully changed. On failure, returns a
+ *                     negative error code indicating the reason for failure.
+ *
+ * @note If the specified path is a relative path, it is interpreted relative
+ *       to the current working directory.
+ *
+ * @see sys_getcwd(), sys_chdir() for changing directories, sys_opendir(), sys_stat()
+ */
 sysret_t sys_chdir(const char *path)
 {
 #ifdef ARCH_MM_MMU
@@ -4418,6 +7518,26 @@ sysret_t sys_chdir(const char *path)
 #endif
 }
 
+/**
+ * @brief Changes the current working directory to the one associated with the specified file descriptor.
+ *
+ * This function changes the current working directory of the calling process
+ * to the directory associated with the file descriptor `fd`. The file descriptor
+ * should refer to an open directory. If the file descriptor does not refer to a
+ * directory, or if the process lacks the necessary permissions, the function will
+ * return an error.
+ *
+ * @param[in] fd   The file descriptor referring to the directory to which the current
+ *                 working directory should be changed.
+ *
+ * @return sysret_t    Returns `0` on success, indicating the current working directory
+ *                     was successfully changed. On failure, returns a negative error code.
+ *
+ * @note The file descriptor must refer to a directory. If it refers to a file or other
+ *       non-directory object, the operation will fail.
+ *
+ * @see sys_chdir(), sys_getcwd(), sys_opendir(), sys_open()
+ */
 sysret_t sys_fchdir(int fd)
 {
     int errcode = -ENOSYS;
@@ -4447,6 +7567,27 @@ sysret_t sys_fchdir(int fd)
     return errcode;
 }
 
+/**
+ * @brief Creates a new directory with the specified path and mode.
+ *
+ * This function creates a new directory with the specified path and mode.
+ * The directory is created with the permissions specified by the `mode` parameter.
+ * If the directory already exists, the function will return an error.
+ *
+ * @param[in] path     The path of the directory to be created. This can be an absolute
+ *                     or relative path. If the directory does not exist, it will be created.
+ * @param[in] mode     The permissions to be set for the new directory. This parameter
+ *                     specifies the access permissions for the directory owner, group, and others.
+ *
+ * @return sysret_t    Returns `0` on success, indicating that the directory was successfully
+ *                     created. On failure, returns a negative error code indicating the reason for failure.
+ *
+ * @note The `mode` parameter specifies the permissions for the new directory. The permissions
+ *       are typically specified using the `S_IRWXU`, `S_IRWXG`, and `S_IRWXO` macros, which
+ *       define the read, write, and execute permissions for the owner, group, and others.
+ *
+ * @see sys_rmdir(), sys_chdir(), sys_mkdirat()
+ */
 sysret_t sys_mkdir(const char *path, mode_t mode)
 {
 #ifdef ARCH_MM_MMU
@@ -4483,6 +7624,26 @@ sysret_t sys_mkdir(const char *path, mode_t mode)
 #endif
 }
 
+/**
+ * @brief Removes the specified directory.
+ *
+ * This function removes the directory specified by the given path. The directory
+ * must be empty for the operation to succeed. If the directory is not empty, the
+ * function will return an error. If the directory does not exist or the process
+ * lacks the necessary permissions, the function will also return an error.
+ *
+ * @param[in] path     The path of the directory to be removed. This can be an absolute
+ *                     or relative path. The directory must be empty for the operation to succeed.
+ *
+ * @return sysret_t    Returns `0` on success, indicating that the directory was successfully
+ *                     removed. On failure, returns a negative error code indicating the reason for failure.
+ *
+ * @note The directory must be empty for the operation to succeed. If the directory contains
+ *       files or subdirectories, the operation will fail. To remove a non-empty directory,
+ *       the contents must be deleted first.
+ *
+ * @see sys_mkdir(), sys_chdir(), sys_rmdirat()
+ */
 sysret_t sys_rmdir(const char *path)
 {
     int err = 0;
@@ -4528,6 +7689,30 @@ sysret_t sys_rmdir(const char *path)
 #endif
 }
 
+/**
+ * @brief Reads directory entries.
+ *
+ * This function reads the directory entries from the directory stream specified by the file descriptor `fd`.
+ * It stores the directory entries in the buffer pointed to by `dirp`, up to the specified number of bytes (`nbytes`).
+ * The entries are returned in a format compatible with the `struct libc_dirent` structure.
+ *
+ * @param[in] fd      The file descriptor referring to an open directory. This descriptor must be obtained
+ *                    from a call to `sys_open()` with the appropriate flags for directory reading.
+ * @param[out] dirp   A pointer to a buffer where the directory entries will be stored.
+ *                    The buffer must be large enough to hold at least `nbytes` bytes of directory entries.
+ * @param[in] nbytes  The size of the buffer (`dirp`) in bytes. It limits the number of directory entries
+ *                    that can be read in a single call. The function will return as many entries as possible
+ *                    that fit within the buffer size.
+ *
+ * @return sysret_t   Returns the number of bytes read on success, which may be less than `nbytes` if there
+ *                     are fewer entries in the directory or if the buffer is too small.
+ *                     On failure, returns a negative error code.
+ *
+ * @note If the function returns 0, it indicates the end of the directory stream. A negative return value
+ *       indicates an error. The caller can use the returned number of bytes to process the entries in `dirp`.
+ *
+ * @see sys_open(), sys_close(), sys_readdir(), sys_stat()
+ */
 sysret_t sys_getdents(int fd, struct libc_dirent *dirp, size_t nbytes)
 {
     int ret = -1;
@@ -4580,12 +7765,49 @@ sysret_t sys_getdents(int fd, struct libc_dirent *dirp, size_t nbytes)
     return ret;
 }
 
+/**
+ * @brief Retrieves the current value of the error code.
+ *
+ * This function returns the most recent error code set by a system call. The error code is typically set
+ * when a system call fails. This function allows users to retrieve the last error that occurred, helping to
+ * diagnose issues or handle errors in a more controlled manner.
+ *
+ * @return sysret_t  The current error code. A value of `0` indicates no error, while a non-zero value
+ *                   represents the most recent error. The error codes are system-specific and can
+ *                   represent various failure conditions (e.g., `EINVAL`, `ENOMEM`, `EIO`).
+ *
+ * @note The error code returned is specific to the current thread or process and is typically updated
+ *       each time a system call fails. The error code is persistent until it is overwritten by the next
+ *       failed system call or explicitly reset.
+ *
+ * @see sys_set_errno(), sys_perror(), sys_strerror()
+ */
 sysret_t sys_get_errno(void)
 {
     return rt_get_errno();
 }
 
 #ifdef ARCH_MM_MMU
+
+/**
+ * @brief Sets the thread-specific data area.
+ *
+ * This function is used to associate a specific area of memory with the current thread. The area pointed to
+ * by `p` is set as the thread's local storage. Thread-specific data is used to store data that is unique to
+ * each thread, allowing different threads to maintain independent state information.
+ *
+ * @param[in] p  A pointer to the memory area that is to be set as the thread's local storage. This area
+ *               will be used by the thread to store its specific data. The structure and size of the data
+ *               area depend on the implementation and use case.
+ *
+ * @return sysret_t   Returns `0` on success. On failure, it returns a negative error code.
+ *
+ * @note This function is typically used to set up thread-specific storage for managing data that should
+ *       not be shared between threads. The data area is accessible only by the thread that set it, ensuring
+ *       thread safety for the stored information.
+ *
+ * @see sys_get_thread_area(), sys_thread_create(), sys_thread_self()
+ */
 sysret_t sys_set_thread_area(void *p)
 {
     rt_thread_t thread;
@@ -4597,6 +7819,27 @@ sysret_t sys_set_thread_area(void *p)
     return 0;
 }
 
+/**
+ * @brief Sets the address at which the thread ID is stored.
+ *
+ * This function sets the address of a variable that will store the thread ID for the calling thread.
+ * The specified address `tidptr` will hold the thread's unique identifier. This can be useful for
+ * managing thread-specific state or for synchronization mechanisms where the thread's ID needs to be
+ * shared or checked by other parts of the system.
+ *
+ * @param[in] tidptr  A pointer to an integer where the thread ID will be stored. This value will
+ *                    hold the calling thread's ID, and it can be accessed to identify the thread
+ *                    later. The value of the thread ID can be used in various thread management
+ *                    operations.
+ *
+ * @return sysret_t   Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function is typically used in systems that require associating a specific address with the
+ *       thread ID, often in real-time or embedded systems where managing and accessing thread IDs is
+ *       crucial for scheduling or resource allocation.
+ *
+ * @see sys_get_tid(), sys_thread_self(), sys_thread_create()
+ */
 sysret_t sys_set_tid_address(int *tidptr)
 {
     rt_thread_t thread;
@@ -4613,11 +7856,47 @@ sysret_t sys_set_tid_address(int *tidptr)
 }
 #endif /* ARCH_MM_MMU */
 
+/**
+ * @brief Gets the thread ID of the calling thread.
+ *
+ * This function returns the unique thread identifier (thread ID) for the calling thread. The thread ID
+ * can be used to uniquely identify the thread within the system and is typically used for debugging,
+ * thread management, or scheduling purposes.
+ *
+ * @return sysret_t   The thread ID of the calling thread. The value is typically a positive integer
+ *                     representing the unique ID assigned to the thread. In case of failure, an error code
+ *                     may be returned.
+ *
+ * @note The thread ID returned by this function is unique within the system, and it may be used to
+ *       reference or manipulate the specific thread associated with the ID.
+ *
+ * @see sys_set_tid_address(), sys_thread_self(), sys_thread_create()
+ */
 sysret_t sys_gettid(void)
 {
     return rt_thread_self()->tid;
 }
 
+/**
+ * @brief Checks the accessibility of a file or directory.
+ *
+ * This function checks whether the calling process has the specified access rights for the given file or directory.
+ * The check is performed based on the provided `mode`, which can indicate whether read, write, or execute permissions
+ * are required.
+ *
+ * @param[in] filename  The path to the file or directory whose accessibility is being checked.
+ * @param[in] mode      The access mode to check for. This can be a combination of the following:
+ *                      - `R_OK`: Check for read permission.
+ *                      - `W_OK`: Check for write permission.
+ *                      - `X_OK`: Check for execute permission.
+ *                      - `F_OK`: Check if the file exists.
+ *
+ * @return sysret_t     Returns `0` if the specified access is allowed. On failure, returns a negative error code.
+ *
+ * @note This function does not modify the file or directory, it only checks if the specified access rights are granted.
+ *
+ * @see sys_open(), sys_stat(), sys_fstat(), sys_chmod(), sys_chown()
+ */
 sysret_t sys_access(const char *filename, int mode)
 {
     int ret = 0;
@@ -4657,6 +7936,24 @@ sysret_t sys_access(const char *filename, int mode)
 #endif
 }
 
+/**
+ * @brief Creates a pipe, a unidirectional data channel.
+ *
+ * This function creates a pipe, which is a unidirectional data channel used for inter-process communication.
+ * The pipe consists of two file descriptors: one for reading from the pipe and one for writing to the pipe.
+ * The pipe is used for passing data between processes or threads, typically in a producer-consumer scenario.
+ *
+ * @param[out] fd  An array of two integers where the file descriptors for the read and write ends of the pipe will be stored.
+ *                 - `fd[0]`: The file descriptor for reading from the pipe.
+ *                 - `fd[1]`: The file descriptor for writing to the pipe.
+ *
+ * @return sysret_t   Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The pipe created by this function is typically used for simple communication between processes or threads.
+ *       The data written to `fd[1]` can be read from `fd[0]`. After usage, both file descriptors should be closed.
+ *
+ * @see sys_read(), sys_write(), sys_close(), sys_fork(), sys_execve()
+ */
 sysret_t sys_pipe(int fd[2])
 {
     int ret;
@@ -4674,11 +7971,65 @@ sysret_t sys_pipe(int fd[2])
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Waits for a process to change state.
+ *
+ * This function suspends the execution of the calling process until one of its child processes terminates
+ * or a specified process (identified by `pid`) changes its state. The function returns the process ID of the child
+ * process that terminated, and provides information about its exit status and resource usage.
+ *
+ * @param[in]  pid      The process ID of the child process to wait for. The behavior of this parameter can be one of the following:
+ *                      - `pid > 0`: Wait for the child process with the specified PID.
+ *                      - `pid == 0`: Wait for any child process in the same process group.
+ *                      - `pid == -1`: Wait for any child process (default behavior).
+ *                      - `pid < -1`: Wait for any child process in the specified process group.
+ *
+ * @param[out] status   A pointer to an integer where the exit status of the terminated child process will be stored.
+ *                      This status can be interpreted using macros such as `WIFEXITED` or `WIFSIGNALED`.
+ *
+ * @param[in]  options  Options for the wait operation, which can include:
+ *                      - `WNOHANG`: Return immediately if no child has exited.
+ *                      - `WUNTRACED`: Return if a child has stopped, but not yet terminated.
+ *
+ * @param[out] ru       A pointer to a `struct rusage` where resource usage information of the child process will be stored.
+ *                      This includes information such as CPU time consumed by the child process.
+ *
+ * @return sysret_t     Returns the process ID of the terminated child on success. In case of failure, a negative error code is returned.
+ *
+ * @note This function is useful for monitoring and cleaning up child processes in parent-child relationships.
+ *       The `status` value can be further analyzed to determine if the child process terminated normally or due to a signal.
+ *
+ * @see sys_waitpid(), sys_fork(), sys_exit()
+ */
 sysret_t sys_wait4(pid_t pid, int *status, int options, struct rusage *ru)
 {
     return lwp_waitpid(pid, status, options, ru);
 }
 
+/**
+ * @brief Sets the time of a specified clock.
+ *
+ * This function sets the time of the specified clock (identified by `clk`) to the given value. The time is provided
+ * as a `struct timespec` containing seconds and nanoseconds. This function can be used to set the system clock or
+ * other specific clocks, such as monotonic or real-time clocks.
+ *
+ * @param[in] clk  The clock ID for which to set the time. The clock can be one of the following:
+ *                 - `CLOCK_REALTIME`: Set the system's real-time clock.
+ *                 - `CLOCK_MONOTONIC`: Set the monotonic clock, which measures time since some unspecified starting point.
+ *                 - `CLOCK_PROCESS_CPUTIME_ID`: Set the CPU time used by the process.
+ *                 - `CLOCK_THREAD_CPUTIME_ID`: Set the CPU time used by the current thread.
+ *
+ * @param[in] ts   A pointer to a `struct timespec` containing the new time to set for the specified clock.
+ *                 - `ts->tv_sec`: Seconds since the epoch (for `CLOCK_REALTIME`) or since some unspecified start point (for other clocks).
+ *                 - `ts->tv_nsec`: Nanoseconds within the current second.
+ *
+ * @return sysret_t  Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function requires appropriate permissions for setting the system's clock. In some systems, only privileged users
+ *       may change the `CLOCK_REALTIME` clock.
+ *
+ * @see sys_clock_gettime(), sys_clock_getres()
+ */
 sysret_t sys_clock_settime(clockid_t clk, const struct timespec *ts)
 {
     int ret = 0;
@@ -4717,6 +8068,29 @@ sysret_t sys_clock_settime(clockid_t clk, const struct timespec *ts)
 #endif
 }
 
+/**
+ * @brief Retrieves the current time of a specified clock.
+ *
+ * This function retrieves the current time of the specified clock (identified by `clk`) and stores it in the
+ * `struct timespec` pointed to by `ts`. The time is expressed in seconds and nanoseconds. The clock can be
+ * one of several types, such as real-time, monotonic, or process-specific clocks.
+ *
+ * @param[in] clk  The clock ID for which to get the time. The clock can be one of the following:
+ *                 - `CLOCK_REALTIME`: Get the system's real-time clock.
+ *                 - `CLOCK_MONOTONIC`: Get the monotonic clock, which measures time since some unspecified starting point.
+ *                 - `CLOCK_PROCESS_CPUTIME_ID`: Get the CPU time used by the process.
+ *                 - `CLOCK_THREAD_CPUTIME_ID`: Get the CPU time used by the current thread.
+ *
+ * @param[out] ts  A pointer to a `struct timespec` where the current time for the specified clock will be stored.
+ *                 - `ts->tv_sec`: Seconds since the epoch (for `CLOCK_REALTIME`) or since some unspecified start point (for other clocks).
+ *                 - `ts->tv_nsec`: Nanoseconds within the current second.
+ *
+ * @return sysret_t  Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function requires appropriate permissions for retrieving certain clocks (e.g., `CLOCK_REALTIME`).
+ *
+ * @see sys_clock_settime(), sys_clock_getres()
+ */
 sysret_t sys_clock_gettime(clockid_t clk, struct timespec *ts)
 {
     int ret = 0;
@@ -4757,6 +8131,40 @@ sysret_t sys_clock_gettime(clockid_t clk, struct timespec *ts)
 #endif
 }
 
+/**
+ * @brief Suspends the execution of the calling thread for the specified time duration.
+ *
+ * This function causes the calling thread to sleep for the specified time duration, which is provided as a
+ * `struct timespec` containing seconds and nanoseconds. The sleep is done based on the specified clock (identified by `clk`).
+ * If the `flags` parameter is set to `TIMER_ABSTIME`, the specified time represents an absolute time, otherwise,
+ * it represents a relative time interval.
+ *
+ * @param[in] clk   The clock ID for which to perform the sleep. The clock can be one of the following:
+ *                  - `CLOCK_REALTIME`: Use the system's real-time clock.
+ *                  - `CLOCK_MONOTONIC`: Use the monotonic clock, which measures time since some unspecified starting point.
+ *                  - `CLOCK_PROCESS_CPUTIME_ID`: Use the CPU time used by the process.
+ *                  - `CLOCK_THREAD_CPUTIME_ID`: Use the CPU time used by the current thread.
+ *
+ * @param[in] flags The sleep behavior flags. The possible flags are:
+ *                  - `0`: The sleep duration is relative to the current time.
+ *                  - `TIMER_ABSTIME`: The sleep duration is absolute (measured from the specified clock).
+ *
+ * @param[in] rqtp  A pointer to a `struct timespec` containing the requested sleep time.
+ *                  - `rqtp->tv_sec`: Seconds to sleep.
+ *                  - `rqtp->tv_nsec`: Nanoseconds to sleep (0 ≤ `rqtp->tv_nsec` < 1 billion).
+ *
+ * @param[out] rmtp A pointer to a `struct timespec` where the remaining time will be stored if the sleep is interrupted.
+ *                  If the sleep completes successfully, `rmtp` will not be modified.
+ *                  - `rmtp->tv_sec`: Remaining seconds.
+ *                  - `rmtp->tv_nsec`: Remaining nanoseconds.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function can be interrupted by signals. In that case, the remaining time is returned in `rmtp`.
+ *       If the sleep is not interrupted, the function returns `SYSRET_OK` when the requested time has passed.
+ *
+ * @see sys_clock_gettime(), sys_clock_settime(), sys_nanosleep()
+ */
 sysret_t sys_clock_nanosleep(clockid_t clk, int flags, const struct timespec *rqtp, struct timespec *rmtp)
 {
     int ret = 0;
@@ -4787,6 +8195,29 @@ sysret_t sys_clock_nanosleep(clockid_t clk, int flags, const struct timespec *rq
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Get the resolution of the specified clock.
+ *
+ * This function retrieves the resolution of the specified clock, which is the smallest time interval that the clock can measure.
+ * The resolution is returned in a `struct timespec` which contains seconds and nanoseconds.
+ *
+ * @param[in] clk   The clock ID for which to get the resolution. The clock can be one of the following:
+ *                  - `CLOCK_REALTIME`: System's real-time clock.
+ *                  - `CLOCK_MONOTONIC`: Monotonic clock (measures time since an unspecified point).
+ *                  - `CLOCK_PROCESS_CPUTIME_ID`: CPU time consumed by the current process.
+ *                  - `CLOCK_THREAD_CPUTIME_ID`: CPU time consumed by the current thread.
+ *
+ * @param[out] ts   A pointer to a `struct timespec` where the clock's resolution will be stored.
+ *                  - `ts->tv_sec`: The number of seconds in the resolution.
+ *                  - `ts->tv_nsec`: The number of nanoseconds in the resolution (0 ≤ `ts->tv_nsec` < 1 billion).
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The resolution may be zero for some clocks, depending on the system's configuration.
+ *       A clock's resolution determines the smallest unit of time the clock can measure.
+ *
+ * @see sys_clock_gettime(), sys_clock_settime(), sys_clock_nanosleep()
+ */
 sysret_t sys_clock_getres(clockid_t clk, struct timespec *ts)
 {
     int ret = 0;
@@ -4813,6 +8244,24 @@ sysret_t sys_clock_getres(clockid_t clk, struct timespec *ts)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Rename or move a file or directory.
+ *
+ * This function renames or moves a file or directory from `oldpath` to `newpath`.
+ * If the `newpath` exists, it may be overwritten depending on the system's file system behavior and
+ * the permissions of the files involved.
+ *
+ * @param[in] oldpath  The current path of the file or directory to rename or move.
+ * @param[in] newpath  The new path or name to which the file or directory should be renamed or moved.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note If `oldpath` and `newpath` refer to different file systems, the behavior may vary,
+ *       as the operation might involve copying and removing files instead of simply renaming them.
+ *       The success of the operation also depends on the permissions of the source and destination.
+ *
+ * @see sys_unlink(), sys_mkdir(), sys_access()
+ */
 sysret_t sys_rename(const char *oldpath, const char *newpath)
 {
     int ret = -1;
@@ -4861,6 +8310,28 @@ sysret_t sys_prlimit64(pid_t pid,
     return -ENOSYS;
 }
 
+/**
+ * @brief Get resource limits.
+ *
+ * This function retrieves the current resource limits for the specified resource type.
+ * The resource limit specifies the maximum value for a particular resource that a process or thread can use.
+ * The limits are returned in an array `rlim` where:
+ * - `rlim[0]` represents the soft limit (the current value).
+ * - `rlim[1]` represents the hard limit (the maximum allowable value).
+ *
+ * @param[in] resource  The resource for which to get the limits. It can be one of the following:
+ *                      - `RLIMIT_NOFILE`: Maximum number of file descriptors.
+ *
+ * @param[out] rlim    An array to store the resource limits. The array should have at least 2 elements:
+ *                     - `rlim[0]`: The soft limit for the resource.
+ *                     - `rlim[1]`: The hard limit for the resource.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The limits returned by `sys_getrlimit` are subject to system constraints and may vary across different systems.
+ *
+ * @see sys_setrlimit(), sys_getrlimit64(), sys_getrusage()
+ */
 sysret_t sys_getrlimit(unsigned int resource, unsigned long rlim[2])
 {
     int ret = -1;
@@ -4904,6 +8375,29 @@ sysret_t sys_setrlimit(unsigned int resource, struct rlimit *rlim)
     return -ENOSYS;
 }
 
+/**
+ * @brief Get random data from the kernel's random number generator.
+ *
+ * This function retrieves cryptographically secure random data from the kernel's random number generator
+ * and stores it in the buffer provided by the user. The data can be used for cryptographic operations or
+ * other applications requiring randomization.
+ *
+ * @param[out] buf     A pointer to the buffer where the random data will be stored. The buffer must be large
+ *                     enough to hold the requested amount of random data.
+ * @param[in]  buflen  The number of bytes of random data to retrieve. This value must be a positive integer.
+ * @param[in]  flags   Optional flags to modify the behavior of the random data retrieval. Possible values may include:
+ *                     - `GRND_RANDOM`: Requests random data from the system's non-blocking random source.
+ *                     - `GRND_NONBLOCK`: Instructs the function to return immediately even if insufficient entropy is available.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note
+ * - If the `GRND_NONBLOCK` flag is not set and there is insufficient entropy in the system's random pool,
+ *   this function may block until enough entropy is available.
+ * - The function returns cryptographically secure random data, suitable for use in secure applications.
+ *
+ * @see sys_random(), sys_getentropy()
+ */
 sysret_t sys_getrandom(void *buf, size_t buflen, unsigned int flags)
 {
     int ret = -1;
@@ -4971,10 +8465,27 @@ sysret_t sys_getrandom(void *buf, size_t buflen, unsigned int flags)
 }
 
 /**
- *  readlink() places the contents of the symbolic link pathname in the buffer buf, which has size bufsiz.
- *  readlink() does not append a null byte to buf.
- *  It will (silently) truncate the contents(to a length of bufsiz characters),
- *  in case the buffer is too small to hold all of the contents.
+ * @brief Read the value of a symbolic link.
+ *
+ * This function reads the value of a symbolic link and stores it in the provided buffer. The value is the
+ * path to which the symbolic link points. If the symbolic link is too long to fit in the provided buffer,
+ * the function returns the number of bytes needed to store the entire path (not including the terminating null byte).
+ *
+ * @param[in]  path   The path of the symbolic link to read.
+ * @param[out] buf    A buffer where the symbolic link's target will be stored. The buffer must be large enough
+ *                    to hold the path of the symbolic link.
+ * @param[in]  bufsz  The size of the buffer `buf`. It specifies the maximum number of bytes to read.
+ *
+ * @return ssize_t The number of bytes written to `buf` (excluding the terminating null byte) on success.
+ *                 On failure, it returns a negative error code:
+ *                 - `-EINVAL`: Invalid path.
+ *                 - `-ENOMEM`: Insufficient memory to read the link.
+ *                 - `-EFAULT`: Invalid address for the `buf`.
+ *
+ * @note It will (silently) truncate the contents(to a length of bufsiz characters),
+ *       in case the buffer is too small to hold all of the contents.
+ *
+ * @see sys_symlink(), sys_lstat()
  */
 ssize_t sys_readlink(char* path, char *buf, size_t bufsz)
 {
@@ -5026,6 +8537,26 @@ ssize_t sys_readlink(char* path, char *buf, size_t bufsz)
     return rtn;
 }
 
+/**
+ * @brief Set the CPU affinity mask of a process.
+ *
+ * This function sets the CPU affinity mask for a specified process. The affinity mask determines which CPUs the
+ * process is allowed to execute on. The process will be restricted to the CPUs specified in the mask.
+ *
+ * @param[in] pid     The process ID of the process whose CPU affinity is to be set. If the `pid` is `0`, the
+ *                    affinity of the calling process will be modified.
+ * @param[in] size    The size (in bytes) of the CPU set, typically `sizeof(cpu_set_t)`.
+ * @param[in] set     A pointer to the CPU set. The CPU set is a bitmask representing which CPUs the process
+ *                    is allowed to run on. The bitmask must have enough bits to cover the number of CPUs on the system.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The CPU set is represented as a bitmask where each bit corresponds to a CPU. If the bit is set, the process
+ *       can execute on that CPU. The number of CPUs is platform-dependent, and the size of `set` must be large enough
+ *       to hold a bit for each CPU.
+ *
+ * @see sys_sched_getaffinity(), sys_setcpu()
+ */
 sysret_t sys_sched_setaffinity(pid_t pid, size_t size, void *set)
 {
     void *kset = RT_NULL;
@@ -5069,6 +8600,26 @@ sysret_t sys_sched_setaffinity(pid_t pid, size_t size, void *set)
     return -1;
 }
 
+/**
+ * @brief Get the CPU affinity mask of a process.
+ *
+ * This function retrieves the CPU affinity mask for a specified process. The affinity mask indicates which CPUs the
+ * process is allowed to execute on. The process can run on any of the CPUs represented by the bits set in the mask.
+ *
+ * @param[in]  pid    The process ID of the process whose CPU affinity is to be retrieved. If `pid` is `0`, the
+ *                    affinity mask of the calling process will be retrieved.
+ * @param[in]  size   The size (in bytes) of the CPU set, typically `sizeof(cpu_set_t)`.
+ * @param[out] set    A pointer to a buffer where the CPU affinity mask will be stored. The mask is represented
+ *                    as a bitmask, where each bit corresponds to a CPU. The bit is set if the process can run on that CPU.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The CPU set is represented as a bitmask where each bit corresponds to a CPU. If the bit is set, the process
+ *       can execute on that CPU. The number of CPUs is platform-dependent, and the size of `set` must be large enough
+ *       to hold a bit for each CPU.
+ *
+ * @see sys_sched_setaffinity(), sys_getcpu()
+ */
 sysret_t sys_sched_getaffinity(const pid_t pid, size_t size, void *set)
 {
 #ifdef ARCH_MM_MMU
@@ -5134,6 +8685,21 @@ sysret_t sys_sched_getaffinity(const pid_t pid, size_t size, void *set)
 #endif
 }
 
+/**
+ * @brief Retrieve system information.
+ *
+ * This function provides details about the current state of the system, such as uptime, memory usage,
+ * load average, and other key statistics. The information is stored in a structure pointed to by `info`.
+ *
+ * @param[out] info A pointer to a buffer where system information will be stored. The structure should
+ *                  be compatible with the format expected by the system, typically `struct sysinfo`.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The structure of `info` must be predefined and consistent with the system's expectations.
+ *       This function does not allocate memory for `info`; the caller must provide sufficient
+ *       memory for the structure.
+ */
 sysret_t sys_sysinfo(void *info)
 {
 #ifdef ARCH_MM_MMU
@@ -5180,6 +8746,22 @@ sysret_t sys_sysinfo(void *info)
 #endif
 }
 
+/**
+ * @brief Set scheduling parameters for a specific thread.
+ *
+ * This function allows setting the scheduling parameters for a thread identified by its thread ID (`tid`).
+ * The parameters are provided via the `param` argument, which should be a structure compatible with the
+ * system's scheduling policies.
+ *
+ * @param[in] tid The thread ID of the target thread for which the scheduling parameters are to be set.
+ * @param[in] param A pointer to a structure containing the new scheduling parameters. The structure
+ *                  typically includes fields like priority and policy.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The caller must have appropriate permissions to change the scheduling parameters of the specified thread.
+ *       The exact structure and fields of `param` depend on the system's implementation and scheduling policies.
+ */
 sysret_t sys_sched_setparam(pid_t tid, void *param)
 {
     struct sched_param *sched_param = RT_NULL;
@@ -5217,12 +8799,39 @@ sysret_t sys_sched_setparam(pid_t tid, void *param)
     return ret;
 }
 
+/**
+ * @brief Relinquish the processor voluntarily.
+ *
+ * This function causes the calling thread to yield the processor, allowing other threads
+ * that are ready to run to execute. The thread will be placed back into the scheduler's
+ * ready queue and may be rescheduled according to its priority and the system's scheduling policy.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function is typically used in cooperative multitasking scenarios or when a thread
+ *       explicitly determines it no longer needs the processor at the moment.
+ */
 sysret_t sys_sched_yield(void)
 {
     rt_thread_yield();
     return 0;
 }
 
+/**
+ * @brief Retrieve the scheduling parameters of a specific thread.
+ *
+ * This function retrieves the scheduling parameters of the thread identified by the thread ID (`tid`).
+ * The retrieved parameters are stored in the structure pointed to by the `param` argument.
+ *
+ * @param[in]  tid   The thread ID of the target thread whose scheduling parameters are to be retrieved.
+ * @param[out] param A pointer to a structure where the scheduling parameters will be stored. The structure
+ *                   typically includes fields like priority and policy.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The caller must have appropriate permissions to query the scheduling parameters of the specified thread.
+ *       The exact structure and fields of `param` depend on the system's implementation and scheduling policies.
+ */
 sysret_t sys_sched_getparam(const pid_t tid, void *param)
 {
     struct sched_param *sched_param = RT_NULL;
@@ -5256,6 +8865,21 @@ sysret_t sys_sched_getparam(const pid_t tid, void *param)
     return ret;
 }
 
+/**
+ * @brief Get the maximum priority for a given scheduling policy.
+ *
+ * This function retrieves the maximum priority value that can be used with the specified
+ * scheduling policy.
+ *
+ * @param[in] policy The scheduling policy for which to retrieve the maximum priority.
+ *
+ * @return sysret_t Returns the maximum priority value on success. On failure, returns a
+ *                  negative error code.
+ *
+ * @note The valid priority range depends on the system's configuration and the selected
+ *       scheduling policy. The returned value represents the highest priority that can
+ *       be assigned to a thread using the given policy.
+ */
 sysret_t sys_sched_get_priority_max(int policy)
 {
     if(policy < 0)
@@ -5266,6 +8890,21 @@ sysret_t sys_sched_get_priority_max(int policy)
     return RT_THREAD_PRIORITY_MAX;
 }
 
+/**
+ * @brief Get the minimum priority for a given scheduling policy.
+ *
+ * This function retrieves the minimum priority value that can be used with the specified
+ * scheduling policy.
+ *
+ * @param[in] policy The scheduling policy for which to retrieve the minimum priority.
+ *
+ * @return sysret_t Returns the minimum priority value on success. On failure, returns a
+ *                  negative error code.
+ *
+ * @note The valid priority range depends on the system's configuration and the selected
+ *       scheduling policy. The returned value represents the lowest priority that can
+ *       be assigned to a thread using the given policy.
+ */
 sysret_t sys_sched_get_priority_min(int policy)
 {
     if(policy < 0)
@@ -5276,6 +8915,26 @@ sysret_t sys_sched_get_priority_min(int policy)
     return 0;
 }
 
+/**
+ * @brief Set the scheduling policy and parameters for a thread.
+ *
+ * This function sets the scheduling policy and associated parameters for the specified thread.
+ * It allows controlling the scheduling behavior of threads.
+ *
+ * @param[in] tid    The thread ID of the target thread.
+ * @param[in] policy The scheduling policy to be applied. Common values include:
+ *                   - `SCHED_FIFO`: First-in, first-out scheduling.
+ *                   - `SCHED_RR`: Round-robin scheduling.
+ *                   - `SCHED_OTHER`: Default or standard scheduling.
+ * @param[in] param  Pointer to a structure containing scheduling parameters, such as priority.
+ *                   The structure type depends on the system implementation.
+ *
+ * @return sysret_t Returns 0 on success. On failure, returns a negative error code.
+ *
+ * @note This function requires appropriate permissions to modify the scheduling settings
+ *       of another thread. For most systems, elevated privileges may be required.
+ *       Ensure the `param` structure is properly initialized for the given `policy`.
+ */
 sysret_t sys_sched_setscheduler(int tid, int policy, void *param)
 {
     sysret_t ret;
@@ -5308,6 +8967,19 @@ sysret_t sys_sched_setscheduler(int tid, int policy, void *param)
     return ret;
 }
 
+/**
+ * @brief Get the scheduling policy of a thread.
+ *
+ * This function retrieves the current scheduling policy of the specified thread.
+ *
+ * @param[in] tid The thread ID of the target thread.
+ *
+ * @return sysret_t Returns the scheduling policy of the thread on success. On failure,
+ *                  returns a negative error code.
+ *
+ * @note The caller must have appropriate permissions to query the scheduling policy
+ *       of the specified thread.
+ */
 sysret_t sys_sched_getscheduler(int tid)
 {
     rt_thread_t thread = RT_NULL;
@@ -5328,6 +9000,23 @@ sysret_t sys_sched_getscheduler(int tid)
     return rtn;
 }
 
+/**
+ * @brief Flush the file descriptors' data to disk.
+ *
+ * This function flushes all modified data of the file associated with the specified
+ * file descriptor to disk, ensuring that any changes made to the file are committed
+ * to permanent storage.
+ *
+ * @param[in] fd The file descriptor associated with the file to be flushed. It should
+ *               refer to an open file.
+ *
+ * @return sysret_t Returns `0` (0) on success. On failure, returns a negative
+ *                  error code.
+ *
+ * @note The `fsync` function ensures that all data written to the file is physically
+ *       stored on disk, but it does not guarantee that all file metadata is flushed.
+ *       To flush both data and metadata, `fdatasync` can be used.
+ */
 sysret_t sys_fsync(int fd)
 {
     int res = fsync(fd);
@@ -5336,6 +9025,35 @@ sysret_t sys_fsync(int fd)
     return res;
 }
 
+/**
+ * @brief Open a message queue.
+ *
+ * This function opens a message queue for communication between processes.
+ * It can create a new message queue or open an existing one, depending on the specified
+ * flags.
+ *
+ * @param[in] name  The name of the message queue. The name should be a null-terminated
+ *                  string and is subject to system-specific naming conventions.
+ * @param[in] flags Flags that control the behavior of the message queue. Common flags include:
+ *                  - `O_CREAT`: Create the message queue if it does not exist.
+ *                  - `O_EXCL`: Fail if the message queue already exists.
+ *                  - `O_RDONLY`: Open the queue for reading.
+ *                  - `O_WRONLY`: Open the queue for writing.
+ *                  - `O_RDWR`: Open the queue for both reading and writing.
+ * @param[in] mode  The mode to be applied when creating the message queue, which defines
+ *                  the permissions for the message queue (e.g., read, write).
+ * @param[in] attr  A pointer to a `struct mq_attr` that defines the attributes of the
+ *                  message queue, such as the maximum number of messages and the size of
+ *                  each message. If `NULL`, default values are used.
+ *
+ * @return mqd_t Returns a non-negative file descriptor for the message queue on success.
+ *               On failure, returns `-1` and sets `errno` to indicate the error.
+ *
+ * @note If the message queue is created, its attributes (such as the maximum number of
+ *       messages and message size) must be defined in the `mq_attr` structure. If the
+ *       `O_CREAT` flag is not specified and the queue does not exist, the function will
+ *       return `-1`.
+ */
 mqd_t sys_mq_open(const char *name, int flags, mode_t mode, struct mq_attr *attr)
 {
     mqd_t mqdes;
@@ -5383,6 +9101,24 @@ mqd_t sys_mq_open(const char *name, int flags, mode_t mode, struct mq_attr *attr
         return mqdes;
 }
 
+/**
+ * @brief Remove a message queue.
+ *
+ * This function removes a message queue identified by its name. If the message queue
+ * is open by any process, it will be removed only when all the processes close their
+ * file descriptors associated with the message queue.
+ *
+ * @param[in] name The name of the message queue to be removed. It should be a null-terminated
+ *                 string that conforms to system-specific naming conventions.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative
+ *                  error code.
+ *
+ * @note After a successful call, the message queue is removed from the system. However,
+ *       the removal will not take effect until all processes close their file descriptors
+ *       associated with the queue. The function will fail if the message queue is still
+ *       open by other processes.
+ */
 sysret_t sys_mq_unlink(const char *name)
 {
     int ret = 0;
@@ -5411,6 +9147,32 @@ sysret_t sys_mq_unlink(const char *name)
 #endif
 }
 
+/**
+ * @brief Send a message to a message queue with a timeout.
+ *
+ * This function sends a message to the specified message queue, but it allows the sender
+ * to specify a timeout. If the message queue is full, the function will block until either
+ * space becomes available or the specified timeout expires. If the timeout expires without
+ * space being available, the function returns an error.
+ *
+ * @param[in] mqd   The message queue descriptor returned by `sys_mq_open`.
+ * @param[in] msg   A pointer to the message to be sent.
+ * @param[in] len   The length of the message to send.
+ * @param[in] prio  The priority of the message (higher values indicate higher priority).
+ * @param[in] at    A pointer to a `timespec` structure that specifies the absolute timeout.
+ *                  If the timeout expires before the message can be sent, the function returns
+ *                  an error.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error
+ *                  code.
+ *
+ * @note The function uses the `timespec` structure to specify the absolute timeout. The
+ *       `at` parameter should indicate the time at which the operation should time out.
+ *       If the timeout is `NULL`, the function will not apply any timeout (it will block
+ *       indefinitely until the message is sent).
+ *
+ * @see sys_mq_send
+ */
 sysret_t sys_mq_timedsend(mqd_t mqd, const char *msg, size_t len, unsigned prio, const struct timespec *at)
 {
     int ret = 0;
@@ -5439,6 +9201,32 @@ sysret_t sys_mq_timedsend(mqd_t mqd, const char *msg, size_t len, unsigned prio,
 #endif
 }
 
+/**
+ * @brief Receive a message from a message queue with a timeout.
+ *
+ * This function attempts to receive a message from the specified message queue, but it
+ * allows the receiver to specify a timeout. If the queue is empty, the function will block
+ * until either a message becomes available or the specified timeout expires. If the timeout
+ * expires without receiving a message, the function returns an error.
+ *
+ * @param[in] mqd    The message queue descriptor returned by `sys_mq_open`.
+ * @param[out] msg   A pointer to the buffer where the received message will be stored.
+ * @param[in] len    The maximum length of the buffer to store the received message.
+ * @param[out] prio  A pointer to an unsigned integer that will be set to the priority
+ *                   of the received message.
+ * @param[in] at     A pointer to a `timespec` structure that specifies the absolute timeout.
+ *                   If the timeout expires before a message is received, the function will
+ *                   return an error.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The function uses the `timespec` structure to specify the absolute timeout. The
+ *       `at` parameter should indicate the time at which the operation should time out.
+ *       If the timeout is `NULL`, the function will block indefinitely until a message is
+ *       received.
+ *
+ * @see sys_mq_receive
+ */
 sysret_t sys_mq_timedreceive(mqd_t mqd, char *restrict msg, size_t len, unsigned *restrict prio, const struct timespec *restrict at)
 {
     int ret = 0;
@@ -5480,6 +9268,27 @@ sysret_t sys_mq_timedreceive(mqd_t mqd, char *restrict msg, size_t len, unsigned
 #endif
 }
 
+/**
+ * @brief Set up asynchronous notification for a message queue.
+ *
+ * This function configures asynchronous notification for a message queue. When a message
+ * is available in the queue, the system can notify the calling process through a signal
+ * or another method specified in the `sigevent` structure. This is typically used to allow
+ * a process to be notified when a message arrives without having to block in the receive call.
+ *
+ * @param[in] mqd  The message queue descriptor returned by `sys_mq_open`.
+ * @param[in] sev  A pointer to a `sigevent` structure that specifies the notification
+ *                 mechanism to be used when a message is received. It could include
+ *                 signals or other notification types such as event flags or message passing.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function enables asynchronous notification, but the specific behavior depends
+ *       on the configuration specified in the `sev` parameter, which could involve signals
+ *       or other forms of notification.
+ *
+ * @see sys_mq_send, sys_mq_timedreceive
+ */
 sysret_t sys_mq_notify(mqd_t mqd, const struct sigevent *sev)
 {
     int ret = 0;
@@ -5493,6 +9302,29 @@ sysret_t sys_mq_notify(mqd_t mqd, const struct sigevent *sev)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Get or set attributes of a message queue.
+ *
+ * This function allows you to get or set the attributes of an existing message queue.
+ * If the `new` attribute structure is non-NULL, it updates the message queue with the new
+ * attributes. Otherwise, If the `old` attribute structure is non-NULL, it will return the current
+ * attributes of the message queue.
+ *
+ * @param[in] mqd  The message queue descriptor returned by `sys_mq_open`.
+ * @param[in] new  A pointer to a `mq_attr` structure containing the new attributes to set.
+ *                 If `NULL`, the function will not modify the message queue attributes.
+ * @param[out] old A pointer to a `mq_attr` structure where the current message queue
+ *                 attributes will be returned. If `NULL`, the current attributes will not
+ *                 be returned.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The `mq_attr` structure contains parameters like the maximum number of messages,
+ *       the maximum message size, and other attributes that control the behavior of the
+ *       message queue.
+ *
+ * @see sys_mq_open, sys_mq_notify
+ */
 sysret_t sys_mq_getsetattr(mqd_t mqd, const struct mq_attr *restrict new, struct mq_attr *restrict old)
 {
     int ret = 0;
@@ -5538,6 +9370,22 @@ sysret_t sys_mq_getsetattr(mqd_t mqd, const struct mq_attr *restrict new, struct
 #endif
 }
 
+/**
+ * @brief Close a message queue descriptor.
+ *
+ * This function closes a message queue descriptor. After calling this function, the
+ * descriptor can no longer be used to interact with the message queue. Any resources
+ * associated with the descriptor are released. If the message queue was opened with the
+ * `O_CLOEXEC` flag, it will be automatically closed when the calling process executes
+ * an `exec` system call.
+ *
+ * @param[in] mqd  The message queue descriptor to be closed. It was previously returned
+ *                 by `sys_mq_open`.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @see sys_mq_open, sys_mq_unlink
+ */
 sysret_t sys_mq_close(mqd_t mqd)
 {
     int ret = 0;
@@ -5553,6 +9401,26 @@ sysret_t sys_mq_close(mqd_t mqd)
 #define DCACHE (1<<1)
 #define BCACHE (ICACHE|DCACHE)
 
+/**
+ * @brief Flush the cache for a specified memory region.
+ *
+ * This function flushes the cache for a specified memory region. It is commonly used
+ * to ensure that the contents of a memory region are written back to the main memory
+ * or that stale cache entries are invalidated. The cache operation can be controlled
+ * by the `cache` parameter to determine whether to clean or invalidate the cache.
+ *
+ * @param[in] addr   The starting address of the memory region to flush.
+ * @param[in] size   The size of the memory region to flush, in bytes.
+ * @param[in] cache  A flag to specify the cache operation:
+ *                   - `CACHE_CLEAN`: Clean the cache (write back to memory).
+ *                   - `CACHE_INVALIDATE`: Invalidate the cache (discard cached data).
+ *                   - `CACHE_FLUSH`: Both clean and invalidate the cache.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function is typically used in low-level operations or in systems where
+ *       cache coherence between memory and cache is critical.
+ */
 rt_weak sysret_t sys_cacheflush(void *addr, int size, int cache)
 {
     if (!lwp_user_accessable(addr, size))
@@ -5577,6 +9445,28 @@ rt_weak sysret_t sys_cacheflush(void *addr, int size, int cache)
     return -EFAULT;
 }
 
+/**
+ * @brief Get system information.
+ *
+ * This function retrieves information about the current system, such as the system name,
+ * version, release, architecture, and other details. The information is stored in the
+ * `utsname` structure pointed to by the `uts` parameter.
+ *
+ * @param[out] uts  A pointer to a `utsname` structure where the system information will
+ *                  be stored. The structure includes fields such as:
+ *                  - `sysname`: Operating system name.
+ *                  - `nodename`: Network node hostname.
+ *                  - `release`: Operating system release version.
+ *                  - `version`: Operating system version.
+ *                  - `machine`: Hardware identifier (architecture).
+ *
+ * @return sysret_t Returns `SYSRET_OK` (0) on success. On failure, returns a negative error code.
+ *
+ * @note This function provides details about the system environment, which may be useful
+ *       for applications needing to adapt to different system configurations.
+ *
+ * @see sys_gethostname, sys_uname
+ */
 sysret_t sys_uname(struct utsname *uts)
 {
     struct utsname utsbuff = {0};
@@ -5591,12 +9481,14 @@ sysret_t sys_uname(struct utsname *uts)
     utsbuff.nodename[0] = '\0';
     ret = rt_snprintf(utsbuff.release, sizeof(utsbuff.release), "%u.%u.%u",
                       RT_VERSION_MAJOR, RT_VERSION_MINOR, RT_VERSION_PATCH);
-    if (ret < 0) {
+    if (ret < 0)
+    {
         return -EIO;
     }
     ret = rt_snprintf(utsbuff.version, sizeof(utsbuff.version), "RT-Thread %u.%u.%u %s %s",
                       RT_VERSION_MAJOR, RT_VERSION_MINOR, RT_VERSION_PATCH, __DATE__, __TIME__);
-    if (ret < 0) {
+    if (ret < 0)
+    {
         return -EIO;
     }
 
@@ -5608,6 +9500,35 @@ sysret_t sys_uname(struct utsname *uts)
     return 0;
 }
 
+/**
+ * @brief Get filesystem statistics.
+ *
+ * This function retrieves statistics about the filesystem at the specified path,
+ * storing the results in the provided `statfs` structure. It can be used to obtain
+ * information such as the total number of blocks, free blocks, available inodes, etc.
+ *
+ * @param[in]  path  The path to the filesystem to query. If the path is the root directory
+ *                   (`"/"`), it returns statistics for the root filesystem.
+ * @param[out] buf   A pointer to a `statfs` structure where the filesystem statistics will
+ *                   be stored. This structure includes information such as:
+ *                   - `f_type`: The type of the filesystem.
+ *                   - `f_bsize`: The optimal block size for I/O operations.
+ *                   - `f_blocks`: Total number of blocks in the filesystem.
+ *                   - `f_bfree`: Number of free blocks.
+ *                   - `f_bavail`: Number of free blocks available to non-superuser.
+ *                   - `f_files`: Total number of file nodes (inodes).
+ *                   - `f_ffree`: Number of free inodes.
+ *                   - `f_favail`: Number of inodes available to non-superuser.
+ *                   - `f_flag`: Flags describing the filesystem.
+ *                   - `f_namelen`: Maximum length of a filename.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function is useful for determining the available space and file system
+ *       characteristics of a mounted filesystem.
+ *
+ * @see sys_fstatfs
+ */
 sysret_t sys_statfs(const char *path, struct statfs *buf)
 {
     int ret = 0;
@@ -5652,6 +9573,32 @@ sysret_t sys_statfs(const char *path, struct statfs *buf)
     return ret;
 }
 
+/**
+ * @brief Get extended filesystem statistics (64-bit).
+ *
+ * This function retrieves extended statistics about the filesystem at the specified path,
+ * using 64-bit values for larger filesystems or filesystems with a large number of blocks or inodes.
+ * The information is stored in the provided `statfs` structure, which includes details such as total
+ * blocks, free blocks, available inodes, etc.
+ *
+ * @param[in]  path  The path to the filesystem to query. Typically, this would be the root directory
+ *                   (`"/"`) for the root filesystem, or any other directory on the filesystem.
+ * @param[in]  sz    The size of the `statfs` structure. This parameter allows for future extensions
+ *                   of the `statfs` structure without breaking compatibility with older applications.
+ * @param[out] buf   A pointer to a `statfs` structure where the extended filesystem statistics
+ *                   will be stored. This structure includes information such as:
+ *                   - `f_bsize`: The optimal block size for I/O operations.
+ *                   - `f_blocks`: Total number of blocks in the filesystem.
+ *                   - `f_bfree`: Number of free blocks.
+ *                   - `f_bavail`: Number of free blocks available to non-superuser.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function is particularly useful for querying large filesystems or filesystems with
+ *       64-bit addresses or data values, and is an extended version of the standard `sys_statfs`.
+ *
+ * @see sys_statfs
+ */
 sysret_t sys_statfs64(const char *path, size_t sz, struct statfs *buf)
 {
     int ret = 0;
@@ -5665,7 +9612,8 @@ sysret_t sys_statfs64(const char *path, size_t sz, struct statfs *buf)
         return -EFAULT;
     }
 
-    if (sz != sizeof(struct statfs)) {
+    if (sz != sizeof(struct statfs))
+    {
         return -EINVAL;
     }
 
@@ -5700,6 +9648,30 @@ sysret_t sys_statfs64(const char *path, size_t sz, struct statfs *buf)
     return ret;
 }
 
+/**
+ * @brief Get filesystem statistics for a file descriptor.
+ *
+ * This function retrieves statistics about the filesystem containing the file referred to by the
+ * file descriptor `fd`. The information is stored in the provided `statfs` structure, which includes
+ * details such as total blocks, free blocks, available inodes, etc.
+ *
+ * @param[in]  fd    The file descriptor referring to an open file. The file descriptor must be
+ *                   valid and represent a file on a mounted filesystem.
+ * @param[out] buf   A pointer to a `statfs` structure where the filesystem statistics will be
+ *                   stored. This structure includes information such as:
+ *                   - `f_bsize`: The optimal block size for I/O operations.
+ *                   - `f_blocks`: Total number of blocks in the filesystem.
+ *                   - `f_bfree`: Number of free blocks.
+ *                   - `f_bavail`: Number of free blocks available to non-superuser.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note This function is useful for obtaining filesystem information about a specific file
+ *       represented by its file descriptor, rather than querying the filesystem associated with
+ *       a specific path.
+ *
+ * @see sys_statfs
+ */
 sysret_t sys_fstatfs(int fd, struct statfs *buf)
 {
     int ret = 0;
@@ -5720,6 +9692,32 @@ sysret_t sys_fstatfs(int fd, struct statfs *buf)
     return ret;
 }
 
+/**
+ * @brief Get 64-bit filesystem statistics for a file descriptor.
+ *
+ * This function retrieves 64-bit statistics about the filesystem containing the file referred to by
+ * the file descriptor `fd`. The statistics are stored in the provided `statfs` structure, which
+ * includes details such as total blocks, free blocks, available inodes, etc. The function differs
+ * from `sys_fstatfs` in that it supports 64-bit values for filesystem sizes and counts.
+ *
+ * @param[in]  fd    The file descriptor referring to an open file. The file descriptor must be
+ *                   valid and represent a file on a mounted filesystem.
+ * @param[in]  sz    The size of the `statfs` structure (typically used to ensure compatibility with
+ *                   different versions of the structure).
+ * @param[out] buf   A pointer to a `statfs` structure where the filesystem statistics will be
+ *                   stored. This structure includes information such as:
+ *                   - `f_bsize`: The optimal block size for I/O operations.
+ *                   - `f_blocks`: Total number of blocks in the filesystem (64-bit).
+ *                   - `f_bfree`: Number of free blocks (64-bit).
+ *                   - `f_bavail`: Number of free blocks available to non-superuser (64-bit).
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ * @note This function is particularly useful for systems supporting 64-bit filesystem statistics.
+ *       It provides extended accuracy for large filesystems, including those with very large
+ *       numbers of blocks or inodes.
+ *
+ * @see sys_fstatfs
+ */
 sysret_t sys_fstatfs64(int fd, size_t sz, struct statfs *buf)
 {
     int ret = 0;
@@ -5730,7 +9728,8 @@ sysret_t sys_fstatfs64(int fd, size_t sz, struct statfs *buf)
         return -EFAULT;
     }
 
-    if (sz != sizeof(struct statfs)) {
+    if (sz != sizeof(struct statfs))
+    {
         return -EINVAL;
     }
 
@@ -5761,6 +9760,30 @@ static char *_cp_from_usr_string(char *dst, char *src, size_t length)
     return rc;
 }
 
+/**
+ * @brief Mount a filesystem.
+ *
+ * This function mounts a filesystem onto a specified directory. It allows for mounting various
+ * types of filesystems, including but not limited to `ext4`, `nfs`, and `tmpfs`. The function
+ * allows the specification of the source device, the target mount point, and additional parameters
+ * such as filesystem type, mount flags, and extra data.
+ *
+ * @param[in]  source        The source of the filesystem, which can be a device (e.g., `/dev/sda1`)
+ *                           or a network resource (e.g., a NFS share). For certain filesystems like
+ *                           `tmpfs`, this can be `NULL`.
+ * @param[in]  target        The target directory where the filesystem will be mounted.
+ *                           This should be an existing empty directory.
+ * @param[in]  filesystemtype The type of filesystem to mount, e.g., `ext4`, `tmpfs`, `nfs`, etc.
+ * @param[in]  mountflags    Flags that control the mount operation, such as `MS_RDONLY` for read-only
+ *                           mounts or `MS_NODEV` to prevent device files from being created.
+ * @param[in]  data          Optional data that is passed to the filesystem's mount handler. This
+ *                           may be used for setting up specific parameters for the filesystem type.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note Mounting a filesystem on an existing mount point can replace the existing filesystem at that
+ *       location. Make sure the target directory is empty before mounting to avoid any conflicts.
+ */
 sysret_t sys_mount(char *source, char *target, char *filesystemtype,
                    unsigned long mountflags, void *data)
 {
@@ -5835,6 +9858,27 @@ sysret_t sys_mount(char *source, char *target, char *filesystemtype,
     return ret;
 }
 
+/**
+ * @brief Unmount a filesystem.
+ *
+ * This function unmounts a previously mounted filesystem from a specified target directory or file.
+ * It removes the filesystem from the system, making the resources associated with it available for
+ * other uses. It can also support additional flags to control the unmounting behavior.
+ *
+ * @param[in]  __special_file The target directory or mount point from which the filesystem is to be
+ *                            unmounted. This should be a valid mount point that was previously mounted.
+ * @param[in]  __flags        Flags that control the unmounting behavior. Common flags include:
+ *                            - `MNT_FORCE`: Forces the unmount even if the filesystem is busy.
+ *                            - `MNT_DETACH`: Detaches the filesystem, allowing it to be unmounted
+ *                              asynchronously.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note The `MNT_FORCE` flag should be used with caution, as it may result in data loss or corruption
+ *       if there are pending writes or active processes using the filesystem.
+ *
+ * @see sys_mount
+ */
 sysret_t sys_umount2(char *__special_file, int __flags)
 {
     char *copy_special_file;
@@ -5862,6 +9906,24 @@ sysret_t sys_umount2(char *__special_file, int __flags)
     return ret;
 }
 
+/**
+ * @brief Create a new hard link to an existing file.
+ *
+ * This function creates a new hard link to an existing file, making the file accessible from
+ * multiple filenames. The new link points to the same inode as the existing file, meaning
+ * both names refer to the same underlying data. The link count for the file is incremented.
+ *
+ * @param[in]  existing The path to the existing file. It must be an absolute or relative path
+ *                      to a file that already exists.
+ * @param[in]  new      The path to the new link to be created. This can be a new filename or
+ *                      an existing directory where the link will be placed.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note Hard links share the same inode number, meaning changes to the data of the file via one
+ *       link will be reflected in all hard links. Deleting any of the links will not remove the
+ *       file data until all links are deleted.
+ */
 sysret_t sys_link(const char *existing, const char *new)
 {
     int ret = -1;
@@ -5930,6 +9992,26 @@ sysret_t sys_link(const char *existing, const char *new)
     return (err < 0 ? err : ret);
 }
 
+/**
+ * @brief Create a symbolic link to an existing file or directory.
+ *
+ * This function creates a new symbolic link, which is a special file that contains a reference
+ * to another file or directory. The symbolic link allows for easy redirection or aliasing of
+ * file paths. Unlike a hard link, a symbolic link can point to a file or directory across
+ * different file systems.
+ *
+ * @param[in]  existing The path to the existing file or directory that the symbolic link
+ *                      will refer to. It must be an absolute or relative path.
+ * @param[in]  new      The path to the new symbolic link to be created. This must be a valid
+ *                      path where the link will be placed.
+ *
+ * @return sysret_t Returns `0` on success. On failure, returns a negative error code.
+ *
+ * @note A symbolic link is distinct from a hard link in that it points to the path of the target
+ *       file or directory, rather than directly to the inode. If the target file or directory is
+ *       removed or moved, the symbolic link will become "broken" and will not resolve to a valid
+ *       location.
+ */
 sysret_t sys_symlink(const char *existing, const char *new)
 {
     int ret = -1;
@@ -5960,6 +10042,27 @@ sysret_t sys_symlink(const char *existing, const char *new)
     return (err < 0 ? err : ret);
 }
 
+/**
+ * @brief Create an event file descriptor.
+ *
+ * This function creates an eventfd, which is a file descriptor used for event notification.
+ * Eventfd is a simple mechanism to notify threads or processes about certain events using
+ * an integer counter. It is typically used for inter-process communication (IPC) or
+ * synchronization purposes, where one thread or process increments the counter to signal
+ * another thread or process.
+ *
+ * @param[in] count  Initial value for the eventfd counter. It can be set to a non-zero
+ *                   value to initialize the counter to that value.
+ * @param[in] flags  Flags that control the behavior of the eventfd. Valid flags include:
+ *                   - `EFD_CLOEXEC`: Set the close-on-exec flag for the eventfd.
+ *                   - `EFD_NONBLOCK`: Set the non-blocking flag for the eventfd.
+ *
+ * @return sysret_t On success, returns a valid file descriptor referring to the eventfd. On
+ *                  failure, returns a negative error code.
+ *
+ * @note Eventfd can be used for both counting and signaling purposes. It provides
+ *       efficient signaling between threads or processes.
+ */
 sysret_t sys_eventfd2(unsigned int count, int flags)
 {
     int ret;
@@ -5967,6 +10070,25 @@ sysret_t sys_eventfd2(unsigned int count, int flags)
     ret = eventfd(count, flags);
     return (ret < 0 ? GET_ERRNO() : ret);
 }
+
+/**
+ * @brief Create an epoll instance.
+ *
+ * This function creates an epoll instance, which is used for monitoring multiple file descriptors
+ * to see if I/O is possible on them. It allows a program to efficiently wait for events such as
+ * data being available for reading or space becoming available for writing. Epoll provides a scalable
+ * mechanism for managing large numbers of file descriptors.
+ *
+ * @param[in] flags  Flags that control the behavior of the epoll instance. The valid flags include:
+ *                   - `EPOLL_CLOEXEC`: Set the close-on-exec flag for the epoll instance.
+ *                   - `EPOLL_NONBLOCK`: Set the non-blocking flag for the epoll instance.
+ *
+ * @return sysret_t On success, returns a file descriptor for the epoll instance. On failure,
+ *                  returns a negative error code.
+ *
+ * @note The `sys_epoll_create1` function is similar to `sys_epoll_create`, but it allows for
+ *       additional control over the epoll instance creation via flags.
+ */
 sysret_t sys_epoll_create1(int flags)
 {
     int ret;
@@ -5976,6 +10098,25 @@ sysret_t sys_epoll_create1(int flags)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Control an epoll instance.
+ *
+ * This function performs control operations on an epoll instance, such as adding, modifying,
+ * or removing file descriptors from the epoll instance's interest list.
+ *
+ * @param[in] fd    The file descriptor of the epoll instance created using `sys_epoll_create` or `sys_epoll_create1`.
+ * @param[in] op    The operation to perform on the epoll instance. It can be one of the following:
+ *                  - `EPOLL_CTL_ADD`: Add the specified file descriptor to the epoll interest list.
+ *                  - `EPOLL_CTL_MOD`: Modify the event mask of an existing file descriptor in the epoll interest list.
+ *                  - `EPOLL_CTL_DEL`: Remove the specified file descriptor from the epoll interest list.
+ * @param[in] fd2   The file descriptor to be added, modified, or removed from the epoll interest list.
+ * @param[in] ev    A pointer to an `epoll_event` structure that describes the event to be associated with `fd2`.
+ *                  This parameter is required for `EPOLL_CTL_ADD` and `EPOLL_CTL_MOD`, but not for `EPOLL_CTL_DEL`.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note This function is typically used to manage the set of file descriptors monitored by an epoll instance.
+ */
 sysret_t sys_epoll_ctl(int fd, int op, int fd2, struct epoll_event *ev)
 {
     int ret = 0;
@@ -6010,6 +10151,27 @@ sysret_t sys_epoll_ctl(int fd, int op, int fd2, struct epoll_event *ev)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Wait for events on an epoll file descriptor, with the ability to block for specific signals.
+ *
+ * This function waits for events on an epoll file descriptor. It blocks until one or more events
+ * are available or a timeout occurs. In addition to waiting for events, it can also block for specific signals
+ * as specified by the `sigs` argument.
+ *
+ * @param[in] fd          The file descriptor of the epoll instance, created using `sys_epoll_create` or `sys_epoll_create1`.
+ * @param[out] ev         A pointer to an array of `epoll_event` structures that will receive the events that have occurred.
+ * @param[in] cnt         The maximum number of events to return. This specifies the size of the `ev` array.
+ * @param[in] to          The timeout in milliseconds. A negative value means no timeout, and `0` means non-blocking.
+ * @param[in] sigs        A pointer to a signal set (`sigset_t`) that specifies the signals to block during the wait.
+ *                        If `NULL`, no signals are blocked.
+ * @param[in] sigsetsize  The size of the signal set (`sigs`) in bytes. This should be the size of `sigset_t` if `sigs` is not `NULL`.
+ *
+ * @return sysret_t On success, returns the number of events returned (may be `0` if the timeout expires with no events).
+ *                  On failure, returns a negative error code.
+ *
+ * @note This function is similar to `sys_epoll_wait`, but it also allows for signal handling, blocking the calling thread
+ *       from receiving signals specified in the `sigs` set while waiting for events.
+ */
 sysret_t sys_epoll_pwait(int fd,
         struct epoll_event *ev,
         int cnt,
@@ -6068,6 +10230,20 @@ sysret_t sys_epoll_pwait(int fd,
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Truncate a file to a specified length.
+ *
+ * This function resizes the file associated with the given file descriptor `fd` to the specified length.
+ * If the current size of the file is greater than the specified length, the file is truncated. If the file is smaller,
+ * it is extended, and the new space is initialized to zero.
+ *
+ * @param[in] fd       The file descriptor referring to the file to truncate. This must be a valid open file descriptor.
+ * @param[in] length   The new length of the file. The file will be truncated or extended to this size.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note The file descriptor `fd` must be opened with write permissions for this operation to succeed.
+ */
 sysret_t sys_ftruncate(int fd, size_t length)
 {
     int ret;
@@ -6077,6 +10253,27 @@ sysret_t sys_ftruncate(int fd, size_t length)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Set file access and modification times.
+ *
+ * This function updates the access and modification times of a file or directory referenced by `__fd` or `__path`.
+ * If `__fd` is a valid file descriptor, the times will be applied to the file or directory it refers to.
+ * If `__fd` is `AT_FDCWD`, the times will be applied to the file or directory specified by `__path`.
+ * The `__times` argument consists of two `timespec` values: the first represents the access time,
+ * and the second represents the modification time. If `__times` is `NULL`, the current time is used.
+ *
+ * @param[in] __fd       The file descriptor of the file or directory to modify, or `AT_FDCWD` to modify using `__path`.
+ * @param[in] __path     The path to the file or directory to modify. Ignored if `__fd` is not `AT_FDCWD`.
+ * @param[in] __times    An array of two `timespec` structures. The first element is the access time, and the second is the modification time.
+ *                       If `__times` is `NULL`, the current time is used for both access and modification times.
+ * @param[in] __flags    Flags to modify behavior. Supported flags include:
+ *                       - `AT_SYMLINK_NOFOLLOW`: Do not follow symbolic links.
+ *                       - `AT_NO_AUTOMOUNT`: Do not trigger automounting.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note This function modifies both access and modification times of files, and may affect file system timestamps.
+ */
 sysret_t sys_utimensat(int __fd, const char *__path, const struct timespec __times[2], int __flags)
 {
 #ifdef RT_USING_DFS_V2
@@ -6116,6 +10313,22 @@ sysret_t sys_utimensat(int __fd, const char *__path, const struct timespec __tim
 #endif
 }
 
+/**
+ * @brief Change file permissions.
+ *
+ * This function changes the permissions of a file or directory specified by the `pathname`.
+ * The new permissions are specified using the `mode` argument, which is a bitwise OR of permission bits.
+ * The permissions apply to the file owner, group, and others, depending on the value of `mode`.
+ *
+ * @param[in] pathname  The path to the file or directory whose permissions are to be changed.
+ * @param[in] mode      The new permissions to set, represented as a bitwise OR of permission flags.
+ *                      For example, `S_IRUSR`, `S_IWUSR`, `S_IRGRP`, etc.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note If the file or directory is a symbolic link, this function will modify the permissions of the symbolic link itself,
+ *       not the target file or directory.
+ */
 sysret_t sys_chmod(const char *pathname, mode_t mode)
 {
     char *copy_file;
@@ -6147,6 +10360,22 @@ sysret_t sys_chmod(const char *pathname, mode_t mode)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Change the ownership of a file or directory.
+ *
+ * This function changes the owner and/or group of the file or directory specified by `pathname`.
+ * The `owner` and `group` parameters represent the new owner and group IDs, respectively. If either
+ * parameter is set to `-1`, that aspect (owner or group) will remain unchanged.
+ *
+ * @param[in] pathname  The path to the file or directory whose ownership is to be changed.
+ * @param[in] owner     The new owner ID. If set to `-1`, the owner's ID is not changed.
+ * @param[in] group     The new group ID. If set to `-1`, the group's ID is not changed.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note The caller must have the appropriate permissions (i.e., be the superuser or the file owner)
+ *       to change the ownership of a file or directory.
+ */
 sysret_t sys_chown(const char *pathname, uid_t owner, gid_t group)
 {
     char *copy_file;
@@ -6195,6 +10424,28 @@ sysret_t lwp_teardown(struct rt_lwp *lwp, void (*cb)(void))
 }
 #endif
 
+/**
+ * @brief Reboot the system.
+ *
+ * This function initiates a system reboot with a specific reboot type and optional arguments.
+ * The reboot process is performed by passing `magic` and `magic2` as security keys to validate the
+ * reboot request, along with the desired reboot type (`type`) and optional argument (`arg`) that
+ * may contain additional parameters depending on the reboot type.
+ *
+ * @param[in] magic   A magic number for security validation, typically used to verify that the caller
+ *                    has sufficient privileges (e.g., root).
+ * @param[in] magic2  A second magic number for additional security verification, used in combination
+ *                    with `magic` to validate the reboot request.
+ * @param[in] type    The type of reboot to perform, such as `RB_AUTOBOOT`, `RB_HALT`, `RB_RESTART`,
+ *                    etc. The exact values may depend on the platform.
+ * @param[in] arg     An optional argument for the reboot process. This can provide additional data,
+ *                    such as a specific shutdown procedure, depending on the type of reboot.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note This operation is typically available to the system administrator (root) and should be used
+ *       with caution as it can cause the system to restart or shut down.
+ */
 sysret_t sys_reboot(int magic, int magic2, int type, void *arg)
 {
     sysret_t rc;
@@ -6216,6 +10467,25 @@ sysret_t sys_reboot(int magic, int magic2, int type, void *arg)
     return rc;
 }
 
+/**
+ * @brief Read data from a file descriptor at a specific offset.
+ *
+ * This function reads data from a file descriptor `fd` into the buffer `buf`, starting from the
+ * specified byte `offset`. Unlike a regular `read` call, `sys_pread64` allows the file pointer to
+ * remain unchanged after the read, as the operation directly accesses the file at the provided
+ * offset.
+ *
+ * @param[in] fd      The file descriptor from which to read. It must be a valid open file descriptor.
+ * @param[out] buf    A pointer to the buffer where the read data will be stored.
+ * @param[in] size    The number of bytes to read from the file.
+ * @param[in] offset  The offset in bytes from the beginning of the file to start reading from.
+ *
+ * @return ssize_t On success, returns the number of bytes read (which may be less than `size` if
+ *                  the end of the file is reached). On error, returns a negative error code.
+ *
+ * @note This function is particularly useful for random access to files, allowing for efficient
+ *       reads from arbitrary positions without affecting the current file pointer.
+ */
 ssize_t sys_pread64(int fd, void *buf, int size, size_t offset)
 #ifdef RT_USING_DFS_V2
 {
@@ -6270,6 +10540,26 @@ ssize_t sys_pread64(int fd, void *buf, int size, size_t offset)
 }
 #endif
 
+/**
+ * @brief Write data to a file descriptor at a specific offset.
+ *
+ * This function writes data from the buffer `buf` to the file descriptor `fd`, starting at the
+ * specified byte `offset`. Unlike a regular `write` call, `sys_pwrite64` allows the file pointer to
+ * remain unchanged after the write, as the operation directly writes the data to the file at the
+ * provided offset.
+ *
+ * @param[in] fd      The file descriptor to which the data will be written. It must be a valid open
+ *                    file descriptor.
+ * @param[in] buf     A pointer to the buffer containing the data to be written.
+ * @param[in] size    The number of bytes to write to the file.
+ * @param[in] offset  The offset in bytes from the beginning of the file to start writing to.
+ *
+ * @return ssize_t On success, returns the number of bytes written (which may be less than `size` if
+ *                  the write operation is partial). On error, returns a negative error code.
+ *
+ * @note This function is particularly useful for random access to files, allowing for efficient
+ *       writes to arbitrary positions without affecting the current file pointer.
+ */
 ssize_t sys_pwrite64(int fd, void *buf, int size, size_t offset)
 #ifdef RT_USING_DFS_V2
 {
@@ -6321,6 +10611,29 @@ ssize_t sys_pwrite64(int fd, void *buf, int size, size_t offset)
 }
 #endif
 
+/**
+ * @brief Create a timer file descriptor.
+ *
+ * This function creates a timer that can be used to notify a process after a specified
+ * amount of time has passed. The timer is represented by a file descriptor, which can be
+ * used with functions such as `read` and `poll` to monitor and retrieve notifications
+ * about timer expirations.
+ *
+ * @param[in] clockid The clock to use for the timer. Possible values include:
+ *                    - `CLOCK_REALTIME`: The system's real-time clock.
+ *                    - `CLOCK_MONOTONIC`: A clock that cannot be set and is not affected by
+ *                      changes in the system time.
+ * @param[in] flags   Flags that modify the behavior of the timer. The commonly used values are:
+ *                    - `TFD_CLOEXEC`: Set the close-on-exec flag for the file descriptor.
+ *                    - `TFD_NONBLOCK`: Set the non-blocking flag for the file descriptor.
+ *
+ * @return sysret_t On success, returns a non-negative file descriptor that refers to the timer.
+ *                   On failure, returns a negative error code.
+ *
+ * @note The timer created by this function can be used to create periodic or one-shot timers.
+ *       The timer can be configured using `timerfd_settime` and notifications can be retrieved
+ *       by reading from the returned file descriptor.
+ */
 sysret_t sys_timerfd_create(int clockid, int flags)
 {
     int ret;
@@ -6330,6 +10643,33 @@ sysret_t sys_timerfd_create(int clockid, int flags)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Set or modify the expiration time for a timer.
+ *
+ * This function is used to arm or re-arm a timer associated with a file descriptor created
+ * by `sys_timerfd_create`. It allows setting a new expiration time and can also return
+ * the previous timer configuration.
+ *
+ * @param[in] fd     The file descriptor referring to the timer, which was created using
+ *                   `sys_timerfd_create`.
+ * @param[in] flags  Flags that modify the behavior of the timer. The commonly used values are:
+ *                   - `TFD_TIMER_ABSTIME`: If set, the `new` expiration time is an absolute time.
+ *                   - `TFD_TIMER_RELATIVE`: The default behavior, where `new` expiration time is
+ *                     a relative time from now.
+ * @param[in] new    A pointer to a `struct itimerspec` specifying the new expiration time.
+ *                   It contains two fields:
+ *                   - `it_value`: The initial expiration time of the timer.
+ *                   - `it_interval`: The period of periodic timers (if zero, the timer is one-shot).
+ * @param[out] old   A pointer to a `struct itimerspec` where the previous timer configuration
+ *                   will be stored. This can be `NULL` if the previous configuration is not needed.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note This function allows for both one-shot and periodic timers. If the timer is periodic,
+ *       it will continue triggering at intervals specified in `it_interval` until canceled or modified.
+ *       When a timer expires, the associated file descriptor becomes readable, and the application
+ *       can retrieve the expiration event by reading from the file descriptor.
+ */
 sysret_t sys_timerfd_settime(int fd, int flags, const struct itimerspec *new, struct itimerspec *old)
 {
     int ret = -1;
@@ -6380,6 +10720,27 @@ sysret_t sys_timerfd_settime(int fd, int flags, const struct itimerspec *new, st
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Retrieve the current configuration of a timer.
+ *
+ * This function is used to obtain the current expiration time and interval of a timer associated
+ * with a file descriptor created by `sys_timerfd_create`. It allows querying the current state
+ * of the timer, including the time remaining until the next expiration and the period (for periodic timers).
+ *
+ * @param[in] fd    The file descriptor referring to the timer, which was created using
+ *                  `sys_timerfd_create`.
+ * @param[out] cur  A pointer to a `struct itimerspec` where the current timer configuration will
+ *                  be stored. This structure contains:
+ *                  - `it_value`: The time remaining until the timer expires.
+ *                  - `it_interval`: The period for periodic timers (zero for one-shot timers).
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note The timer's `it_value` field will contain the time remaining until the next expiration.
+ *       If the timer is periodic, the `it_interval` field will contain the period for the next expiration.
+ *       If the timer has expired and there is no further interval (for one-shot timers), `it_value` will
+ *       contain a value of `0`.
+ */
 sysret_t sys_timerfd_gettime(int fd, struct itimerspec *cur)
 {
     int ret = -1;
@@ -6406,6 +10767,32 @@ sysret_t sys_timerfd_gettime(int fd, struct itimerspec *cur)
     return (ret < 0 ? GET_ERRNO() : ret);
 }
 
+/**
+ * @brief Create a file descriptor for receiving signals.
+ *
+ * This function creates a file descriptor that can be used to receive signals, similar to how a
+ * regular file descriptor is used. The signals specified in the provided signal mask are blocked
+ * for the calling thread, and any matching signals will be reported through the file descriptor.
+ * This allows signals to be handled in a more controlled, non-interrupt-driven way by using
+ * standard I/O operations (e.g., `read()` or `select()`) on the file descriptor.
+ *
+ * @param[in] fd    A file descriptor associated with the process, typically obtained from
+ *                  `sys_signalfd()` or a similar mechanism. If `fd` is `-1`, a new file descriptor
+ *                  will be created.
+ * @param[in] mask  A pointer to the signal mask (`sigset_t`) that specifies the signals that
+ *                  should be received by the file descriptor. Only signals in the mask will be
+ *                  reported.
+ * @param[in] flags Additional flags to control the behavior of the signalfd. Common flags
+ *                  include `O_NONBLOCK` for non-blocking operation.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note The caller must call `read()` on the resulting file descriptor to actually receive signals.
+ *       Each read returns a `struct signalfd_siginfo` containing the signal number, and additional
+ *       information, such as the signal source and sender.
+ *
+ * @see sys_read(), sigprocmask(), sigaction(), sigsuspend().
+ */
 sysret_t sys_signalfd(int fd, const sigset_t *mask, int flags)
 {
     int ret = 0;
@@ -6443,6 +10830,32 @@ sysret_t sys_memfd_create()
     return 0;
 }
 
+/**
+ * @brief Set the value of an interval timer.
+ *
+ * This function is used to set the value of a specified timer that generates periodic signals
+ * after the specified intervals. The timer can be configured to generate a signal when it expires,
+ * and it can be used for tasks like scheduling periodic events.
+ *
+ * @param[in] which Specifies which timer to set. Possible values include:
+ *                  - `ITIMER_REAL`: Timer that decrements in real time and sends `SIGALRM` when expired.
+ *                  - `ITIMER_VIRTUAL`: Timer that decrements only while the process is executing.
+ *                  - `ITIMER_PROF`: Timer that decrements while the process is executing or when it is
+ *                    executing in the kernel.
+ * @param[in] new A pointer to a `struct itimerspec` containing the new value for the timer.
+ *                The `itimerspec` structure contains two `timespec` fields: `it_value` for the initial
+ *                expiration time and `it_interval` for the interval between successive expirations.
+ * @param[out] old A pointer to a `struct itimerspec` where the previous timer values (before the
+ *                 timer is set) will be stored.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note If the specified timer is already active, it will be updated with the new values. The timer
+ *       will start at the `it_value` time and will repeat at the interval specified in `it_interval`.
+ *       If `it_interval` is set to `0`, the timer will not repeat and will only expire once.
+ *
+ * @see sys_getitimer(), sigaction(), alarm(), setitimer().
+ */
 sysret_t sys_setitimer(int which, const struct itimerspec *restrict new, struct itimerspec *restrict old)
 {
     sysret_t rc = 0;
@@ -6462,6 +10875,30 @@ sysret_t sys_setitimer(int which, const struct itimerspec *restrict new, struct
     return rc;
 }
 
+/**
+ * @brief Set the robust list for the current thread.
+ *
+ * The `sys_set_robust_list` function sets the robust list for the calling thread. The robust list is
+ * a list of `struct robust_list_head` elements that contain information about mutexes or other
+ * resources that need to be cleaned up if the thread dies unexpectedly.
+ *
+ * This function is typically used for thread safety in multi-threaded programs, where robust mutexes
+ * can be used to avoid leaving resources in an inconsistent state when a thread is terminated
+ * without properly unlocking locks or releasing resources.
+ *
+ * @param[in] head A pointer to the robust list to be set. This list contains `struct robust_list_head`
+ *                 entries which are used by the kernel to maintain information about robust mutexes.
+ * @param[in] len The length of the robust list (the number of entries in the list). This should correspond
+ *                to the size of the list in memory, generally expressed in bytes.
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note The robust list should be set during the initialization of a thread or task, and it may be
+ *       used by the kernel to track which mutexes need to be cleaned up in case of failure.
+ *       The list may be manipulated using related functions such as `sys_get_robust_list`.
+ *
+ * @see sys_get_robust_list(), robust_mutex, pthread_mutex, set_robust_list.
+ */
 sysret_t sys_set_robust_list(struct robust_list_head *head, size_t len)
 {
     if (len != sizeof(*head))
@@ -6471,6 +10908,33 @@ sysret_t sys_set_robust_list(struct robust_list_head *head, size_t len)
     return 0;
 }
 
+/**
+ * @brief Get the robust list for the specified thread.
+ *
+ * The `sys_get_robust_list` function retrieves the robust list associated with the given thread.
+ * The robust list contains `struct robust_list_head` entries used by the kernel to manage
+ * robust mutexes and other resources that need to be cleaned up if the thread terminates unexpectedly.
+ *
+ * This function is primarily used to retrieve the robust list for a specific thread, so that
+ * the caller can inspect or manipulate the robust list to handle clean-up operations in case
+ * the thread exits while holding resources.
+ *
+ * @param[in] tid The thread ID of the thread whose robust list is to be retrieved.
+ *
+ * @param[out] head_ptr A pointer to a pointer to `struct robust_list_head`. On success,
+ *                      this will point to the robust list for the specified thread.
+ *
+ * @param[out] len_ptr A pointer to a variable that will hold the length of the robust list
+ *                     (i.e., the number of entries in the list).
+ *
+ * @return sysret_t On success, returns `0`. On failure, returns a negative error code.
+ *
+ * @note The robust list is used to track mutexes and other resources that need to be cleaned up
+ *       if a thread terminates without releasing the resources properly. It is typically used by
+ *       the kernel for thread safety and resource management in multi-threaded programs.
+ *
+ * @see sys_set_robust_list(), robust_mutex, pthread_mutex, get_robust_list.
+ */
 sysret_t sys_get_robust_list(int tid, struct robust_list_head **head_ptr, size_t *len_ptr)
 {
     rt_thread_t thread;
@@ -6623,12 +11087,12 @@ const static struct rt_syscall_def func_table[] =
 
     SYSCALL_NET(SYSCALL_SIGN(sys_sendmsg)),
     SYSCALL_NET(SYSCALL_SIGN(sys_recvmsg)),
-    SYSCALL_SIGN(sys_notimpl),    //network,
-    SYSCALL_SIGN(sys_notimpl),    //network,
-    SYSCALL_SIGN(sys_notimpl),    //network, /* 90 */
-    SYSCALL_SIGN(sys_notimpl),    //network,
-    SYSCALL_SIGN(sys_notimpl),    //network,
-    SYSCALL_SIGN(sys_notimpl),    //network,
+    SYSCALL_SIGN(sys_notimpl),    /* network */
+    SYSCALL_SIGN(sys_notimpl),    /* network */
+    SYSCALL_SIGN(sys_notimpl),    /* network, 90 */
+    SYSCALL_SIGN(sys_notimpl),    /* network */
+    SYSCALL_SIGN(sys_notimpl),    /* network */
+    SYSCALL_SIGN(sys_notimpl),    /* network */
 
 #ifdef RT_USING_DFS
     SYSCALL_SIGN(sys_select),
@@ -6636,15 +11100,15 @@ const static struct rt_syscall_def func_table[] =
     SYSCALL_SIGN(sys_notimpl),
 #endif
 
-    SYSCALL_SIGN(sys_notimpl),    //SYSCALL_SIGN(sys_hw_interrupt_disable), /* 95 */
-    SYSCALL_SIGN(sys_notimpl),    //SYSCALL_SIGN(sys_hw_interrupt_enable),
+    SYSCALL_SIGN(sys_notimpl),    /* SYSCALL_SIGN(sys_hw_interrupt_disable), 95 */
+    SYSCALL_SIGN(sys_notimpl),    /* SYSCALL_SIGN(sys_hw_interrupt_enable) */
 
     SYSCALL_SIGN(sys_tick_get),
     SYSCALL_SIGN(sys_exit_group),
 
-    SYSCALL_SIGN(sys_notimpl),    //rt_delayed_work_init,
-    SYSCALL_SIGN(sys_notimpl),    //rt_work_submit,           /* 100 */
-    SYSCALL_SIGN(sys_notimpl),    //rt_wqueue_wakeup,
+    SYSCALL_SIGN(sys_notimpl),    /* rt_delayed_work_init */
+    SYSCALL_SIGN(sys_notimpl),    /* rt_work_submit, 100 */
+    SYSCALL_SIGN(sys_notimpl),    /* rt_wqueue_wakeup */
     SYSCALL_SIGN(sys_thread_mdelay),
     SYSCALL_SIGN(sys_sigaction),
     SYSCALL_SIGN(sys_sigprocmask),
@@ -6828,6 +11292,6 @@ const char *lwp_get_syscall_name(rt_uint32_t number)
         }
     }
 
-    // skip sys_
+    /* skip sys_ */
     return name;
 }