Re: [PATCH v2] tty/serial: Add a serial port simulator

[Randy Dunlap <rdunlap@infradead.org>]

Hi Corey,

Just some doc comments.

On 3/5/19 9:12 AM, minyard@acm.org wrote:
> diff --git a/Documentation/serial/serialsim.rst b/Documentation/serial/serialsim.rst
> new file mode 100644
> index 000000000000..655e10b4908e
> --- /dev/null
> +++ b/Documentation/serial/serialsim.rst
> @@ -0,0 +1,149 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +=====================================
> +serialsim - A kernel serial simualtor
                               xxxxxxxxx
                        serial device simulator

> +=====================================
> +
> +:Author: Corey Minyard <minyard@mvista.com> / <minyard@acm.org>
> +
> +The serialsim device is a serial simulator with echo and pipe devices.
> +It is quite useful for testing programs that use serial ports.
> +
> +This attempts to emulate a basic serial device.  It uses the baud rate
> +and sends the bytes through the loopback or pipe at approximately the
> +speed it would on a normal serial device.
> +
> +There is a python interface to the special ioctls for controlling the
> +remote end of the termios in addition to the standard ioctl interface
> +documented below.  See https://github.com/cminyard/serialsim
> +
> +=====
> +Using
> +=====
> +
> +The serialsim.ko module creates two types of devices.  Echo devices
> +simply echo back the data to the same device.  These devices will
> +appear as /dev/ttyEcho<n>.
> +
> +Pipe devices will transfer the data between two devices.  The
> +devices will appear as /dev/ttyPipeA<n> and /dev/ttyPipeB<n>.  And

                                                                  Any

> +data written to PipeA reads from PipeB, and vice-versa.
> +
> +You may create an arbitrary number of devices by setting the
> +nr_echo ports and nr_pipe_ports module parameters.  The default is

   nr_echo_ports

> +four for both.

or for each.

> +
> +This driver supports modifying the modem control lines and
> +injecting various serial errors.  It also supports a simulated null
> +modem between the two pipes, or in a loopback on the echo device.
> +
> +By default a pipe or echo comes up in null modem configuration,
> +meaning that the DTR line is hooked to the DSR and CD lines on the
> +other side and the RTS line on one side is hooked to the CTS line
> +on the other side.
> +
> +The RTS and CTS lines don't currently do anything for flow control.
> +
> +You can modify null modem and control the lines individually
> +through an interface in /sys/class/tty/ttyECHO<n>/ctrl,
> +/sys/class/tty/ttyPipeA<n>/ctrl, and
> +/sys/class/tty/ttyPipeB<n>/ctrl.  The following may be written to
> +those files:
> +
> +[+-]nullmodem
> +    enable/disable null modem
> +
> +[+-]cd
> +    enable/disable Carrier Detect (no effect if +nullmodem)
> +
> +[+-]dsr
> +    enable/disable Data Set Ready (no effect if +nullmodem)
> +
> +[+-]cts
> +    enable/disable Clear To Send (no effect if +nullmodem)
> +
> +[+-]ring
> +    enable/disable Ring
> +
> +frame
> +    inject a frame error on the next byte
> +
> +parity
> +    inject a parity error on the next byte
> +
> +overrun
> +    inject an overrun error on the next byte
> +
> +The contents of the above files has the following format:

                                   have

> +
> +tty[Echo|PipeA|PipeB]<n>
> +    <mctrl values>
> +
> +where <mctrl values> is the modem control values above (not frame,
> +parity, or overrun) with the following added:
> +
> +[+-]dtr
> +    value of the Data Terminal Ready
> +
> +[+-]rts
> +    value of the Request To Send
> +
> +The above values are not settable through this interface, they are
> +set through the serial port interface itself.
> +
> +So, for instance, ttyEcho0 comes up in the following state::
> +
> +   # cat /sys/class/tty/ttyEcho0/ctrl
> +   ttyEcho0: +nullmodem -cd -dsr -cts -ring -dtr -rts
> +
> +If something connects, it will become::
> +
> +   ttyEcho0: +nullmodem +cd +dsr +cts -ring +dtr +rts
> +
> +To enable ring::
> +
> +   # echo "+ring" >/sys/class/tty/ttyEcho0/ctrl
> +   # cat /sys/class/tty/ttyEcho0/ctrl
> +   ttyEcho0: +nullmodem +cd +dsr +cts +ring +dtr +rts
> +
> +Now disable NULL modem and the CD line::
> +
> +   # echo "-nullmodem -cd" >/sys/class/tty/ttyEcho0/ctrl
> +   # cat /sys/class/tty/ttyEcho0/ctrl
> +   ttyEcho0: -nullmodem -cd -dsr -cts +ring -dtr -rts
> +
> +Note that these settings are for the side you are modifying.  So if
> +you set nullmodem on ttyPipeA0, that controls whether the DTR/RTS
> +lines from ttyPipeB0 affect ttyPipeA0.  It doesn't affect ttyPipeB's
> +modem control lines.
> +
> +The PIPEA and PIPEB devices also have the ability to set these
> +values for the other end via an ioctl.  The following ioctls are
> +available:
> +
> +TIOCSERSNULLMODEM
> +    Set the null modem value, the arg is a boolean.
> +
> +TIOCSERSREMMCTRL
> +    Set the modem control lines, bits 16-31 of the arg is

                                                          are

> +    a 16-bit mask telling which values to set, bits 0-15 are the
> +    actual values.  Settable values are TIOCM_CAR, TIOCM_CTS,
> +    TIOCM_DSR, and TIOC_RNG.  If NULLMODEM is set to true, then only
> +    TIOC_RNG is settable.  The DTR and RTS lines are not here, you can
> +    set them through the normal interface.
> +
> +TIOCSERSREMERR
> +    Send an error or errors on the next sent byte.  arg is
> +    a bitwise OR of (1 << TTY_xxx).  Allowed errors are TTY_BREAK,

is this better: (or I don't understand?)
       a bitwise OR of (1 << TTY_xxx) and one (or more of) the
       allowed error flags TTY_BREAK, TTY_FRAME, TTY_PARITY, and TTY_OVERRUN.

> +    TTY_FRAME, TTY_PARITY, and TTY_OVERRUN.
> +
> +TIOCSERGREMTERMIOS
> +    Return the termios structure for the other side of the pipe.
> +    arg is a pointer to a standard termios struct.
> +
> +TIOCSERGREMRS485
> +    Return the remote RS485 settings, arg is a pointer to a struct
> +    serial_rs485.
> +
> +Note that unlike the sysfs interface, these ioctls affect the other
> +end.  So setting nullmodem on the ttyPipeB0 interface sets whether
> +the DTR/RTS lines on ttyPipeB0 affect ttyPipeA0.


cheers.
-- 
~Randy