Add comments for all functions in components/libc/posix/io/termios/termios.c

components/libc/posix/io/termios/termios.c

@@ -4,8 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
- * Date           Author       Notes
- * 2017/08/30     Bernard      The first version
+ * Date             Author          Notes
+ * 2017-08-30       Bernard         The first version
+ * 2024-04-26       TroyMitchell    Add comments for all functions
  */
 
 #include <stdlib.h>
@@ -15,6 +16,17 @@
 #include "termios.h"
 #include <rtthread.h>
 
+/**
+ * @brief   Gets the current attributes of a terminal device.
+ * @param   fd File descriptor of the terminal device.
+ * @param   tio Pointer to a struct termios where the attributes will be stored.
+ * @return  Upon successful completion, returns 0; otherwise, returns -1.
+ *
+ * @note    This function retrieves the current attributes of a terminal device specified by the file descriptor fd.
+ *          It uses the ioctl system call with the TCGETA command to obtain the attributes and stores them in the
+ *          struct termios pointed to by tio.
+ *          If the ioctl operation fails, the function returns -1 to indicate an error.
+ */
 int tcgetattr(int fd, struct termios *tio)
 {
     /* Get the current serial port settings. */
@@ -24,6 +36,24 @@ int tcgetattr(int fd, struct termios *tio)
     return 0;
 }
 
+/**
+ * @brief   Sets the attributes of a terminal device.
+ * @param   fd File descriptor of the terminal device.
+ * @param   act Action to be taken for the attribute change (TCSANOW, TCSADRAIN, or TCSAFLUSH).
+ * @param   tio Pointer to a struct termios containing the new attributes.
+ * @return  Upon successful completion, returns 0; otherwise, returns -1 and sets errno to indicate the error.
+ *
+ * @note    This function sets the attributes of a terminal device specified by the file descriptor fd.
+ *          The act parameter determines when the attribute change takes effect:
+ *          - TCSANOW: Make the change immediately.
+ *          - TCSADRAIN: Make the change after all currently written data has been transmitted.
+ *          - TCSAFLUSH: Make the change after all currently written data has been transmitted, and discard
+ *            any received but unread data.
+ *          The new attributes are specified in the struct termios pointed to by tio.
+ *          The ioctl system call is used to set the attributes based on the value of act.
+ *          If the ioctl operation fails or an invalid action is specified, errno is set to indicate the error,
+ *          and the function returns -1.
+ */
 int tcsetattr(int fd, int act, const struct termios *tio)
 {
     switch (act)
@@ -50,26 +80,59 @@ int tcsetattr(int fd, int act, const struct termios *tio)
 }
 
 /**
- * this function gets process group ID for session leader for controlling
- * terminal
+ * @brief   Gets the session ID of a terminal.
+ * @param   fd File descriptor of the terminal device.
+ * @return  Always returns 0.
  *
- * @return always 0
+ * @note    This function is a stub and always returns 0.
+ *          In POSIX systems, tcgetsid() is used to get the session ID of the terminal associated with the file descriptor fd.
+ *          However, this function does not provide this functionality and simply returns 0 as a placeholder.
  */
 pid_t tcgetsid(int fd)
 {
     return 0;
 }
 
+/**
+ * @brief   Gets the output baud rate from a termios structure.
+ * @param   tio Pointer to a struct termios containing the terminal attributes.
+ * @return  Output baud rate extracted from the terminal attributes.
+ *
+ * @note    This function extracts the output baud rate from the termios structure pointed to by tio.
+ *          It retrieves the baud rate from the c_cflag member of the termios structure using the CBAUD mask.
+ *          The output baud rate is returned as a speed_t type.
+ */
 speed_t cfgetospeed(const struct termios *tio)
 {
     return tio->c_cflag & CBAUD;
 }
 
+/**
+ * @brief   Gets the input baud rate from a termios structure.
+ * @param   tio Pointer to a struct termios containing the terminal attributes.
+ * @return  Input baud rate extracted from the terminal attributes.
+ *
+ * @note    This function is a wrapper for the cfgetospeed() function.
+ *          It returns the input baud rate by calling cfgetospeed() with the termios structure pointer tio.
+ */
 speed_t cfgetispeed(const struct termios *tio)
 {
     return cfgetospeed(tio);
 }
 
+/**
+ * @brief   Sets the output baud rate in a termios structure.
+ * @param   tio Pointer to a struct termios where the output baud rate will be set.
+ * @param   speed Output baud rate to be set.
+ * @return  Upon successful completion, returns 0; otherwise, returns -1 and sets errno to indicate the error.
+ *
+ * @note    This function sets the output baud rate in the termios structure pointed to by tio.
+ *          The speed parameter specifies the baud rate to be set.
+ *          If the specified speed exceeds the CBAUD mask, indicating an invalid baud rate value,
+ *          errno is set to EINVAL, and the function returns -1.
+ *          Otherwise, the function clears the CBAUD bits in the c_cflag member of the termios structure
+ *          and sets them to the specified speed value. It then returns 0 to indicate success.
+ */
 int cfsetospeed(struct termios *tio, speed_t speed)
 {
     if (speed & ~CBAUD)
@@ -83,35 +146,106 @@ int cfsetospeed(struct termios *tio, speed_t speed)
     return 0;
 }
 
