Re: [PATCH] dt-bindings: convert spmi.txt to spmi.yaml

From: Rob Herring
Date: Wed Aug 19 2020 - 19:08:21 EST

On Wed, Aug 19, 2020 at 05:20:06PM +0200, Mauro Carvalho Chehab wrote:
> Convert the SPMI bus documentation to JSON/yaml.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
>
> Rob,
>
> As promissed, this patch converts the spmi.txt generic bus bindings to
> html.

Thanks!

>
> .../bindings/mfd/qcom,spmi-pmic.txt | 2 +-
> .../bindings/spmi/qcom,spmi-pmic-arb.txt | 4 +-
> .../devicetree/bindings/spmi/spmi.txt | 41 ------------
> .../devicetree/bindings/spmi/spmi.yaml | 62 +++++++++++++++++++
> 4 files changed, 65 insertions(+), 44 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/spmi/spmi.txt
> create mode 100644 Documentation/devicetree/bindings/spmi/spmi.yaml
>
> diff --git a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.txt b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.txt
> index fffc8fde3302..79367a43b27d 100644
> --- a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.txt
> +++ b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.txt
> @@ -37,7 +37,7 @@ Required properties:
> or generalized "qcom,spmi-pmic".
> - reg: Specifies the SPMI USID slave address for this device.
> For more information see:
> - Documentation/devicetree/bindings/spmi/spmi.txt
> + Documentation/devicetree/bindings/spmi/spmi.yaml
>
> Required properties for peripheral child nodes:
> - compatible: Should contain "qcom,xxx", where "xxx" is a peripheral name.
> diff --git a/Documentation/devicetree/bindings/spmi/qcom,spmi-pmic-arb.txt b/Documentation/devicetree/bindings/spmi/qcom,spmi-pmic-arb.txt
> index e16b9b5afc70..ca645e21fe47 100644
> --- a/Documentation/devicetree/bindings/spmi/qcom,spmi-pmic-arb.txt
> +++ b/Documentation/devicetree/bindings/spmi/qcom,spmi-pmic-arb.txt
> @@ -7,8 +7,8 @@ devices to control a single SPMI master.
> The PMIC Arbiter can also act as an interrupt controller, providing interrupts
> to slave devices.
>
> -See spmi.txt for the generic SPMI controller binding requirements for child
> -nodes.
> +See Documentation/devicetree/bindings/spmi/spmi.yaml for the generic SPMI
> +controller binding requirements for child nodes.
>
> See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt for
> generic interrupt controller binding documentation.
> diff --git a/Documentation/devicetree/bindings/spmi/spmi.txt b/Documentation/devicetree/bindings/spmi/spmi.txt
> deleted file mode 100644
> index 4bb10d161a27..000000000000
> --- a/Documentation/devicetree/bindings/spmi/spmi.txt
> +++ /dev/null
> @@ -1,41 +0,0 @@
> -System Power Management Interface (SPMI) Controller
> -
> -This document defines a generic set of bindings for use by SPMI controllers. A
> -controller is modelled in device tree as a node with zero or more child nodes,
> -each representing a unique slave on the bus.
> -
> -Required properties:
> -- #address-cells : must be set to 2
> -- #size-cells : must be set to 0
> -
> -Child nodes:
> -
> -An SPMI controller node can contain zero or more child nodes representing slave
> -devices on the bus. Child 'reg' properties are specified as an address, type
> -pair. The address must be in the range 0-15 (4 bits). The type must be one of
> -SPMI_USID (0) or SPMI_GSID (1) for Unique Slave ID or Group Slave ID respectively.
> -These are the identifiers "statically assigned by the system integrator", as
> -per the SPMI spec.
> -
> -Each child node must have one and only one 'reg' entry of type SPMI_USID.
> -
> -#include <dt-bindings/spmi/spmi.h>
> -
> - spmi@.. {
> - compatible = "...";
> - reg = <...>;
> -
> - #address-cells = <2>;
> - #size-cells = <0>;
> -
> - child@0 {
> - compatible = "...";
> - reg = <0 SPMI_USID>;
> - };
> -
> - child@7 {
> - compatible = "...";
> - reg = <7 SPMI_USID
> - 3 SPMI_GSID>;
> - };
> - };
> diff --git a/Documentation/devicetree/bindings/spmi/spmi.yaml b/Documentation/devicetree/bindings/spmi/spmi.yaml
> new file mode 100644
> index 000000000000..8d72796b9bec
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/spmi/spmi.yaml
> @@ -0,0 +1,62 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/spmi/spmi.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: System Power Management Interface (SPMI) Controller
> +
> +maintainers:
> + - Josh Cartwright <joshc@xxxxxxxxxxxxxx>
> +
> +description: |
> + The System Power Management (SPMI) controller is a 2-wire bus defined
> + by the MIPI Alliance for power management control to be used on SoC designs.
> +
> + SPMI controllers are modelled in device tree using a generic set of
> + bindings defined here, plus any bus controller specific properties, if
> + needed.
> +
> + Each SPMI controller has zero or more child nodes (up to 16 ones), each
> + one representing an unique slave at the bus.
> +
> +properties:
> + $nodename:
> + pattern: "spmi@[0-9a-f]+"

Just "spmi@.*" as we shouldn't assume unit-address details of the parent
bus.

> +
> + compatible:
> + description: filled by the SPMI bus controller
> +
> + reg:
> + maxItems: 1

No need for 'reg' and 'compatible' here. Those will be covered by
specific SPMI controller schemas. But you do need:

"#address-cells":
const: 2

"#size-cells":
const: 0

> +
> +patternProperties:
> + "@([0-9]|1[0-5])$":

While buses define their own unit-address format, unit addresses are
normally hex.

> + description: up to 16 child PMIC nodes

type: object

Need to also define 'reg' constraints as defined by the bus:

properties:
reg:
minItems: 1
maxItems: 2 #??? Not sure about this. Is it 1 SPMI_USID and 1 \
SPMI_GSID entry at most?
items:
items:
- minimum: 0
maximum: 0xf
- enum: [ 0, 1 ]

> +
> +required:
> + - compatible
> + - reg
> +
> +examples:
> + - |
> + #include <dt-bindings/spmi/spmi.h>
> +
> + spmi@.. {
> + compatible = "...";
> + reg = <...>;

Example has to build now. Just drop these 2 properties.

> +
> + #address-cells = <2>;
> + #size-cells = <0>;
> +
> + child@0 {
> + compatible = "...";
> + reg = <0 SPMI_USID>;
> + };
> +
> + child@7 {
> + compatible = "...";
> + reg = <7 SPMI_USID
> + 3 SPMI_GSID>;
> + };
> + };
> --
> 2.26.2
>
>