--- linux-2.4.20-pre8/Documentation/serial-console.txt Tue Jun 20 05:26:07 2000
+++ linux-2.4.20-pre8-gdt1/Documentation/serial-console.txt Fri Oct 11 12:01:15 2002
@@ -102,3 +102,159 @@
the integration of these patches into m68k, ppc and alpha.
Miquel van Smoorenburg <miquels@cistron.nl>, 11-Jun-2000
+
+ ----------------
+
+ Serial console flow control
+
+The serial console now supports CTS-based flow control, along with DSR
+and DCD for status control. This is configured by appending a 'r' to
+the kernel paramater. For example
+
+ console=ttyS1,9600n8
+
+becomes
+
+ console=ttyS1,9600n8r
+
+I've no idea why Kanoj Sarcar, the flow control author, chose 'r'.
+Think of it as "Rigidly Interpreting the RS-232 Specification".
+
+The remote device must assert the incoming status lines Data Set Ready
+and Data Carrier Detect and the incoming flow control line Clear to
+Send before seeing any kernel-generated console output.
+
+When initializing the serial console the kernel asserts the outgoing
+status line Data Terminal Ready and the outgoing flow control line
+Ready to Send. A user-space application may later alter DTR or RTS
+(getty often clears and re-asserts DTR and RTS when initializing).
+
+Configuring status and flow control requires a correctly configured
+remote device and a correctly wired cable. In return disconnected
+devices do not see kernel messages and can use flow control to ensure
+that characters are not dropped from kernel-generated messages. This
+allows smart modems to be used reliably.
+
+The code has one pathological case. If DSR and DCD are cabled to be
+always asserted but there is no remote host present then CTS will be
+tested a million times before the pending kernel message is discarded.
+This is about a one second delay for each console message [1]. When
+wiring a null modem cable take care to avoid this case by powering DSR
+and DCD from the remote machine's DTR, not the local machine's DTR.
+
+Glen Turner
+2002-10-10
+
+ [1] If it is any consolation, in these circumstances a previous
+ version of flow control looped testing for about one second per
+ character in the message.
+
+ ----------------
+
+ sysctl variables
+
+Debugging RS-232 cabling on a remotely-located machine can be
+difficult, so a number of sysctl variables are maintained. These are
+located in the "dev.serialconsole" namespace, which can be found at
+
+ /proc/sys/dev/serialconsole/
+
+messages-total
+
+ The number of messages presented to the serial console
+
+ Expected values are 0 or greater.
+
+messages-dropped
+
+ The number of messages abandoned during output by the serial
+ console.
+
+ The reasons message were abandoned are counted in the timeouts-*
+ variables. Totalling the values in timeouts-* should match
+ messages-dropped.
+
+ The number of successfully output messages is (messages-total -
+ messages-dropped).
+
+ Expected values are integers of 0 or greater. When no flow
+ control is configured, the only source of update is
+ timeouts-transmit.
+
+timeouts-transmit
+maximum-attempts-transmit
+
+ The number of times when printing a character the UART's transmit
+ buffer, after being tested maximum-attempts-transmit times, is
+ still full. The character and the remainder of the messages is
+ abandoned and messages-dropped incremented.
+
+ The expected values of timeouts-transmit are integers of 0 or
+ greater. Values greater than 0 suggest a design or hardware fault
+ in the UART.
+
+ maximum-attempts-transmit can be altered, valid values are
+ integers greater than 1. Values that result in waiting for the
+ UART's transmit buffer for more than a second or so are not
+ recommended.
+
+timeouts-data-set-ready
+
+ When flow control is configured, the number of times when printing
+ a character the RS-232 signal Data Set Ready was not asserted.
+ The character and the remainder of the messages is abandoned and
+ messages-dropped incremented.
+
+ Expected value is 0 if flow control is not configued.
+
+ Expected values are integers of 0 or greater if flow control is
+ configured.
+
+ If the remote RS-232 device is disconnected then increments to
+ this variable or timeouts-data-carrier-detect are expected. If
+ the device is connected then increments suggest a cabling error or
+ a DSR status configuration error on the remote device.
+
+timeouts-data-carrier-detect
+
+ When flow control is configured, the number of times when printing
+ a character the RS-232 signal Data Carrier Detect was not
+ asserted. The character and the remainder of the messages is
+ abandoned and messages-dropped incremented.
+
+ Expected value is 0 if flow control is not configued.
+
+ Expected values are integers of 0 or greater if flow control is
+ configured.
+
+ If the remote RS-232 device is disconnected then increments to
+ this variable or timeouts-data-set-ready are expected. If the
+ device is connected then increments suggest a cabling error or a
+ DCD status configuration error on the remote device.
+
+timeouts-clear-to-send
+maximum-attempts-clear-to-send
+
+ When flow control is configured, the number of times when printing
+ a character the RS-232 signal Clear to Send, after being tested
+ maximum-attempts-clear-to-send times, is still not asserted. The
+ character and the remainder of the messages is abandoned and
+ messages-dropped incremented.
+
+ The expected values of timeouts-clear-to-send are integers of 0 or
+ greater. Values greater than 0 suggest a very slow RS-232 device,
+ a cabling error, or a handshaking configuration error on the
+ remote device.
+
+ maximum-attempts-clear-to-send can be altered, valid values are
+ integers greater than 1. Values that result in waiting for CTS
+ for more than a second or so are not recommended.
+
+ ----------------
+
+ Further documentation
+
+More information on configuring a serial console can be found in the
+Linux Documentation Project's "Remote Serial Console HOWTO".
+
+ http://www.tldp.org/HOWTO/Remote-Serial-Console-HOWTO/
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Tue Oct 15 2002 - 22:00:48 EST