[PATCH v1 1/3] dt-bindings: ttyvs: document serial null modem driver dt bindings

[Rishi Gupta <gupt21@gmail.com>]

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@gmail.com>
---
 .../devicetree/bindings/serial/ttyvs.yaml          | 175 +++++++++++++++++++++
 1 file changed, 175 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..d37c237
--- /dev/null
+++ b/Documentation/devicetree/bindings/serial/ttyvs.yaml
@@ -0,0 +1,175 @@
+# 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@gmail.com>
+
+description: |
+  The ttyvs driver creates a virtual card accessible through node
+  /dev/ttyvs_card. This card can have 0 to 65535 virtual tty devices.
+  The card is modeled 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 through DT (see examples Ex1/2/3 at the end)
+  or by writing pre-formatted string to card node.
+
+  If the driver is built as loadable module, standard null modem pairs
+  can be created by passing 'init_num_nm_pairs' parameter. Similarly,
+  standard loopback devices can be created by passing 'init_num_lb_devs'
+  parameter. When DT is used and device nodes are defined, all devices
+  created due to module parameters will be deleted first and then
+  devices specified by DT will be created.
+
+  Devices can be deleted only by writing pre-formatted string to card node,
+  irrespective of whether they were created using DT or through string.
+
+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' parameter to the driver or
+      by defining 'max-num-vs-devs' DT property. If both are used then
+      first all devices created during module loading are deleted, 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:
+      A node representing one virtual tty device. This node optionally,
+      describes, device number and its configuration.
+
+    properties:
+      dev-num:
+        allOf:
+          - $ref: /schemas/types.yaml#/definitions/uint32
+          - minimum: 0
+          - maximum: 0xffff
+        maxItems: 1
+        description:
+          Specifies index (N in /dev/ttyvsN) to use for creating device.
+          If this property is not specified then next lowest free index
+          is used by driver. Valid value for N is 0 to 65535.
+
+      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
+
+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