svn commit: r337750 - head/share/man/man4

[Warner Losh]

Author: imp
Date: Tue Aug 14 13:52:10 2018
New Revision: 337750
URL: https://svnweb.freebsd.org/changeset/base/337750

Log:
  Add good description of init and lock devices from sio to uart.

Modified:
  head/share/man/man4/uart.4

Modified: head/share/man/man4/uart.4
==============================================================================
--- head/share/man/man4/uart.4	Tue Aug 14 13:52:08 2018	(r337749)
+++ head/share/man/man4/uart.4	Tue Aug 14 13:52:10 2018	(r337750)
@@ -225,6 +225,52 @@ Generally speaking, a connection to a DB-9 style conne
 level signal at up to 12 volts.
 A connection to header pins or an edge-connector on an embedded board
 is typically a TTL signal at 3.3 or 5 volts.
+.Sh Special Devices
+The
+.Nm
+driver also supports an initial-state and a lock-state control
+device for each of the callin and the callout "data" devices.
+The termios settings of a data device are copied
+from those of the corresponding initial-state device
+on first opens and are not inherited from previous opens.
+Use
+.Xr stty 1
+in the normal way on the initial-state devices to program
+initial termios states suitable for your setup.
+.Pp
+The lock termios state acts as flags to disable changing
+the termios state.
+E.g., to lock a flag variable such as CRTSCTS, use
+.Em stty crtscts
+on the lock-state device.
+Speeds and special characters
+may be locked by setting the corresponding value in the lock-state
+device to any nonzero value.
+E.g., to lock a speed to 115200, use
+.Dq Li stty 115200
+on the initial-state device and
+.Dq Li stty 1
+on the lock-state device.
+.Pp
+Correct programs talking to correctly wired external devices
+work with almost arbitrary initial states and almost no locking,
+but other setups may benefit from changing some of the default
+initial state and locking the state.
+In particular, the initial states for non (POSIX) standard flags
+should be set to suit the devices attached and may need to be
+locked to prevent buggy programs from changing them.
+E.g., CRTSCTS should be locked on for devices that support
+RTS/CTS handshaking at all times and off for devices that do not
+support it at all.
+CLOCAL should be locked on for devices that do not support carrier.
+HUPCL may be locked off if you do not
+want to hang up for some reason.
+In general, very bad things happen
+if something is locked to the wrong state, and things should not
+be locked for devices that support more than one setting.
+The CLOCAL flag on callin ports should be locked off for logins
+to avoid certain security holes, but this needs to be done by
+getty if the callin port is used for anything else.
 .Sh FILES
 .Bl -tag -width "/dev/ttyu?.init" -compact
 .It Pa /dev/ttyu?