libs/rt-thread-official
libs
/
rt-thread-official
mirror of https://github.com/RT-Thread/rt-thread.git
4
0
Fork 0
Code Issues Releases Wiki Activity

[libc][posix/io] add comments

This commit is contained in:
Troy 2024-04-02 11:18:15 +08:00 committed by GitHub
parent 79e2946467
commit 3a4db99104
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 197 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
components/libc/posix/io/epoll/epoll.c
View File

@ -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

21
components/libc/posix/io/mman/mman.c
View File

@ -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)

66
components/libc/posix/io/mman/sys/mman.h
View File

@ -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);

135
components/libc/posix/io/poll/poll.c
View File

@ -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;

57
components/libc/posix/io/poll/poll.h
View File

@ -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) */