diff --git a/components/libc/posix/io/termios/termios.c b/components/libc/posix/io/termios/termios.c index ece9081d9d..2023410f9e 100644 --- a/components/libc/posix/io/termios/termios.c +++ b/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 @@ -15,6 +16,17 @@ #include "termios.h" #include +/** + * @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);