[RFCv3 PATCH 1/2] dt-bindings: bus: add Wiegand bus dt documentation

[Martin Zaťovič]

This patch documents the devicetree entry for a Wiegand bus.
A Wiegand bus follows the Wiegand protocol. The bus claims two GPIO
lines over which the communication is realized. It also introduces
parameters to control the pulse durations and the length of a gap
after finishing sending a frame.

Signed-off-by: Martin Zaťovič <m.zatovic1@xxxxxxxxx>
---
 .../devicetree/bindings/bus/wiegand.yaml      | 75 +++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/bus/wiegand.yaml

diff --git a/Documentation/devicetree/bindings/bus/wiegand.yaml b/Documentation/devicetree/bindings/bus/wiegand.yaml
new file mode 100644
index 000000000000..cc8d3c46bcde
--- /dev/null
+++ b/Documentation/devicetree/bindings/bus/wiegand.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/bus/wiegand.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Wiegand Bus
+
+maintainers:
+  - Martin Zaťovič <m.zatovic1@xxxxxxxxx>
+
+description: |
+  Wiegand interface is a wiring standard popularized in the 1980s. To this day
+  many card readers, fingerprint readers, sensors, etc. use Wiegand interface
+  particularly for access control applications. It utilizes two wires to
+  transmit the data - D0 and D1.
+
+  Both data lines are initially pulled up. To send a bit of value 1, the D1
+  line is set low. Similarly to send a bit of value 0, the D0 line is set low.
+
+properties:
+  $nodename:
+    pattern: "^wiegand(@.*|-[0-9a-f])*$"
+
+  compatible:
+    contains:
+      const: wiegand
+
+  data-hi-gpios:
+    description: GPIO spec for data-hi line to use. This line is initially
+      pulled up to high value. Wiegand write of a bit of value 1 results in
+      this line being pulled down for pulse length duration.
+    maxItems: 1
+
+  data-lo-gpios:
+    description: GPIO spec for data-lo line to use. This line is initially
+      pulled up to high value. Wiegand write of a bit of value 0 results in
+      this line being pulled down for pulse length duration.
+    maxItems: 1
+
+  pulse-len:
+    description: length of the low pulse for both data-lo and data-hi lines.
+    maxItems: 1
+
+  interval-len:
+    description: length of a whole bit (both the pulse and the high phase) for
+      both data-hi and data-lo lines in usecs; defaults to 2000us.
+    maxItems: 1
+
+  frame-gap:
+    description: length of the last bit of a frame (both the pulse and the high
+      phase) in usec; defaults to 2000us.
+    maxItems: 1
+
+required:
+  - compatible
+  - data-hi-gpios
+  - data-lo-gpios
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+
+    wiegand {
+        compatible = "wiegand";
+        data-hi-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
+        data-lo-gpios = <&gpio 6 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
+        pulse-len = <100>;
+        interval-len = <2500>;
+        frame-gap = <4000>;
+    };
+
+...
--
2.37.3