diff mbox series

dt-bindings: convert spmi.txt to spmi.yaml

Message ID 94b055687143c9593cd4311f8bcda99a743a619f.1597850327.git.mchehab+huawei@kernel.org (mailing list archive)
State Superseded
Headers show
Series dt-bindings: convert spmi.txt to spmi.yaml | expand

Commit Message

Mauro Carvalho Chehab Aug. 19, 2020, 3:20 p.m. UTC
Convert the SPMI bus documentation to JSON/yaml.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

Rob,

As promissed, this patch converts the spmi.txt generic bus bindings to
html.

 .../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

Comments

Rob Herring Aug. 19, 2020, 10:38 p.m. UTC | #1
On Wed, 19 Aug 2020 17:20:06 +0200, Mauro Carvalho Chehab wrote:
> Convert the SPMI bus documentation to JSON/yaml.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> 
> Rob,
> 
> As promissed, this patch converts the spmi.txt generic bus bindings to
> html.
> 
>  .../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
> 


My bot found errors running 'make dt_binding_check' on your patch:

Error: Documentation/devicetree/bindings/spmi/spmi.example.dts:23.18-19 syntax error
FATAL ERROR: Unable to parse input tree
make[1]: *** [scripts/Makefile.lib:342: Documentation/devicetree/bindings/spmi/spmi.example.dt.yaml] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [Makefile:1367: dt_binding_check] Error 2


See https://patchwork.ozlabs.org/patch/1347886

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure dt-schema is up to date:

pip3 install git+https://github.com/devicetree-org/dt-schema.git@master --upgrade

Please check and re-submit.
Rob Herring Aug. 19, 2020, 11:08 p.m. UTC | #2
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@kernel.org>
> ---
> 
> 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@codeaurora.org>
> +
> +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
> 
>
Mauro Carvalho Chehab Aug. 25, 2020, 9:29 a.m. UTC | #3
Em Wed, 19 Aug 2020 17:08:12 -0600
Rob Herring <robh@kernel.org> escreveu:

> 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@kernel.org>
> > ---
> > 
> > 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@codeaurora.org>
> > +
> > +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.

Ok.

> 
> > +
> > +  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.

Ok. I was in doubt about those, as the original .txt file had it with
a <...>.

> But you do need:
> 
> "#address-cells":
>   const: 2
> 
> "#size-cells":
>   const: 0

Ok. 

> 
> > +
> > +patternProperties:
> > +  "@([0-9]|1[0-5])$":  
> 
> While buses define their own unit-address format, unit addresses are 
> normally hex.

I don't have a strong preference here. Yet, as this bus can have only up 
to 16 child (starting from 0), I guess decimal would make more sense.

> 
> > +    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?


I guess so. Currently, no devices use SPMI_GSID. I guess that we
can place maxItems: 2. If later needed, this could be changed in
the future.

>     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.

OK.

> 
> > +
> > +      #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
> > 
> >   



Thanks,
Mauro
Mauro Carvalho Chehab Aug. 26, 2020, 4:16 a.m. UTC | #4
Em Wed, 19 Aug 2020 17:08:12 -0600
Rob Herring <robh@kernel.org> escreveu:

> 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?


Each child have just one user ID (SPMI_USID). The group ID (SPMI_GSID) is an 
optional feature. From what I know, only one group ID is allowed at most.
So, maxItems: 2 makes sense.


>     items:
>       items:
>         - minimum: 0
>           maximum: 0xf
>         - enum: [ 0, 1 ]

If I use both maxItems:2 and the above, the example produces the following
error:

	/devel/v4l/temp/Documentation/devicetree/bindings/spmi/spmi.example.dt.yaml: spmi@0: child@7:reg: Additional items are not allowed ([3, 1] was unexpected)

(full DT file enclosed)

This seems to be some bug at the parsing logic, which seems to be refusing
to accept both "items" and "maxItems".

-

That's said, looking at the code[1], only SPMI_USID is currently supported:

		err = of_property_read_u32_array(node, "reg", reg, 2);
		if (err) {
			dev_err(&ctrl->dev,
				"node %pOF err (%d) does not have 'reg' property\n",
				node, err);
			continue;
		}

		if (reg[1] != SPMI_USID) {
			dev_err(&ctrl->dev,
				"node %pOF contains unsupported 'reg' entry\n",
				node);
			continue;
		}

		if (reg[0] >= SPMI_MAX_SLAVE_ID) {
			dev_err(&ctrl->dev, "invalid usid on node %pOF\n", node);
			continue;
		}

So, for now, using SPMI_GSID will fail.

[1] drivers/spmi/spmi.c

So, I'm inclined to define reg property as:

    properties:
      reg:
        minItems: 1
        maxItems: 2
        items:
          - minimum: 0
            maximum: 0xf
          - enum: [ 0 ]
            description: |
              0 means user ID address. 1 is reserved for group ID address.

And drop the group ID from the example. I'll send such version as a
second version of this patch.

Thanks,
Mauro


# 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@codeaurora.org>

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@.*"

  reg:
    maxItems: 1

  "#address-cells":
    const: 2

  "#size-cells":
    const: 0

patternProperties:
  ".*@([0-9]|1[0-5])$":
    description: up to 16 child PMIC nodes
    type: object

    properties:
      reg:
        minItems: 1
        maxItems: 2
        items:
          - minimum: 0
            maximum: 0xf
          - enum: [ 0, 1 ]

    required:
      - reg

required:
  - reg

examples:
  - |
    #include <dt-bindings/spmi/spmi.h>

    spmi@0 {
      reg = <0 0>;

      #address-cells = <2>;
      #size-cells = <0>;

      child@0 {
        reg = <0 SPMI_USID>;
      };

      child@7 {
        reg = <7 SPMI_USID>,
              <3 SPMI_GSID>;
      };
    };
diff mbox series

Patch

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@codeaurora.org>
+
+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]+"
+
+  compatible:
+    description: filled by the SPMI bus controller
+
+  reg:
+    maxItems: 1
+
+patternProperties:
+  "@([0-9]|1[0-5])$":
+    description: up to 16 child PMIC nodes
+
+required:
+  - compatible
+  - reg
+
+examples:
+  - |
+    #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>;
+      };
+    };