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 @@ -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 @@ -21,30 +22,42 @@ #include #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) */