From 7f698140e86b7ca41803a8ff717e1596d97130e8 Mon Sep 17 00:00:00 2001 From: ousugo Date: Tue, 7 Dec 2021 16:05:01 +0800 Subject: [PATCH 1/3] Add pipe.c function annotation --- components/drivers/src/pipe.c | 171 ++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) diff --git a/components/drivers/src/pipe.c b/components/drivers/src/pipe.c index 89b544bc4e..e52b25a9c9 100644 --- a/components/drivers/src/pipe.c +++ b/components/drivers/src/pipe.c @@ -19,6 +19,15 @@ #include #include +/** + * @brief This function will open a pipe. + * + * @param fd is the file descriptor. + * + * @return Return the operation status, 0 on successful. + * When the return value is -1, it means the file descriptor is invalid. + * When the return value is -RT_ENOMEM, it means insufficient memory allocation failed. + */ static int pipe_fops_open(struct dfs_fd *fd) { int rc = 0; @@ -62,6 +71,14 @@ __exit: return rc; } +/** + * @brief This function will close a pipe. + * + * @param fd is the file descriptor. + * + * @return Return the operation status, 0 on successful. + * When the return value is -1, it means the file descriptor is invalid. + */ static int pipe_fops_close(struct dfs_fd *fd) { rt_device_t device; @@ -116,6 +133,22 @@ static int pipe_fops_close(struct dfs_fd *fd) return 0; } +/** + * @brief This function will get the pipe space size depends on the command. + * + * @param fd is the file descriptor. + * + * @param cmd is the command. It determines what data will get. + * + * FIONREAD The command to get the number of bytes in the pipe. + * + * FIONWRITE The command to get the number of bytes can be written to the pipe. + * + * @param args is the pointer to the data to store the read data. + * + * @return Return the operation status, 0 on successful. + * When the return value is -EINVAL, it means the command is invalid. + */ static int pipe_fops_ioctl(struct dfs_fd *fd, int cmd, void *args) { rt_pipe_t *pipe; @@ -139,6 +172,19 @@ static int pipe_fops_ioctl(struct dfs_fd *fd, int cmd, void *args) return ret; } +/** + * @brief This function will read data from pipe. + * + * @param fd is the file descriptor. + * + * @param buf is the buffer to store the read data. + * + * @param count is the length of data to be read. + * + * @return Return the length of data read. + * When the return value is 0, it means O_NONBLOCK is enabled and there is no thread that has the pipe open for writing. + * When the return value is -EAGAIN, it means there are no data to be read. + */ static int pipe_fops_read(struct dfs_fd *fd, void *buf, size_t count) { int len = 0; @@ -188,6 +234,19 @@ out: return len; } +/** + * @brief This function will write data to pipe. + * + * @param fd is the file descriptor. + * + * @param buf is a pointer to the data buffer to be written. + * + * @param count is the length of data to be write. + * + * @return Return the length of data written. + * When the return value is -EAGAIN, it means O_NONBLOCK is enabled and there are no space to be written. + * When the return value is -EPIPE, it means there is no thread that has the pipe open for reading. + */ static int pipe_fops_write(struct dfs_fd *fd, const void *buf, size_t count) { int len; @@ -258,6 +317,19 @@ out: return ret; } +/** + * @brief This function will get the pipe status. + * + * @param fd is the file descriptor. + * + * @param req is the request type. + * + * @return mask of the pipe status. + * POLLIN means there is data to be read. + * POLLHUP means there is no thread that has the pipe open for writing. + * POLLOUT means there is space to be written. + * POLLERR means there is no thread that has the pipe open for reading. + */ static int pipe_fops_poll(struct dfs_fd *fd, rt_pollreq_t *req) { int mask = 0; @@ -322,6 +394,18 @@ static const struct dfs_file_ops pipe_fops = }; #endif /* RT_USING_POSIX_DEVIO */ +/** + * @brief This function will open the pipe and actually creates the pipe buffer. + * + * @param device is a pointer to the pipe device descriptor. + * + * @param oflag is the open method, but it is not used yet. + * + * @return Return the operation status. + * When the return value is RT_EOK, the operation is successful. + * When the return value is -RT_EINVAL, it means the device handle is empty. + * When the return value is -RT_ENOMEM, it means insufficient memory allocation failed. + */ rt_err_t rt_pipe_open(rt_device_t device, rt_uint16_t oflag) { rt_pipe_t *pipe = (rt_pipe_t *)device; @@ -350,6 +434,15 @@ __exit: return ret; } +/** + * @brief This function will close the pipe and release the pipe buffer. + * + * @param device is a pointer to the pipe device descriptor. + * + * @return Return the operation status. + * When the return value is RT_EOK, the operation is successful. + * When the return value is -RT_EINVAL, it means the device handle is empty. + */ rt_err_t rt_pipe_close(rt_device_t device) { rt_pipe_t *pipe = (rt_pipe_t *)device; @@ -368,6 +461,20 @@ rt_err_t rt_pipe_close(rt_device_t device) return RT_EOK; } +/** + * @brief This function will read the specified length of data from the pipe. + * + * @param device is a pointer to the pipe device descriptor. + * + * @param pos is a parameter compatible with POSIX standard interface (currently meaningless, just pass in 0). + * + * @param buffer is a pointer to the buffer to store the read data. + * + * @param count is the length of data to be read. + * + * @return Return the length of data read. + * When the return value is 0, it means the pipe device handle is empty or the count is 0. + */ rt_size_t rt_pipe_read(rt_device_t device, rt_off_t pos, void *buffer, rt_size_t count) { uint8_t *pbuf; @@ -396,6 +503,20 @@ rt_size_t rt_pipe_read(rt_device_t device, rt_off_t pos, void *buffer, rt_size_t return read_bytes; } +/** + * @brief This function will write the specified length of data to the pipe. + * + * @param device is a pointer to the pipe device descriptor. + * + * @param pos is a parameter compatible with POSIX standard interface (currently meaningless, just pass in 0). + * + * @param buffer is a pointer to the data buffer to be written. + * + * @param count is the length of data to be written. + * + * @return Return the length of data written. + * When the return value is 0, it means the pipe device handle is empty or the count is 0. + */ rt_size_t rt_pipe_write(rt_device_t device, rt_off_t pos, const void *buffer, rt_size_t count) { uint8_t *pbuf; @@ -424,6 +545,17 @@ rt_size_t rt_pipe_write(rt_device_t device, rt_off_t pos, const void *buffer, rt return write_bytes; } +/** + * @brief This function is not used yet. + * + * @param dev is not used yet. + * + * @param cmd is not used yet. + * + * @param args is not used yet. + * + * @return Always return RT_EOK yet. + */ rt_err_t rt_pipe_control(rt_device_t dev, int cmd, void *args) { return RT_EOK; @@ -441,6 +573,18 @@ const static struct rt_device_ops pipe_ops = }; #endif /* RT_USING_DEVICE_OPS */ +/** + * @brief This function will initialize a pipe device. + * The system allocates a pipe handle from dynamic heap memory, initializes the pipe handle + * with the specified value, and registers the pipe device with the system. + * + * @param name is the name of pipe device. + * + * @param bufsz is the size of pipe buffer. + * + * @return Return the pointer to the pipe device. + * When the return value is RT_NULL, it means the initialization failed. + */ rt_pipe_t *rt_pipe_create(const char *name, int bufsz) { rt_pipe_t *pipe; @@ -486,6 +630,16 @@ rt_pipe_t *rt_pipe_create(const char *name, int bufsz) return pipe; } +/** + * @brief This function will delete a pipe device. + * The system will release the pipe handle and unregister the pipe device from the system. + * + * @param pipe is the pointer to the pipe device. + * + * @return Return the operation status, 0 on successful. + * When the return value is -RT_EINVAL, it means the pipe device is not found or the device isn't a pipe. + * When the return value is -RT_EBUSY, it means the pipe device is busy. + */ int rt_pipe_delete(const char *name) { int result = 0; @@ -530,6 +684,14 @@ int rt_pipe_delete(const char *name) } #ifdef RT_USING_POSIX_DEVIO +/** + * @brief This function will creat a anonymous pipe. + * + * @param fildes[0] is the read handle. + * fildes[1] is the write handle. + * + * @return Return the operation status, 0 on successful, -1 on failed. + */ int pipe(int fildes[2]) { rt_pipe_t *pipe; @@ -563,6 +725,15 @@ int pipe(int fildes[2]) return 0; } +/** + * @brief This function will create a named pipe. + * + * @param path is the name of pipe device. + * + * @param mode is not used yet. + * + * @return Return the operation status, 0 on successful, -1 on failed. + */ int mkfifo(const char *path, mode_t mode) { rt_pipe_t *pipe; From a237f805b940db16ef0d0009e56eb183f5713c07 Mon Sep 17 00:00:00 2001 From: ousugo Date: Tue, 7 Dec 2021 16:08:00 +0800 Subject: [PATCH 2/3] fix format --- components/drivers/src/pipe.c | 100 +++++++++++++++++----------------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/components/drivers/src/pipe.c b/components/drivers/src/pipe.c index e52b25a9c9..62047e46d6 100644 --- a/components/drivers/src/pipe.c +++ b/components/drivers/src/pipe.c @@ -21,9 +21,9 @@ /** * @brief This function will open a pipe. - * + * * @param fd is the file descriptor. - * + * * @return Return the operation status, 0 on successful. * When the return value is -1, it means the file descriptor is invalid. * When the return value is -RT_ENOMEM, it means insufficient memory allocation failed. @@ -73,9 +73,9 @@ __exit: /** * @brief This function will close a pipe. - * + * * @param fd is the file descriptor. - * + * * @return Return the operation status, 0 on successful. * When the return value is -1, it means the file descriptor is invalid. */ @@ -135,17 +135,17 @@ static int pipe_fops_close(struct dfs_fd *fd) /** * @brief This function will get the pipe space size depends on the command. - * + * * @param fd is the file descriptor. - * + * * @param cmd is the command. It determines what data will get. - * + * * FIONREAD The command to get the number of bytes in the pipe. - * + * * FIONWRITE The command to get the number of bytes can be written to the pipe. - * + * * @param args is the pointer to the data to store the read data. - * + * * @return Return the operation status, 0 on successful. * When the return value is -EINVAL, it means the command is invalid. */ @@ -174,11 +174,11 @@ static int pipe_fops_ioctl(struct dfs_fd *fd, int cmd, void *args) /** * @brief This function will read data from pipe. - * + * * @param fd is the file descriptor. - * + * * @param buf is the buffer to store the read data. - * + * * @param count is the length of data to be read. * * @return Return the length of data read. @@ -236,13 +236,13 @@ out: /** * @brief This function will write data to pipe. - * + * * @param fd is the file descriptor. - * + * * @param buf is a pointer to the data buffer to be written. - * + * * @param count is the length of data to be write. - * + * * @return Return the length of data written. * When the return value is -EAGAIN, it means O_NONBLOCK is enabled and there are no space to be written. * When the return value is -EPIPE, it means there is no thread that has the pipe open for reading. @@ -319,11 +319,11 @@ out: /** * @brief This function will get the pipe status. - * + * * @param fd is the file descriptor. - * + * * @param req is the request type. - * + * * @return mask of the pipe status. * POLLIN means there is data to be read. * POLLHUP means there is no thread that has the pipe open for writing. @@ -396,12 +396,12 @@ static const struct dfs_file_ops pipe_fops = /** * @brief This function will open the pipe and actually creates the pipe buffer. - * + * * @param device is a pointer to the pipe device descriptor. - * + * * @param oflag is the open method, but it is not used yet. - * - * @return Return the operation status. + * + * @return Return the operation status. * When the return value is RT_EOK, the operation is successful. * When the return value is -RT_EINVAL, it means the device handle is empty. * When the return value is -RT_ENOMEM, it means insufficient memory allocation failed. @@ -436,9 +436,9 @@ __exit: /** * @brief This function will close the pipe and release the pipe buffer. - * + * * @param device is a pointer to the pipe device descriptor. - * + * * @return Return the operation status. * When the return value is RT_EOK, the operation is successful. * When the return value is -RT_EINVAL, it means the device handle is empty. @@ -463,15 +463,15 @@ rt_err_t rt_pipe_close(rt_device_t device) /** * @brief This function will read the specified length of data from the pipe. - * + * * @param device is a pointer to the pipe device descriptor. - * + * * @param pos is a parameter compatible with POSIX standard interface (currently meaningless, just pass in 0). - * + * * @param buffer is a pointer to the buffer to store the read data. - * + * * @param count is the length of data to be read. - * + * * @return Return the length of data read. * When the return value is 0, it means the pipe device handle is empty or the count is 0. */ @@ -505,15 +505,15 @@ rt_size_t rt_pipe_read(rt_device_t device, rt_off_t pos, void *buffer, rt_size_t /** * @brief This function will write the specified length of data to the pipe. - * + * * @param device is a pointer to the pipe device descriptor. - * + * * @param pos is a parameter compatible with POSIX standard interface (currently meaningless, just pass in 0). - * + * * @param buffer is a pointer to the data buffer to be written. - * + * * @param count is the length of data to be written. - * + * * @return Return the length of data written. * When the return value is 0, it means the pipe device handle is empty or the count is 0. */ @@ -547,13 +547,13 @@ rt_size_t rt_pipe_write(rt_device_t device, rt_off_t pos, const void *buffer, rt /** * @brief This function is not used yet. - * + * * @param dev is not used yet. - * + * * @param cmd is not used yet. - * + * * @param args is not used yet. - * + * * @return Always return RT_EOK yet. */ rt_err_t rt_pipe_control(rt_device_t dev, int cmd, void *args) @@ -577,11 +577,11 @@ const static struct rt_device_ops pipe_ops = * @brief This function will initialize a pipe device. * The system allocates a pipe handle from dynamic heap memory, initializes the pipe handle * with the specified value, and registers the pipe device with the system. - * + * * @param name is the name of pipe device. - * + * * @param bufsz is the size of pipe buffer. - * + * * @return Return the pointer to the pipe device. * When the return value is RT_NULL, it means the initialization failed. */ @@ -633,9 +633,9 @@ rt_pipe_t *rt_pipe_create(const char *name, int bufsz) /** * @brief This function will delete a pipe device. * The system will release the pipe handle and unregister the pipe device from the system. - * + * * @param pipe is the pointer to the pipe device. - * + * * @return Return the operation status, 0 on successful. * When the return value is -RT_EINVAL, it means the pipe device is not found or the device isn't a pipe. * When the return value is -RT_EBUSY, it means the pipe device is busy. @@ -686,10 +686,10 @@ int rt_pipe_delete(const char *name) #ifdef RT_USING_POSIX_DEVIO /** * @brief This function will creat a anonymous pipe. - * + * * @param fildes[0] is the read handle. * fildes[1] is the write handle. - * + * * @return Return the operation status, 0 on successful, -1 on failed. */ int pipe(int fildes[2]) @@ -727,11 +727,11 @@ int pipe(int fildes[2]) /** * @brief This function will create a named pipe. - * + * * @param path is the name of pipe device. - * + * * @param mode is not used yet. - * + * * @return Return the operation status, 0 on successful, -1 on failed. */ int mkfifo(const char *path, mode_t mode) From 3e9757888f94fb739c77e6dbaa941500234cc3d9 Mon Sep 17 00:00:00 2001 From: ousugo Date: Tue, 14 Dec 2021 14:13:02 +0800 Subject: [PATCH 3/3] Fix format and mistake --- components/drivers/src/pipe.c | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/components/drivers/src/pipe.c b/components/drivers/src/pipe.c index 993f6f7616..7e1f569b62 100644 --- a/components/drivers/src/pipe.c +++ b/components/drivers/src/pipe.c @@ -24,7 +24,8 @@ * * @param fd is the file descriptor. * - * @return Return the operation status, 0 on successful. + * @return Return the operation status. + * When the return value is 0, it means the operation is successful. * When the return value is -1, it means the file descriptor is invalid. * When the return value is -RT_ENOMEM, it means insufficient memory allocation failed. */ @@ -76,7 +77,8 @@ __exit: * * @param fd is the file descriptor. * - * @return Return the operation status, 0 on successful. + * @return Return the operation status. + * When the return value is 0, it means the operation is successful. * When the return value is -1, it means the file descriptor is invalid. */ static int pipe_fops_close(struct dfs_fd *fd) @@ -146,7 +148,8 @@ static int pipe_fops_close(struct dfs_fd *fd) * * @param args is the pointer to the data to store the read data. * - * @return Return the operation status, 0 on successful. + * @return Return the operation status. + * When the return value is 0, it means the operation is successful. * When the return value is -EINVAL, it means the command is invalid. */ static int pipe_fops_ioctl(struct dfs_fd *fd, int cmd, void *args) @@ -326,9 +329,9 @@ out: * * @return mask of the pipe status. * POLLIN means there is data to be read. - * POLLHUP means there is no thread that has the pipe open for writing. + * POLLHUP means there is no thread that occupied the pipe to open for writing. * POLLOUT means there is space to be written. - * POLLERR means there is no thread that has the pipe open for reading. + * POLLERR means there is no thread that occupied the pipe to open for reading. */ static int pipe_fops_poll(struct dfs_fd *fd, rt_pollreq_t *req) { @@ -554,7 +557,7 @@ static rt_size_t rt_pipe_write(rt_device_t device, rt_off_t pos, const void *buf * * @param args is not used yet. * - * @return Always return RT_EOK yet. + * @return Always return RT_EOK. */ static rt_err_t rt_pipe_control(rt_device_t dev, int cmd, void *args) { @@ -636,7 +639,8 @@ rt_pipe_t *rt_pipe_create(const char *name, int bufsz) * * @param pipe is the pointer to the pipe device. * - * @return Return the operation status, 0 on successful. + * @return Return the operation status. + * When the return value is 0, it means the operation is successful. * When the return value is -RT_EINVAL, it means the pipe device is not found or the device isn't a pipe. * When the return value is -RT_EBUSY, it means the pipe device is busy. */ @@ -690,7 +694,9 @@ int rt_pipe_delete(const char *name) * @param fildes[0] is the read handle. * fildes[1] is the write handle. * - * @return Return the operation status, 0 on successful, -1 on failed. + * @return Return the operation status. + * When the return value is 0, it means the operation is successful. + * When the return value is -1, it means the operation is failed. */ int pipe(int fildes[2]) { @@ -732,7 +738,9 @@ int pipe(int fildes[2]) * * @param mode is not used yet. * - * @return Return the operation status, 0 on successful, -1 on failed. + * @return Return the operation status. + * When the return value is 0, it means the operation is successful. + * When the return value is -1, it means the operation is failed. */ int mkfifo(const char *path, mode_t mode) {