[PATCH v1 3/3] termios: manual: disambiguate hardware and software flow control

[H. Peter Anvin]

Hardware and software flow control are completely independent, but the
manual used the term "flow control" ambiguously.  Consistently specify
hardware or software flow control.

Add some additional index entries as well, as these concepts are
partially described across different sections.

Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>
---
 manual/terminal.texi | 89 ++++++++++++++++++++++++++++++--------------
 1 file changed, 61 insertions(+), 28 deletions(-)

diff --git a/manual/terminal.texi b/manual/terminal.texi
index 2f7633c0b824..2e0871360859 100644
--- a/manual/terminal.texi
+++ b/manual/terminal.texi
@@ -50,6 +50,10 @@ speed is device specific.
 The rest of this section is described in terms of a physical RS232
 interface.
 
+@cindex Data Terminal Equipment (DTE)
+@cindex DTE
+@cindex Data Communications Equipment (DCE)
+@cindex DCE
 The RS232 specification assumes the host (@dfn{Data Terminal Equipment},
 @dfn{DTE}) connects to a modem (@dfn{Data Communications Equipment},
 @dfn{DCE}), regardless of if a physical modem is present or not.
@@ -69,6 +73,9 @@ full RS232 and V.24 specifications provide a large number of signals,
 but the ones that are typically implemented in contemporary hardware and
 are relevant to the terminal device interface are:
 
+@cindex terminal control and status signals
+@cindex control signals, terminal
+@cindex status signals, terminal
 @table @asis
 @item DTR - Data Terminal Ready (control)
 
@@ -78,13 +85,17 @@ communications session.  If deasserted (false), this is a
 required to, trigger a modem disconnect in response.
 @cindex modem disconnect request
 
+@cindex hardware terminal flow control
+@cindex terminal flow control, hardware
+@cindex flow control, terminal
+@cindex RTS/CTS flow control
 @item RTS - Request To Send (control)
 
 This signal is also referred to as Ready To Receive (RTR).
 
 If asserted, the DTE is ready to accept data.  If deasserted, the DCE is
 requested to hold data temporarily without disconnecting.  This is known
-as hardware or RTS/CTS @dfn{flow control} and can be handled
+as @dfn{RTS/CTS} or @dfn{hardware flow control} and can be handled
 automatically if the appropriate terminal mode flags are set.
 
 @item DSR - Data Set Ready (status)
@@ -234,10 +245,10 @@ when you type a very long line.  @xref{Canonical or Not}.
 @cindex terminal output queue
 The @dfn{terminal output queue} is like the input queue, but for output;
 it contains characters that have been written by processes, but not yet
-transmitted to the terminal.  If output flow control is enabled by
-setting the @code{IXON} input mode bit (@pxref{Input Modes}), the
+transmitted to the terminal.  If output software flow control is enabled
+by setting the @code{IXON} input mode bit (@pxref{Input Modes}), the
 terminal driver obeys START and STOP characters sent by the terminal to
-stop and restart transmission of output.
+stop and restart transmission of output.  @xref{Start/Stop Characters}.
 
 @dfn{Clearing} the terminal input queue means discarding any characters
 that have been received but not yet read.  Similarly, clearing the
@@ -545,9 +556,10 @@ set_istrip (int desc, int value)
 @node Input Modes
 @subsection Input Modes
 
-This section describes the terminal attribute flags that control
-fairly low-level aspects of input processing: handling of parity errors,
-BREAK signals, flow control, and @key{RET} and @key{LFD} characters.
+This section describes the terminal attribute flags that control fairly
+low-level aspects of input processing: handling of parity errors, BREAK
+signals, hardware and software flow control, and @key{RET} and @key{LFD}
+characters.
 
 All of these flags are bits in the @code{c_iflag} member of the
 @code{struct termios} structure.  The member is an integer, and you
@@ -839,19 +851,21 @@ systems and @gnuhurdsystems{}.
 
 @deftypevr Macro tcflag_t CCTS_OFLOW
 @standards{BSD, termios.h}
-If this bit is set, enable flow control of output based on the CTS wire
-(RS232 protocol).
+If this bit is set, enable hardware flow control of output based
+on the CTS status signal.
 @end deftypevr
 
 @deftypevr Macro tcflag_t CRTS_IFLOW
 @standards{BSD, termios.h}
-If this bit is set, enable flow control of input based on the RTS wire
-(RS232 protocol).
+If this bit is set, enable hardware flow control of input based on the
+RTS control signal.
 @end deftypevr
 
 @deftypevr Macro tcflag_t MDMBUF
 @standards{BSD, termios.h}
