[libc][posix/io] add comments

5 files changed, 197 insertions, 84 deletions

diff --git a/components/libc/posix/io/epoll/epoll.c b/components/libc/posix/io/epoll/epoll.c
index 26527fb611..7677b8deea 100644
--- a/components/libc/posix/io/epoll/epoll.c
+++ b/components/libc/posix/io/epoll/epoll.c
@@ -6,7 +6,7 @@
  * Change Logs:
  * Date           Author        Notes
  * 2023-07-29     zmq810150896  first version
- * 2024/03/26     TroyMitchelle Add comments for all functions, members within structure members and fix incorrect naming of triggered
+ * 2024-03-26     TroyMitchelle Add comments for all functions, members within structure members and fix incorrect naming of triggered
  * 2023-12-14     Shell         When poll goes to sleep before the waitqueue has added a
  *                              record and finished enumerating all the fd's, it may be
  *                              incorrectly woken up. This is basically because the poll
diff --git a/components/libc/posix/io/mman/mman.c b/components/libc/posix/io/mman/mman.c
index 69a86d9bab..68b906903c 100644
--- a/components/libc/posix/io/mman/mman.c
+++ b/components/libc/posix/io/mman/mman.c
@@ -4,8 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
- * Date           Author       Notes
- * 2017/11/30     Bernard      The first version.
+ * Date           Author            Notes
+ * 2017/11/30     Bernard           The first version.
+ * 2024/03/29     TroyMitchelle     Add all function comments
  */
 
 #include <stdint.h>
@@ -20,6 +21,16 @@
 
 #include "sys/mman.h"
 
