Re: [PATCH RFC v1 2/2] devicetree: bindings: bus: add Wiegand driver documentation

[Krzysztof Kozlowski]

On 28/07/2022 11:17, Martin Zaťovič wrote:
> Wiegand write-only driver requires definitions of two GPIO lines
> in the devicetree. This adds the documentation of their
> definitions.
> 

Subject prefix consistent with subsystem, so:
dt-bindings: bus: add Wiegand bus

There should be no references to drivers in bindings. Bindings also go
before the actual driver in the patchset.


> Signed-off-by: Martin Zaťovič <m.zatovic1@xxxxxxxxx>
> ---
>  .../devicetree/bindings/bus/wiegand-gpio.yaml | 66 +++++++++++++++++++
>  MAINTAINERS                                   |  1 +
>  2 files changed, 67 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/bus/wiegand-gpio.yaml
> 
> diff --git a/Documentation/devicetree/bindings/bus/wiegand-gpio.yaml b/Documentation/devicetree/bindings/bus/wiegand-gpio.yaml
> new file mode 100644
> index 000000000000..74733aadc61e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/bus/wiegand-gpio.yaml
> @@ -0,0 +1,66 @@
> +# SPDX-License-Identifier: GPL-2.0-only

Dual license please.

> +
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/bus/wiegand-gpio.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Wiegand write-only GPIO driver
> +
> +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.
> +  Standard Wiegand formats include 26, 36 and 37 bit and they reserve the first
> +  and last bits for parity. The first(MSB) parity bit is set to 1 if the parity
> +  of the first half of the payload is odd. The last(LSB) parity bit is set to 1
> +  if the parity of the second half of the payload even.
> +
> +properties:
> +  $nodename:
> +    pattern: "^wiegand-gpio(@[0-9a-f]+)?$"
> +
> +  compatible:
> +    contains:

Nope. See example-schema.

> +      const: gpio,wiegand-gpio
> +    description:
> +      Shall contain "wiegand-gpio" for the driver to match with this node.

No description. See example-schema.
> +
> +  wiegand-data-hi-gpios:

I propose just data-hi-gpios

> +    description:
> +      gpio used to transmit bits the value of which is 1, it should be
> +      flagged as active high with GPIO_ACTIVE_HIGH from
> +      <dt-bindings/gpio/gpio.h>.
> +    maxItems: 1
> +
> +  wiegand-data-lo-gpios:

data-lo-gpios

> +    description:
> +      gpio used to transmit bits the value of which is 1, it should be
> +      flagged as active high with GPIO_ACTIVE_HIGH from
> +      <dt-bindings/gpio/gpio.h>.
> +    maxItems: 1
> +
> +required:
> +  - compatible
> +  - wiegand-data-hi-gpios
> +  - wiegand-data-lo-gpios
> +
> +additionalProperties: true

Nope. This must be false, unless you create here a bus bindings. But in
such case you example is incomplete.

> +
> +examples:
> +  - |
> +    wiegand-gpio {

Just wiegand.

https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation

> +        compatible = "wiegand-gpio";
> +        pinctrl-names = "default";
> +        pinctrl-0 = <&pinctrl_uart1_wiegand>;
> +        wiegand-data-hi-gpios = <&gpio2 1 GPIO_ACTIVE_HIGH>;
> +        wiegand-data-lo-gpios = <&gpio2 2 GPIO_ACTIVE_HIGH>;
> +        status = "okay";

No need for status.

> +    };
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 9a519530e44e..c7db1e41cc02 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -21589,6 +21589,7 @@ F:	drivers/rtc/rtc-sd3078.c
>  WIEGAND WRITE-ONLY GPIO DRIVER
>  M:	Martin Zaťovič <m.zatovic1@xxxxxxxxx>
>  S:	Maintained
> +F:	Documentation/devicetree/bindings/bus/wiegand-gpio.yaml
>  F:	drivers/bus/wiegand-gpio.c
>  F:	drivers/bus/wiegand-gpio.h
>  


Best regards,
Krzysztof