-If this bit is set, enable carrier-based flow control of output.
+If this bit is set, enable hardware flow control of output based on the
+Data Carrier Detect (DCD) status signal instead of the CTS status
+signal.
 @end deftypevr
 
 @deftypevr Macro tcflag_t CIGNORE
@@ -1046,9 +1060,8 @@ bit remains set until reprinting is finished.  @xref{Editing Characters}.
 
 @node Line Speed
 @subsection Line Speed
-@cindex line speed
-@cindex baud rate
-@cindex terminal line speed
+@cindex line speed, terminal
+@cindex baud rate, terminal
 @cindex terminal line speed
 
 The terminal line speed tells the computer how fast to read and write
@@ -1689,12 +1702,29 @@ Typically, the DSUSP character is @kbd{C-y}.
 @end deftypevr
 
 @node Start/Stop Characters
-@subsubsection Special Characters for Flow Control
+@cindex software flow control, terminal
+@cindex terminal flow control, software
+@cindex flow control, terminal
+@cindex XON/XOFF flow control
+@subsubsection Special Characters for Software Flow Control
 
 These special characters may be active in either canonical or noncanonical
 input mode, but their use is controlled by the flags @code{IXON} and
 @code{IXOFF} (@pxref{Input Modes}).
 
+This is referred to as @dfn{XON/XOFF} or @dfn{software flow control},
+and is independent of hardware (RTS/CTS) flow control; it is possible to
+use either one, both at the same time, or neither.
+
+Whereas hardware flow control is fully transparent, software flow
+control requires that the START and STOP characters are dedicated to
+this function and cannot be used for other purposes.  This may interfere
+with applications that use these characters, or require full binary
+transparency.
+
+The terms @dfn{XON} and @dfn{XOFF} are often used to describe the
+@emph{default} values of the START and STOP characters.
+
 @deftypevr Macro int VSTART
 @standards{POSIX.1, termios.h}
 @cindex START character
@@ -1710,9 +1740,9 @@ output; the resuming character is not discarded unless it is the START
 character.  If @code{IXOFF} is set, the system may also transmit START
 characters to the terminal.
 
-The usual value for the START character is @kbd{C-q}.  You may not be
-able to change this value---the hardware may insist on using @kbd{C-q}
-regardless of what you specify.
+The usual value for the START character is @kbd{C-q} (@code{0x11}).
+You may not be able to change this value---the hardware may insist on
+using @kbd{C-q} regardless of what you specify.
 @end deftypevr
 
 @deftypevr Macro int VSTOP
@@ -1728,9 +1758,9 @@ output to be suspended; the STOP character itself is discarded.  If
 @code{IXOFF} is set, the system may also transmit STOP characters to the
 terminal, to prevent the input queue from overflowing.
 
-The usual value for the STOP character is @kbd{C-s}.  You may not be
-able to change this value---the hardware may insist on using @kbd{C-s}
-regardless of what you specify.
+The usual value for the STOP character is @kbd{C-s} (@code{0x13}).
+You may not be able to change this value---the hardware may insist on
+using @kbd{C-s} regardless of what you specify.
 @end deftypevr
 
 @node Other Special
@@ -2101,8 +2131,10 @@ output would be confusing.  Unfortunately, the name @code{tcflush} comes
 from POSIX and we cannot change it.
 @end deftypefun
 
+@cindex software flow control, terminal
+@cindex terminal flow control, software
 @cindex flow control, terminal
-@cindex terminal flow control
+@cindex XON/XOFF flow control
 @deftypefun int tcflow (int @var{filedes}, int @var{action})
 @standards{POSIX.1, termios.h}
 @safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acsafe{}}
@@ -2111,17 +2143,18 @@ from POSIX and we cannot change it.
 @c the c_cc character corresponding to the action; there's a window for
 @c another thread to change the xon/xoff characters.
 The @code{tcflow} function is used to perform operations relating to
-XON/XOFF flow control on the terminal file specified by @var{filedes}.
+software flow control on the terminal file specified by
+@var{filedes}.
 
 The @var{action} argument specifies what operation to perform, and can
 be one of the following values:
 
 @vtable @code
 @item TCOOFF
-Suspend transmission of output.
+Suspend transmission of output, as if a STOP character had been received.
 
 @item TCOON
-Restart transmission of output.
+Restart transmission of output, as if a START character had been received.
 
 @item TCIOFF
 Transmit a STOP character.
@@ -2130,8 +2163,8 @@ Transmit a STOP character.
 Transmit a START character.
 @end vtable
 
-For more information about the STOP and START characters, see @ref{Special
-Characters}.
+For more information about the STOP and START characters, see
+@ref{Start/Stop Characters}.
 
 The return value is normally zero.  In the event of an error, a value
 of @math{-1} is returned.  The following @code{errno} error conditions
-- 
2.50.1