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

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

This commit is contained in:
Troy 2024-04-26 20:47:54 +08:00 committed by Meco Man
parent bc774190f2
commit 946dd264ed
1 changed files with 150 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
components/libc/posix/io/termios/termios.c
View File

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