+/**
+ * @brief   Sets the input baud rate in a termios structure.
+ * @param   tio Pointer to a struct termios where the input baud rate will be set.
+ * @param   speed Input baud rate to be set.
+ * @return  Upon successful completion, returns 0; otherwise, returns -1 and sets errno to indicate the error.
+ *
+ * @note    This function sets the input baud rate in the termios structure pointed to by tio.
+ *          The speed parameter specifies the input baud rate to be set.
+ *          If the speed parameter is non-zero, indicating a valid baud rate, the function calls
+ *          cfsetospeed() to set both the input and output baud rates to the specified value.
+ *          If speed is zero, indicating that no baud rate needs to be set for input, the function returns 0
+ *          without making any changes to the termios structure.
+ */
 int cfsetispeed(struct termios *tio, speed_t speed)
 {
     return speed ? cfsetospeed(tio, speed) : 0;
 }
 
+/**
+ * @brief   Sends a break signal on a terminal.
+ * @param   fd File descriptor of the terminal device.
+ * @param   dur Duration of the break signal (ignored).
+ * @return  Always returns 0.
+ *
+ * @note    This function is a stub and does not send an actual break signal.
+ *          Sending a break signal with a nonzero duration is implementation-defined,
+ *          so this function ignores the duration parameter and always returns 0.
+ */
 int tcsendbreak(int fd, int dur)
 {
     /* nonzero duration is implementation-defined, so ignore it */
     return 0;
 }
 
+/**
+ * @brief   Flushes data from a terminal input or output queue.
+ * @param   fd File descriptor of the terminal device.
+ * @param   queue Queue to be flushed (TCIFLUSH, TCOFLUSH, or TCIOFLUSH).
+ * @return  Upon successful completion, returns 0; otherwise, returns -1 and sets errno to indicate the error.
+ *
+ * @note    This function flushes data from the input or output queue of the terminal device specified by the file descriptor fd.
+ *          The queue parameter specifies which queue to flush:
+ *          - TCIFLUSH: Flushes data from the input queue.
+ *          - TCOFLUSH: Flushes data from the output queue.
+ *          - TCIOFLUSH: Flushes data from both the input and output queues.
+ *          The ioctl system call is used with the TCFLSH command to perform the flush operation.
+ *          If the ioctl operation fails, errno is set to indicate the error, and the function returns -1.
+ */
 int tcflush(int fd, int queue)
 {
     return ioctl(fd, TCFLSH, (void*)(rt_ubase_t)queue);
 }
 
+/**
+ * @brief   Controls the terminal flow control.
+ * @param   fd File descriptor of the terminal device.
+ * @param   action Action to be taken for flow control (TCOOFF, TCOON, TCIOFF, or TCION).
+ * @return  Upon successful completion, returns 0; otherwise, returns -1 and sets errno to indicate the error.
+ *
+ * @note    This function controls the flow of data on the terminal device specified by the file descriptor fd.
+ *          The action parameter determines the flow control action to be taken:
+ *          - TCOOFF: Suspends output transmission.
+ *          - TCOON: Restarts output transmission.
+ *          - TCIOFF: Suspends input transmission.
+ *          - TCION: Restarts input transmission.
+ *          The ioctl system call is used with the TCXONC command to perform the flow control operation.
+ *          If the ioctl operation fails, errno is set to indicate the error, and the function returns -1.
+ */
 int tcflow(int fd, int action)
 {
     return ioctl(fd, TCXONC, (void*)(rt_ubase_t)action);
 }
 
 /**
- * this function waits for transmission of output
+ * @brief   Waits until all output written to the terminal is transmitted.
+ * @param   fd File descriptor of the terminal device.
+ * @return  Always returns 0.
+ *
+ * @note    This function is a stub and does not perform any action.
+ *          In POSIX systems, tcdrain() is used to wait until all output written to the terminal
+ *          is transmitted, but this function does not provide this functionality and simply returns 0 as a placeholder.
  */
 int tcdrain(int fd)
 {
     return 0;
 }
 
+/**
+ * @brief   Sets the terminal attributes to raw mode.
+ * @param   t Pointer to a struct termios where the terminal attributes will be set.
+ *
+ * @note    This function sets the terminal attributes pointed to by t to raw mode.
+ *          Raw mode disables special input and output processing features, making the terminal behave more like a data stream.
+ *          The following modifications are made to the termios structure:
+ *          - Input flags (c_iflag) are cleared of various processing flags.
+ *          - Output flags (c_oflag) are cleared to disable output processing.
+ *          - Local flags (c_lflag) are cleared to disable canonical mode, echoing, and signal handling.
+ *          - Control flags (c_cflag) are modified to set character size to 8 bits and disable parity.
+ *          - The VMIN and VTIME control characters are set to 1 and 0, respectively, for non-blocking read behavior.
+ */
 void cfmakeraw(struct termios *t)
 {
     t->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP|INLCR|IGNCR|ICRNL|IXON);
@@ -123,6 +257,16 @@ void cfmakeraw(struct termios *t)
     t->c_cc[VTIME] = 0;
 }
 
+/**
+ * @brief   Sets the input and output baud rates in a termios structure.
+ * @param   tio Pointer to a struct termios where the input and output baud rates will be set.
+ * @param   speed Baud rate to be set for both input and output.
+ * @return  Upon successful completion, returns 0; otherwise, returns -1 and sets errno to indicate the error.
+ *
+ * @note    This function is a wrapper for the cfsetospeed() function.
+ *          It sets both the input and output baud rates in the termios structure pointed to by tio to the specified speed.
+ *          The function returns the result of cfsetospeed(), which sets the baud rate for both input and output.
+ */
 int cfsetspeed(struct termios *tio, speed_t speed)
 {
     return cfsetospeed(tio, speed);