Re: [PATCH v3 4/4] tty: documentation: document how to use ttyvs driver

[Randy Dunlap]

Hi,
A few changes for you to consider:


On 4/15/20 9:56 PM, Rishi Gupta wrote:
> The commit documents how to use ttyvs driver to create/delete
> virtual tty devices, how to emulate various serial port events
> through this driver etc.
> 
> Signed-off-by: Rishi Gupta <gupt21@xxxxxxxxx>
> ---
> Changes in v3:
> - Rebased on top of v5.7-rc1
> - Moved virtual-tty-ttyvs.rst from Documentation/virtual to Documentation/admin-guide
> 
> Changes in v2:
> - Added this file from v2 only
> 
>  Documentation/admin-guide/index.rst             |   1 +
>  Documentation/admin-guide/virtual-tty-ttyvs.rst | 142 ++++++++++++++++++++++++
>  2 files changed, 143 insertions(+)
>  create mode 100644 Documentation/admin-guide/virtual-tty-ttyvs.rst


> diff --git a/Documentation/admin-guide/virtual-tty-ttyvs.rst b/Documentation/admin-guide/virtual-tty-ttyvs.rst
> new file mode 100644
> index 0000000..c30b768
> --- /dev/null
> +++ b/Documentation/admin-guide/virtual-tty-ttyvs.rst
> @@ -0,0 +1,142 @@
> +================================================
> +Kernel driver for virtual tty null modem devices
> +================================================
> +
> +Author: Rishi Gupta <gupt21@xxxxxxxxx>
> +
> +The ttyvs driver (drivers/tty/ttyvs.c) creates virtual tty devices
> +that can be used with standard POSIX APIs for terminal devices.
> +
> +Applications can write to the sysfs file provided by this driver to
> +emulate various serial port communication events and error conditions.
> +
> +This driver creates a virtual card which can have 0 to 65535 virtual
> +tty devices.
> +
> +Use cases
> +=========
> +- Automated performance and scalability testing
> +- Serial port redirector to any other subsystem like TCP/IP
> +- Feeding data to GPS simulator
> +- Segregating hardware issues from software bugs quickly
> +- Serial port communication sniffer or test sniffer application itself
> +- Application development when hardware is still not available
> +- Testing user space drivers & corner case by injecting handcrafted data
> +- Migrate binary only or legacy applications to new communication medium
> +- Analyze and reverse-engineer serial protocols
> +- Cases where socat utility does not meet requirements for unix-like OS
> +- Cases where available physical serial ports don't meet requirements
> +- Product demo where data from hardware needs to be sent to the GUI app
> +- Stress and corner case testing of user space application
> +
> +How to create devices
> +=====================
> +There are two ways to create devices:
> +
> +1. Using device tree:
> +The card is modelled as a node with zero or more child nodes each
> +representing a virtual tty device. To create a device simply define
> +a child node with the required device parameters. This is explained
> +in detail in DT binding file:
> +Documentation/devicetree/bindings/serial/ttyvs.yaml
> +
> +2. Using configfs:
> +When ttyvs driver is loaded, it will create ttyvs directory inside
> +configfs mount point. For ex; if configfs is mounted at /config, then

                 either  For example,
                 or      E.g.,

> +/config/ttyvs directory will be created. To create a device, simply
> +create directory inside this, write values to be used as device
> +parameters and finally write 1 to create attribute. Defining ownidx
> +and devtype is mandatory.
> +
> +Pin mappings are bit maps; set bit 0 to connect a pin to CTS pin,
> +set bit 1 to connect to DCD pin, set bit 2 to connect to DSR and
> +set bit 3 to connect to RI. Pin naming conventions are follows
> +standard RS232 DB9 connector naming conventions.

A table would be better here IMO.

> +
> +An example to create a loop-back device with device number as 0

                          loopback

