[PATCH v2 1/4] dt-bindings: ttyvs: document serial null modem driver bindings

From: Rishi Gupta
Date: Sat Feb 15 2020 - 12:51:43 EST


The ttyvs driver creates virtual tty devices. These devices can
also be created through device tree. This commit document this.

Signed-off-by: Rishi Gupta <gupt21@xxxxxxxxx>
---
Changes in v2:
- Made dev-num property mandatory
- Removed descriptions not needed due to driver changes

.../devicetree/bindings/serial/ttyvs.yaml | 165 +++++++++++++++++++++
1 file changed, 165 insertions(+)
create mode 100644 Documentation/devicetree/bindings/serial/ttyvs.yaml

diff --git a/Documentation/devicetree/bindings/serial/ttyvs.yaml b/Documentation/devicetree/bindings/serial/ttyvs.yaml
new file mode 100644
index 0000000..c919424
--- /dev/null
+++ b/Documentation/devicetree/bindings/serial/ttyvs.yaml
@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/serial/ttyvs.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Virtual multi-port serial card DT bindings
+
+maintainers:
+ - Rishi Gupta <gupt21@xxxxxxxxx>
+
+description: |
+ The ttyvs driver creates a virtual card which can have 0 to 65535
+ virtual tty devices. The card is modelled as a node with zero or more
+ child nodes each representing a virtual tty device. These devices
+ can be configured to be a loop-back type device or it can be part of
+ a null-modem pair.
+
+ Devices can be created by defining properties required to instantiate
+ a device (see examples Ex1/2/3 at the end). More information about
+ how to use this driver is here Documentation/virtual/tty-ttyvs.rst
+
+properties:
+ compatible:
+ const: ttyvs,virtual-uart-card
+
+ max-num-vs-devs:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - minimum: 0
+ - maximum: 0xffff
+ maxItems: 1
+ description:
+ By default, the driver can create upto 64 devices. This number can
+ be changed by passing 'max_num_vs_devs' module parameter to the driver
+ or by defining 'max-num-vs-devs' DT property. If both are used then
+ driver updates itself to support total number of devices as defined
+ by max-num-vs-devs property.
+
+patternProperties:
+ "^ttyvs@[0-9]+$":
+ type: object
+ description:
+ Node representing one virtual tty device. This describes, device
+ number and its configuration.
+
+ properties:
+ dev-num:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - minimum: 0
+ - maximum: 65534
+ maxItems: 1
+ description:
+ Specifies index (N in /dev/ttyvsN) to use for creating device.
+ Valid value for dev-num is from 0 to 65534.
+
+ rtsmap:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ - enum: [1, 6, 8, 9]
+ maxItems: 1
+ description:
+ Specifies to which pin(s) RTS pin of this device should be
+ connected. Valid values are pin 1 (DCD), pin 6 (DSR), pin 8
+ (CTS) and pin 9 (RI). If this is not used then RTS pin is
+ left unconnected.
+
+ dtrmap:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ - enum: [1, 6, 8, 9]
+ maxItems: 1
+ description:
+ Specifies to which pin(s) DTR pin of this device should be
+ connected. Valid values are pin 1 (DCD), pin 6 (DSR), pin 8
+ (CTS) and pin 9 (RI). If this is not used then DTR pin is
+ left unconnected.
+
+ set-dtr-at-open:
+ type: boolean
+ description:
+ If used, DTR signal will be asserted by driver when device
+ node is opened by user space application.
+
+ peer-dev:
+ $ref: /schemas/types.yaml#definitions/phandle
+ description:
+ Phandle to the peer DT node if this node is part of a null
+ modem pair.
+
+required:
+ - compatible
+ - dev-num
+
+examples:
+ - |
+ # Ex1; Null-modem pair only TX/RX connected
+ # /dev/ttvs0 <---> /dev/ttyvs1
+ # TX (3) ----> (2) RX
+ # RX (2) <---- (3) TX
+
+ ttyvs-card@0 {
+ compatible = "ttyvs,virtual-uart-card";
+
+ ttyvs0: ttyvs0 {
+ dev-num = <0>;
+ peer-dev = <&ttyvs1>;
+ };
+
+ ttyvs1: ttyvs1 {
+ dev-num = <1>;
+ peer-dev = <&ttyvs0>;
+ };
+ };
+
+ - |
+ # Ex2; Standard loop-back device
+ # TX (3) -->|
+ # RX (2) <--|
+
+ ttyvs-card@0 {
+ compatible = "ttyvs,virtual-uart-card";
+ ttyvs2 {
+ dev-num = <2>;
+ rtsmap = <8>;
+ dtrmap = <1 6>;
+ set-dtr-at-open;
+ };
+ };
+
+ - |
+ # Ex3; Standard null-modem pair for hardware flow control
+ # 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) <-+
+
+ ttyvs-card@0 {
+ compatible = "ttyvs,virtual-uart-card";
+ max-num-vs-devs = <128>;
+
+ ttyvs3: ttyvs3 {
+ dev-num = <3>;
+ rtsmap = <8>;
+ dtrmap = <1 6>;
+ set-dtr-at-open;
+ peer-dev = <&ttyvs4>;
+ };
+
+ ttyvs4: ttyvs4 {
+ dev-num = <4>;
+ rtsmap = <8>;
+ dtrmap = <1 6>;
+ set-dtr-at-open;
+ peer-dev = <&ttyvs3>;
+ };
+ };
+...
--
2.7.4