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

[Ian Lepore]

On Tue, 2018-08-14 at 13:52 +0000, Warner Losh wrote:
> 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?
> 

Now they're documented together with a different single driver of many
that supports the feature. This is implemented in the tty layer and
applies to all serial drivers, shouldn't it be documented in tty(4)?

-- Ian