> +(/dev/ttyvs0), RTS and DTR pins unconnected, no need to assert DTR
> +when device is opened would be something like this:
> +
> +.. code-block:: sh
> +
> + mkdir /config/ttyvs/devlb-0
> + echo 0 > /config/ttyvs/devlb-0/ownidx
> + echo lb > /config/ttyvs/devlb-0/devtype
> + echo 0 > /config/ttyvs/devlb-0/ortsmap
> + echo 0 > /config/ttyvs/devlb-0/odtrmap
> + echo 0 > /config/ttyvs/devlb-0/odtratopn
> + echo 1 > /config/ttyvs/devlb-0/create
> +
> +An example to create a standard null modem pair with device numbers
> +0 and 1 with pin numbers as per RS232 standards will be something
> +like this:
> +
> +.. code-block:: sh
> +
> + /dev/ttyvs0        /dev/ttyvs1
> +   TX  (3)   ---->    (2) RX
> +   RX  (2)   <----    (3) TX
> +   RTS (7)   ---->    (8) CTS
> +   DTR (4)   --+->    (1) DCD
> +               +->    (6) DSR
> +   CTS (8)   <----    (7) RTS
> +   DCD (1)   <-+--    (4) DTR
> +   DSR (6)   <-+
> +
> + mkdir /config/ttyvs/devnm-0-1
> + echo nm > /config/ttyvs/devnm-0-1/devtype
> + echo 0 > /config/ttyvs/devnm-0-1/ownidx
> + echo 1 > /config/ttyvs/devnm-0-1/ortsmap
> + echo 6 > /config/ttyvs/devnm-0-1/odtrmap
> + echo 0 > /config/ttyvs/devnm-0-1/odtratopn
> + echo 1 > /config/ttyvs/devnm-0-1/peeridx
> + echo 1 > /config/ttyvs/devnm-0-1/prtsmap
> + echo 6 > /config/ttyvs/devnm-0-1/pdtrmap
> + echo 0 > /config/ttyvs/devnm-0-1/pdtratopn
> + echo 1 > /config/ttyvs/devnm-0-1/create
> +
> +Directory name devnm-0-1 can be user defined. We used this simple style
> +as it is intuitive to understand that the device is null modem with
> +numbers 0 and 1. Further, to use configfs based approach, kernel must
> +be compiled with CONFIG_CONFIGFS_FS=y option.
> +
> +How to delete devices
> +=====================
> +To delete a device created by configfs simply delete the directory
> +created in /config/ttyvs directory. If the device is part of a null
> +modem pair, peer device will also be deleted automatically.
> +
> +How to emulate events
> +=====================
> +When a virtual tty device is created, an event sysfs file will also
> +be created by the driver (/sys/class/tty/ttyvsN/event N is device
> +number).
> +
> +1. Emulating framing error: the driver inserts -7 in data buffer as
> +the byte that got corrupted due to framing error while receiving data.
> +To emulate this write 1 to /sys/class/tty/ttyvsN/event file.
> +
> +2. Emulating parity error: the driver inserts -8 in data buffer as
> +the byte that got corrupted due to parity error while receiving data.
> +To emulate this write 2 to /sys/class/tty/ttyvsN/event file.
> +
> +3. Emulating overrun error: the driver reports to tty layer that an
> +overrun has happened.To emulate this write 3 to /sys/class/tty/ttyvsN/event

               happened. To

> +file.
> +
> +4. Emulating ring indication: to emulate as if ring indication has been
> +observed write 4 to the event file. To emulate as if ring indication has
> +been removed write 5 to the event file.
> +
> +5. Emulate break received: to emulate as if break condition has been received
> +write 6 to the /sys/class/tty/ttyvsN/event file.
> +
> +6. Emulate faulty cable: to emulate as if the cable is faulty write 7
> +to the event file. In this case data sent from sender will not be received
> +by the receiver end. To remove this condition write 8 to the event file.
> +
> +How to support more devices
> +===========================
> +By default ttyvs driver supports upto 64 devices. This can be

                                    up to

> +changed by passing module parameter max_num_vs_devs or by defining
> +max-num-vs-devs device tree property.
> 


thanks.
-- 
~Randy