+/**
+ * @brief   Maps a region of memory into the calling process's address space.
+ * @param   addr    Desired starting address of the mapping.
+ * @param   length  Length of the mapping.
+ * @param   prot    Protection of the mapped memory region.
+ * @param   flags   Type of the mapped memory region.
+ * @param   fd      File descriptor of the file to be mapped.
+ * @param   offset  Offset within the file to start the mapping.
+ * @return  Upon success, returns a pointer to the mapped region; otherwise, MAP_FAILED is returned.
+ */
 void *mmap(void *addr, size_t length, int prot, int flags,
     int fd, off_t offset)
 {
@@ -59,6 +70,12 @@ void *mmap(void *addr, size_t length, int prot, int flags,
     return MAP_FAILED;
 }
 
+/**
+ * @brief   Unmaps a mapped region of memory.
+ * @param   addr    Starting address of the mapping to be unmapped.
+ * @param   length  Length of the mapping.
+ * @return  Upon success, returns 0; otherwise, -1 is returned.
+ */
 int munmap(void *addr, size_t length)
 {
     if (addr)
diff --git a/components/libc/posix/io/mman/sys/mman.h b/components/libc/posix/io/mman/sys/mman.h
index a730f33b6b..0955975c65 100644
--- a/components/libc/posix/io/mman/sys/mman.h
+++ b/components/libc/posix/io/mman/sys/mman.h
@@ -4,8 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
- * Date           Author       Notes
- * 2017/11/30     Bernard      The first version.
+ * Date           Author            Notes
+ * 2017/11/30     Bernard           The first version.
+ * 2024/03/29     TroyMitchelle     Add comments for all macros
  */
 
 #ifndef __SYS_MMAN_H__
@@ -19,37 +20,42 @@ extern "C" {
 
 #define MAP_FAILED     ((void *) -1)
 
-#define MAP_SHARED     0x01
-#define MAP_PRIVATE    0x02
-#define MAP_TYPE       0x0f
-#define MAP_FIXED      0x10
-#define MAP_ANON       0x20
-#define MAP_ANONYMOUS  MAP_ANON
-#define MAP_NORESERVE  0x4000
-#define MAP_GROWSDOWN  0x0100
-#define MAP_DENYWRITE  0x0800
-#define MAP_EXECUTABLE 0x1000
-#define MAP_LOCKED     0x2000
-#define MAP_POPULATE   0x8000
-#define MAP_NONBLOCK   0x10000
-#define MAP_STACK      0x20000
-#define MAP_HUGETLB    0x40000
-#define MAP_FILE       0
+/* mmap flags */
+#define MAP_SHARED     0x01      /**< Share the mapping with other processes. */
+#define MAP_PRIVATE    0x02      /**< Create a private copy-on-write mapping. */
+#define MAP_TYPE       0x0f      /**< Mask for type of mapping. */
+#define MAP_FIXED      0x10      /**< Interpret addr exactly. */
+#define MAP_ANON       0x20      /**< Anonymous mapping. */
+#define MAP_ANONYMOUS  MAP_ANON  /**< Synonym for MAP_ANON. */
+#define MAP_NORESERVE  0x4000    /**< Don't reserve swap space for this mapping. */
+#define MAP_GROWSDOWN  0x0100    /**< Stack-like segment. */
+#define MAP_DENYWRITE  0x0800    /**< ETXTBSY. */
+#define MAP_EXECUTABLE 0x1000    /**< Mark it as an executable. */
+#define MAP_LOCKED     0x2000    /**< Lock the mapping's pages. */
+#define MAP_POPULATE   0x8000    /**< Populate (prefault) pagetables. */
+#define MAP_NONBLOCK   0x10000   /**< Do not block on IO. */
+#define MAP_STACK      0x20000   /**< Allocation is a stack segment. */
+#define MAP_HUGETLB    0x40000   /**< Create a huge page mapping. */
+#define MAP_FILE       0         /**< Compatibility */
 
-#define PROT_NONE      0
-#define PROT_READ      1
-#define PROT_WRITE     2
-#define PROT_EXEC      4
-#define PROT_GROWSDOWN 0x01000000
-#define PROT_GROWSUP   0x02000000
+/* mmap protections */
+#define PROT_NONE      0         /**< No access. */
+#define PROT_READ      1         /**< Page can be read. */
+#define PROT_WRITE     2         /**< Page can be written. */
+#define PROT_EXEC      4         /**< Page can be executed. */
+#define PROT_GROWSDOWN 0x01000000/**< Extend change to start of growsdown vma (mprotect only). */
+#define PROT_GROWSUP   0x02000000/**< Extend change to start of growsup vma (mprotect only). */
 
-#define MS_ASYNC       1
-#define MS_INVALIDATE  2
-#define MS_SYNC        4
+/* msync flags */
+#define MS_ASYNC       1         /**< Perform asynchronous writes. */
+#define MS_INVALIDATE  2         /**< Invalidate mappings after writing. */
+#define MS_SYNC        4         /**< Perform synchronous writes. */
+
+/* mlockall flags */
+#define MCL_CURRENT    1         /**< Lock all pages which are currently mapped into the address space of the process. */
+#define MCL_FUTURE     2         /**< Lock all pages which will become mapped into the address space of the process in the future. */
+#define MCL_ONFAULT    4         /**< Lock all pages which are currently mapped into the address space of the process on access. */
 
-#define MCL_CURRENT    1
-#define MCL_FUTURE     2
-#define MCL_ONFAULT    4
 
 void *mmap (void *start, size_t len, int prot, int flags, int fd, off_t off);
 int munmap (void *start, size_t len);
diff --git a/components/libc/posix/io/poll/poll.c b/components/libc/posix/io/poll/poll.c
index 2abc1cde6b..7ab4a9bec1 100644
--- a/components/libc/posix/io/poll/poll.c
+++ b/components/libc/posix/io/poll/poll.c
@@ -4,15 +4,16 @@
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
- * Date           Author       Notes
- * 2016-12-28     Bernard      first version
- * 2018-03-09     Bernard      Add protection for pt->triggered.
- * 2023-12-04     Shell        Fix return code and error verification
- * 2023-12-14     Shell        When poll goes to sleep before the waitqueue has added a
- *                             record and finished enumerating all the fd's, it may be
- *                             incorrectly woken up. This is basically because the poll
- *                             mechanism wakeup algorithm does not correctly distinguish
- *                             the current wait state.
+ * Date           Author            Notes
+ * 2016-12-28     Bernard           first version
+ * 2018-03-09     Bernard           Add protection for pt->triggered.
+ * 2023-12-04     Shell             Fix return code and error verification
+ * 2023-12-14     Shell             When poll goes to sleep before the waitqueue has added a
+ *                                  record and finished enumerating all the fd's, it may be
+ *                                  incorrectly woken up. This is basically because the poll
+ *                                  mechanism wakeup algorithm does not correctly distinguish
+ *                                  the current wait state.
+ * 2024-03-29     TroyMitchelle     Add all function comments and comments to structure members
  */
 
 #include <stdint.h>
@@ -21,30 +22,42 @@
 #include <dfs_file.h>
 #include "poll.h"
 
-struct rt_poll_node;
-enum rt_poll_status {
-    RT_POLL_STAT_INIT,
-    RT_POLL_STAT_TRIG,
-    RT_POLL_STAT_WAITING,
+
+enum rt_poll_status 
+{
+    RT_POLL_STAT_INIT,     /**< Poll operation initialization status. */
+    RT_POLL_STAT_TRIG,     /**< Poll operation triggered status. */
+    RT_POLL_STAT_WAITING   /**< Poll operation waiting status. */
 };
 
-struct rt_poll_table
+
+struct rt_poll_table 
 {
-    rt_pollreq_t req;
-    enum rt_poll_status status; /* the waited thread whether triggered */
-    rt_thread_t polling_thread;
-    struct rt_poll_node *nodes;
+    rt_pollreq_t req;               /**< Poll request. */
+    enum rt_poll_status status;     /**< Status of the poll operation. */
+    rt_thread_t polling_thread;     /**< Polling thread associated with the table. */
+    struct rt_poll_node *nodes;     /**< Linked list of poll nodes. */
 };
 
-struct rt_poll_node
+
+struct rt_poll_node 
 {
-    struct rt_wqueue_node wqn;
-    struct rt_poll_table *pt;
-    struct rt_poll_node *next;
+    struct rt_wqueue_node wqn;     /**< Wait queue node for the poll node. */
+    struct rt_poll_table *pt;       /**< Pointer to the parent poll table. */
+    struct rt_poll_node *next;      /**< Pointer to the next poll node. */
 };
 
 static RT_DEFINE_SPINLOCK(_spinlock);
 
+/**
+ * @brief   Wake-up function for the wait queue.
+ *
+ * This function is invoked when a node in the wait queue needs to be woken up.
+ *
+ * @param   wait    Pointer to the wait queue node.
+ * @param   key     Key associated with the wake-up operation.
+ * @return  Upon successful wake-up, returns 0; otherwise, -1 is returned.
+ */
 static int __wqueue_pollwake(struct rt_wqueue_node *wait, void *key)
 {
     rt_ubase_t level;
@@ -68,6 +81,15 @@ static int __wqueue_pollwake(struct rt_wqueue_node *wait, void *key)
     return -1;
 }
 
+/**
+ * @brief   Adds a poll request to the wait queue.
+ *
+ * This function adds a poll request to the wait queue associated with the specified
+ * wait queue and poll request.
+ *
+ * @param   wq      Pointer to the wait queue.
+ * @param   req     Pointer to the poll request.
+ */
 static void _poll_add(rt_wqueue_t *wq, rt_pollreq_t *req)
 {
     struct rt_poll_table *pt;
@@ -89,6 +111,14 @@ static void _poll_add(rt_wqueue_t *wq, rt_pollreq_t *req)
     rt_wqueue_add(wq, &node->wqn);
 }
 
+/**
+ * @brief   Initializes a poll table.
+ *
+ * This function initializes a poll table with the provided poll request, status,
+ * and polling thread.
+ *
+ * @param   pt  Pointer to the poll table to be initialized.
+ */
 static void poll_table_init(struct rt_poll_table *pt)
 {
     pt->req._proc = _poll_add;
@@ -97,6 +127,18 @@ static void poll_table_init(struct rt_poll_table *pt)
     pt->polling_thread = rt_thread_self();
 }
 
+/**
+ * @brief   Waits for events on the poll table with a specified timeout.
+ *
+ * This function waits for events on the poll table with the specified timeout
+ * in milliseconds.
+ *
+ * @param   pt      Pointer to the poll table.
+ * @param   msec    Timeout value in milliseconds.
+ * @return  Upon successful completion, returns 0. If the timeout expires, -RT_ETIMEOUT
+ *          is returned. If the operation is interrupted by a signal, -RT_EINTR is
+ *          returned.
+ */
 static int poll_wait_timeout(struct rt_poll_table *pt, int msec)
 {
     rt_int32_t timeout;
@@ -150,6 +192,17 @@ static int poll_wait_timeout(struct rt_poll_table *pt, int msec)
     return ret;
 }
 
+/**
+ * @brief   Performs poll operation for a single file descriptor.
+ *
+ * This function performs a poll operation for a single file descriptor and updates
+ * the revents field of the pollfd structure accordingly.
+ *
+ * @param   pollfd  Pointer to the pollfd structure.
+ * @param   req     Pointer to the poll request.
+ * @return  Upon successful completion, returns the bitmask of events that occurred.
+ *          If an error occurs, -1 is returned.
+ */
 static int do_pollfd(struct pollfd *pollfd, rt_pollreq_t *req)
 {
     int mask = 0;
@@ -187,6 +240,21 @@ static int do_pollfd(struct pollfd *pollfd, rt_pollreq_t *req)
     return mask;
 }
 
+/**
+ * @brief   Performs the poll operation on an array of file descriptors.
+ *
+ * This function performs the poll operation on an array of file descriptors and
+ * waits for events with the specified timeout.
+ *
+ * @param   fds     Pointer to the array of pollfd structures.
+ * @param   nfds    Number of file descriptors in the array.
+ * @param   pt      Pointer to the poll table.
+ * @param   msec    Timeout value in milliseconds.
+ * @return  Upon successful completion, returns the number of file descriptors
+ *          for which events were received. If the timeout expires, -RT_ETIMEOUT
+ *          is returned. If the operation is interrupted by a signal, -RT_EINTR is
+ *          returned.
+ */
 static int poll_do(struct pollfd *fds, nfds_t nfds, struct rt_poll_table *pt, int msec)
 {
     int num;
@@ -241,6 +309,14 @@ static int poll_do(struct pollfd *fds, nfds_t nfds, struct rt_poll_table *pt, in
     return num;
 }
 
+/**
+ * @brief   Tears down the poll table.
+ *
+ * This function tears down the poll table by removing all poll nodes associated
+ * with it.
+ *
+ * @param   pt  Pointer to the poll table.
+ */
 static void poll_teardown(struct rt_poll_table *pt)
 {
     struct rt_poll_node *node, *next;
@@ -255,6 +331,19 @@ static void poll_teardown(struct rt_poll_table *pt)
     }
 }
 
+/**
+ * @brief   Performs the poll operation on a set of file descriptors.
+ *
+ * This function performs the poll operation on a set of file descriptors and
+ * waits for events with the specified timeout.
+ *
+ * @param   fds     Pointer to the array of pollfd structures.
+ * @param   nfds    Number of file descriptors in the array.
+ * @param   timeout Timeout value in milliseconds.
+ * @return  Upon successful completion, returns the number of file descriptors
+ *          for which events were received. If the timeout expires, 0 is returned.
+ *          If an error occurs, -1 is returned.
+ */
 int poll(struct pollfd *fds, nfds_t nfds, int timeout)
 {
     int num;
diff --git a/components/libc/posix/io/poll/poll.h b/components/libc/posix/io/poll/poll.h
index 7b710cd14e..def526ff9d 100644
--- a/components/libc/posix/io/poll/poll.h
+++ b/components/libc/posix/io/poll/poll.h
@@ -4,8 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
- * Date           Author       Notes
- * 2021-09-11     Meco Man     First version
+ * Date           Author            Notes
+ * 2021-09-11     Meco Man          First version
+ * 2024-03-29     TroyMitchelle     Add all macro comments and comments to structure members
  */
 
 #ifndef __POLL_H__
@@ -17,43 +18,43 @@ extern "C" {
 
 #ifdef RT_USING_MUSLLIBC
 #if !defined(POLLIN) && !defined(POLLOUT)
-#define POLLIN     0x001
-#define POLLPRI    0x002
-#define POLLOUT    0x004
-#define POLLERR    0x008
-#define POLLHUP    0x010
-#define POLLNVAL   0x020
-#define POLLRDNORM 0x040
-#define POLLRDBAND 0x080
-#define POLLWRNORM 0x100
-#define POLLWRBAND 0x200
+#define POLLIN     0x001   /**< There is data to read. */
+#define POLLPRI    0x002   /**< There is urgent data to read. */
+#define POLLOUT    0x004   /**< Writing is now possible. */
+#define POLLERR    0x008   /**< Error condition. */
+#define POLLHUP    0x010   /**< Hang up. */
+#define POLLNVAL   0x020   /**< Invalid polling request. */
+#define POLLRDNORM 0x040   /**< Normal data may be read. */
+#define POLLRDBAND 0x080   /**< Priority data may be read. */
+#define POLLWRNORM 0x100   /**< Writing normal data is possible. */
+#define POLLWRBAND 0x200   /**< Writing priority data is possible. */
 typedef unsigned int nfds_t;
 struct pollfd
 {
-    int fd;
-    short events;
-    short revents;
+    int fd;             /**< File descriptor. */
+    short events;       /**< Requested events. */
+    short revents;      /**< Returned events. */
 };
 #endif
 #else
 #if !defined(POLLIN) && !defined(POLLOUT)
-#define POLLIN     0x1
-#define POLLOUT    0x2
-#define POLLERR    0x4
-#define POLLNVAL   0x8
+#define POLLIN     0x1     /**< There is data to read. */
+#define POLLOUT    0x2     /**< Writing is now possible. */
+#define POLLERR    0x4     /**< Error condition. */
+#define POLLNVAL   0x8     /**< Invalid polling request. */
 /* Below values are unimplemented */
-#define POLLRDNORM 0x10
-#define POLLRDBAND 0x20
-#define POLLPRI    0x40
-#define POLLWRNORM 0x80
-#define POLLWRBAND 0x100
-#define POLLHUP    0x200
+#define POLLRDNORM 0x10    /**< Normal data may be read. */
+#define POLLRDBAND 0x20    /**< Priority data may be read. */
+#define POLLPRI    0x40    /**< There is urgent data to read. */
+#define POLLWRNORM 0x80    /**< Writing normal data is possible. */
+#define POLLWRBAND 0x100   /**< Writing priority data is possible. */
+#define POLLHUP    0x200   /**< Hang up. */
 typedef unsigned int nfds_t;
 struct pollfd
 {
-    int fd;
-    short events;
-    short revents;
+    int fd;             /**< File descriptor. */
+    short events;       /**< Requested events. */
+    short revents;      /**< Returned events. */
 };
 #endif
 #endif /* !defined(POLLIN) && !defined(POLLOUT) */