[1/2] dt-bindings: bus: simple-pm-bus: convert bindings to json-schema
diff mbox series

Message ID 20190916153357.3880-2-horms+renesas@verge.net.au
State Superseded
Delegated to: Geert Uytterhoeven
Headers show
Series
  • dt-bindings: bus: simple-pm-bus, renesas-bsc: convert bindings to json-schema
Related show

Commit Message

Simon Horman Sept. 16, 2019, 3:33 p.m. UTC
Convert Simple Power-Managed Bus bindings documentation to json-schema.

As a side effect of this change only simple-pm-bus is used in example. A
follow-up patch will provide an example for the separately documented
Renesas Bus State Controller (BSC) that uses "renesas,bsc-sh73a0" and
"renesas,bsc" compat strings.

Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
---
* Tested using:
  # ARCH=arm64 make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
  # ARCH=arm   make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
---
 .../devicetree/bindings/bus/simple-pm-bus.txt      | 44 --------------
 .../devicetree/bindings/bus/simple-pm-bus.yaml     | 68 ++++++++++++++++++++++
 2 files changed, 68 insertions(+), 44 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.txt
 create mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.yaml

Comments

Ulrich Hecht Sept. 17, 2019, 10:43 a.m. UTC | #1
> On September 16, 2019 at 5:33 PM Simon Horman <horms+renesas@verge.net.au> wrote:
> 
> 
> Convert Simple Power-Managed Bus bindings documentation to json-schema.
> 
> As a side effect of this change only simple-pm-bus is used in example. A
> follow-up patch will provide an example for the separately documented
> Renesas Bus State Controller (BSC) that uses "renesas,bsc-sh73a0" and
> "renesas,bsc" compat strings.
> 
> Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
> ---
> * Tested using:
>   # ARCH=arm64 make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
>   # ARCH=arm   make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> ---
>  .../devicetree/bindings/bus/simple-pm-bus.txt      | 44 --------------
>  .../devicetree/bindings/bus/simple-pm-bus.yaml     | 68 ++++++++++++++++++++++
>  2 files changed, 68 insertions(+), 44 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.txt
>  create mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> 
> diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt b/Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> deleted file mode 100644
> index 6f15037131ed..000000000000
> --- a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> +++ /dev/null
> @@ -1,44 +0,0 @@
> -Simple Power-Managed Bus
> -========================
> -
> -A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> -driver, as it's typically initialized by the boot loader.
> -
> -However, its bus controller is part of a PM domain, or under the control of a
> -functional clock.  Hence, the bus controller's PM domain and/or clock must be
> -enabled for child devices connected to the bus (either on-SoC or externally)
> -to function.
> -
> -While "simple-pm-bus" follows the "simple-bus" set of properties, as specified
> -in the Devicetree Specification, it is not an extension of "simple-bus".
> -
> -
> -Required properties:
> -  - compatible: Must contain at least "simple-pm-bus".
> -		Must not contain "simple-bus".
> -		It's recommended to let this be preceded by one or more
> -		vendor-specific compatible values.
> -  - #address-cells, #size-cells, ranges: Must describe the mapping between
> -		parent address and child address spaces.
> -
> -Optional platform-specific properties for clock or PM domain control (at least
> -one of them is required):
> -  - clocks: Must contain a reference to the functional clock(s),
> -  - power-domains: Must contain a reference to the PM domain.
> -Please refer to the binding documentation for the clock and/or PM domain
> -providers for more details.
> -
> -
> -Example:
> -
> -	bsc: bus@fec10000 {
> -		compatible = "renesas,bsc-sh73a0", "renesas,bsc",
> -			     "simple-pm-bus";
> -		#address-cells = <1>;
> -		#size-cells = <1>;
> -		ranges = <0 0 0x20000000>;
> -		reg = <0xfec10000 0x400>;
> -		interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
> -		clocks = <&zb_clk>;
> -		power-domains = <&pd_a4s>;
> -	};
> diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> new file mode 100644
> index 000000000000..72a3644974e3
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> @@ -0,0 +1,68 @@
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/bus/simple-pm-bus.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Simple Power-Managed Bus
> +
> +maintainers:
> +  - Geert Uytterhoeven <geert+renesas@glider.be>
> +
> +description: |
> +  A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> +  driver, as it's typically initialized by the boot loader.
> +
> +  However, its bus controller is part of a PM domain, or under the control
> +  of a functional clock.  Hence, the bus controller's PM domain and/or
> +  clock must be enabled for child devices connected to the bus (either
> +  on-SoC or externally) to function.
> +
> +  While "simple-pm-bus" follows the "simple-bus" set of properties, as
> +  specified in the Devicetree Specification, it is not an extension of
> +  "simple-bus".
> +
> +
> +properties:
> +  compatible:
> +    items:
> +       - const: simple-pm-bus
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 1
> +
> +  ranges:
> +    # Mapping between parent address and child address spaces.
> +    maxItems: 1
> +
> +  clocks:
> +    # Functional clocks
> +    # Required if power-domains is absent, optional otherwise
> +    minItems: 1
> +
> +  power-domains:
> +    # Required if clocks is absent, optional otherwise
> +    minItems: 1
> +
> +required:
> +  - compatible
> +  - '#address-cells'
> +  - '#size-cells'
> +  - ranges
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    bsc: bus@fec10000 {
> +        compatible = "simple-pm-bus";
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +        ranges = <0 0 0x20000000>;
> +        reg = <0xfec10000 0x400>;
> +        interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
> +        clocks = <&zb_clk>;
> +        power-domains = <&pd_a4s>;
> +    };
> -- 
> 2.11.0

Reviewed-by: Ulrich Hecht <uli+renesas@fpond.eu>

CU
Uli

>
Simon Horman Sept. 17, 2019, 11:29 a.m. UTC | #2
On Mon, Sep 16, 2019 at 05:33:56PM +0200, Simon Horman wrote:
> Convert Simple Power-Managed Bus bindings documentation to json-schema.
> 
> As a side effect of this change only simple-pm-bus is used in example. A
> follow-up patch will provide an example for the separately documented
> Renesas Bus State Controller (BSC) that uses "renesas,bsc-sh73a0" and
> "renesas,bsc" compat strings.
> 
> Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
> ---
> * Tested using:
>   # ARCH=arm64 make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
>   # ARCH=arm   make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> ---
>  .../devicetree/bindings/bus/simple-pm-bus.txt      | 44 --------------
>  .../devicetree/bindings/bus/simple-pm-bus.yaml     | 68 ++++++++++++++++++++++
>  2 files changed, 68 insertions(+), 44 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.txt
>  create mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> 
> diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt b/Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> deleted file mode 100644
> index 6f15037131ed..000000000000
> --- a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> +++ /dev/null
> @@ -1,44 +0,0 @@
> -Simple Power-Managed Bus
> -========================
> -
> -A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> -driver, as it's typically initialized by the boot loader.
> -
> -However, its bus controller is part of a PM domain, or under the control of a
> -functional clock.  Hence, the bus controller's PM domain and/or clock must be
> -enabled for child devices connected to the bus (either on-SoC or externally)
> -to function.
> -
> -While "simple-pm-bus" follows the "simple-bus" set of properties, as specified
> -in the Devicetree Specification, it is not an extension of "simple-bus".
> -
> -
> -Required properties:
> -  - compatible: Must contain at least "simple-pm-bus".
> -		Must not contain "simple-bus".
> -		It's recommended to let this be preceded by one or more
> -		vendor-specific compatible values.
> -  - #address-cells, #size-cells, ranges: Must describe the mapping between
> -		parent address and child address spaces.
> -
> -Optional platform-specific properties for clock or PM domain control (at least
> -one of them is required):
> -  - clocks: Must contain a reference to the functional clock(s),
> -  - power-domains: Must contain a reference to the PM domain.
> -Please refer to the binding documentation for the clock and/or PM domain
> -providers for more details.
> -
> -
> -Example:
> -
> -	bsc: bus@fec10000 {
> -		compatible = "renesas,bsc-sh73a0", "renesas,bsc",
> -			     "simple-pm-bus";
> -		#address-cells = <1>;
> -		#size-cells = <1>;
> -		ranges = <0 0 0x20000000>;
> -		reg = <0xfec10000 0x400>;
> -		interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
> -		clocks = <&zb_clk>;
> -		power-domains = <&pd_a4s>;
> -	};
> diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> new file mode 100644
> index 000000000000..72a3644974e3
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> @@ -0,0 +1,68 @@
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/bus/simple-pm-bus.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Simple Power-Managed Bus
> +
> +maintainers:
> +  - Geert Uytterhoeven <geert+renesas@glider.be>
> +
> +description: |
> +  A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> +  driver, as it's typically initialized by the boot loader.
> +
> +  However, its bus controller is part of a PM domain, or under the control
> +  of a functional clock.  Hence, the bus controller's PM domain and/or
> +  clock must be enabled for child devices connected to the bus (either
> +  on-SoC or externally) to function.
> +
> +  While "simple-pm-bus" follows the "simple-bus" set of properties, as
> +  specified in the Devicetree Specification, it is not an extension of
> +  "simple-bus".
> +
> +

There is an extra blank line above, I will plan to remove it in v2.

> +properties:
> +  compatible:
> +    items:
> +       - const: simple-pm-bus

The following patch, for Renesas BSC, also
describes the simple-pm-bus but also requires other compatible
strings to be present.

In order to facilitate that I tried the following:

   compatible:
      contains:
         const: simple-pm-bus
      additionalItems: true

This allows make dtbs_check DT_SCHEMA_FILES=.../simple-pm-bus.yaml to pass
in cases where there are more compat strings pesent. However
make dtbs_check DT_SCHEMA_FILES=...renesas,bsc.yaml (schema file
introduced in following patch) fails in the case
where the only compat string is simple-pm-bus.

make dtbs_check DT_SCHEMA_FILES=...renesas,bsc.yaml also fails
due to the reg property not being present for the same compat case,
which should be valid according to simple-pm-bus.yaml.

Does anyone have any guidance on how to proceed?

> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 1
> +
> +  ranges:
> +    # Mapping between parent address and child address spaces.
> +    maxItems: 1
> +
> +  clocks:
> +    # Functional clocks
> +    # Required if power-domains is absent, optional otherwise
> +    minItems: 1
> +
> +  power-domains:
> +    # Required if clocks is absent, optional otherwise
> +    minItems: 1
> +
> +required:
> +  - compatible
> +  - '#address-cells'
> +  - '#size-cells'
> +  - ranges
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    bsc: bus@fec10000 {
> +        compatible = "simple-pm-bus";
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +        ranges = <0 0 0x20000000>;
> +        reg = <0xfec10000 0x400>;
> +        interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
> +        clocks = <&zb_clk>;
> +        power-domains = <&pd_a4s>;
> +    };
> -- 
> 2.11.0
>
Rob Herring Sept. 17, 2019, 12:12 p.m. UTC | #3
On Mon, Sep 16, 2019 at 10:35 AM Simon Horman
<horms+renesas@verge.net.au> wrote:
>
> Convert Simple Power-Managed Bus bindings documentation to json-schema.
>
> As a side effect of this change only simple-pm-bus is used in example. A
> follow-up patch will provide an example for the separately documented
> Renesas Bus State Controller (BSC) that uses "renesas,bsc-sh73a0" and
> "renesas,bsc" compat strings.
>
> Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
> ---
> * Tested using:
>   # ARCH=arm64 make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
>   # ARCH=arm   make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> ---
>  .../devicetree/bindings/bus/simple-pm-bus.txt      | 44 --------------
>  .../devicetree/bindings/bus/simple-pm-bus.yaml     | 68 ++++++++++++++++++++++
>  2 files changed, 68 insertions(+), 44 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.txt
>  create mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.yaml

> diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> new file mode 100644
> index 000000000000..72a3644974e3
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> @@ -0,0 +1,68 @@

SPDX tag?

> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/bus/simple-pm-bus.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Simple Power-Managed Bus
> +
> +maintainers:
> +  - Geert Uytterhoeven <geert+renesas@glider.be>
> +
> +description: |
> +  A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> +  driver, as it's typically initialized by the boot loader.
> +
> +  However, its bus controller is part of a PM domain, or under the control
> +  of a functional clock.  Hence, the bus controller's PM domain and/or
> +  clock must be enabled for child devices connected to the bus (either
> +  on-SoC or externally) to function.
> +
> +  While "simple-pm-bus" follows the "simple-bus" set of properties, as
> +  specified in the Devicetree Specification, it is not an extension of
> +  "simple-bus".
> +
> +
> +properties:

Add $nodename in here.

> +  compatible:
> +    items:
> +       - const: simple-pm-bus

extra leading space.

> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 1

1 or 2 should be valid...

> +
> +  ranges:
> +    # Mapping between parent address and child address spaces.
> +    maxItems: 1

empty or multiple ranges should be possible.

> +
> +  clocks:
> +    # Functional clocks
> +    # Required if power-domains is absent, optional otherwise
> +    minItems: 1

This will imply maxItems is 1 which I don't think you want.

Though more than 1 starts to mean you need to know specifically what the h/w is.

> +
> +  power-domains:
> +    # Required if clocks is absent, optional otherwise
> +    minItems: 1
> +
> +required:
> +  - compatible
> +  - '#address-cells'
> +  - '#size-cells'
> +  - ranges

This will capture what you commented above:

oneOf:
  - required:
      - clocks
  - required:
      - power-domains

> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    bsc: bus@fec10000 {
> +        compatible = "simple-pm-bus";
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +        ranges = <0 0 0x20000000>;
> +        reg = <0xfec10000 0x400>;

If you have reg, then it shouldn't be "simple-pm-bus" unless you can
function without accessing the regs.

> +        interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;

Not documented?

> +        clocks = <&zb_clk>;
> +        power-domains = <&pd_a4s>;
> +    };
> --
> 2.11.0
>
Geert Uytterhoeven Sept. 17, 2019, 12:44 p.m. UTC | #4
Hi Rob,

On Tue, Sep 17, 2019 at 2:12 PM Rob Herring <robh+dt@kernel.org> wrote:
> On Mon, Sep 16, 2019 at 10:35 AM Simon Horman
> <horms+renesas@verge.net.au> wrote:
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/irq.h>
> > +
> > +    bsc: bus@fec10000 {
> > +        compatible = "simple-pm-bus";
> > +        #address-cells = <1>;
> > +        #size-cells = <1>;
> > +        ranges = <0 0 0x20000000>;
> > +        reg = <0xfec10000 0x400>;
>
> If you have reg, then it shouldn't be "simple-pm-bus" unless you can
> function without accessing the regs.

Typically the registers are set up by the boot loader.

But this is actually the example for renesas,bsc.txt.
Perhaps agnoc@0 in arch/arm64/boot/dts/qcom/msm8996.dtsi would
be more appropriate?

Gr{oetje,eeting}s,

                        Geert
Rob Herring Sept. 17, 2019, 12:48 p.m. UTC | #5
On Tue, Sep 17, 2019 at 6:29 AM Simon Horman <horms@verge.net.au> wrote:
>
> On Mon, Sep 16, 2019 at 05:33:56PM +0200, Simon Horman wrote:
> > Convert Simple Power-Managed Bus bindings documentation to json-schema.
> >
> > As a side effect of this change only simple-pm-bus is used in example. A
> > follow-up patch will provide an example for the separately documented
> > Renesas Bus State Controller (BSC) that uses "renesas,bsc-sh73a0" and
> > "renesas,bsc" compat strings.
> >
> > Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
> > ---
> > * Tested using:
> >   # ARCH=arm64 make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> >   # ARCH=arm   make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > ---
> >  .../devicetree/bindings/bus/simple-pm-bus.txt      | 44 --------------
> >  .../devicetree/bindings/bus/simple-pm-bus.yaml     | 68 ++++++++++++++++++++++
> >  2 files changed, 68 insertions(+), 44 deletions(-)
> >  delete mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> >  create mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt b/Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> > deleted file mode 100644
> > index 6f15037131ed..000000000000
> > --- a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> > +++ /dev/null
> > @@ -1,44 +0,0 @@
> > -Simple Power-Managed Bus
> > -========================
> > -
> > -A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> > -driver, as it's typically initialized by the boot loader.
> > -
> > -However, its bus controller is part of a PM domain, or under the control of a
> > -functional clock.  Hence, the bus controller's PM domain and/or clock must be
> > -enabled for child devices connected to the bus (either on-SoC or externally)
> > -to function.
> > -
> > -While "simple-pm-bus" follows the "simple-bus" set of properties, as specified
> > -in the Devicetree Specification, it is not an extension of "simple-bus".
> > -
> > -
> > -Required properties:
> > -  - compatible: Must contain at least "simple-pm-bus".
> > -             Must not contain "simple-bus".
> > -             It's recommended to let this be preceded by one or more
> > -             vendor-specific compatible values.
> > -  - #address-cells, #size-cells, ranges: Must describe the mapping between
> > -             parent address and child address spaces.
> > -
> > -Optional platform-specific properties for clock or PM domain control (at least
> > -one of them is required):
> > -  - clocks: Must contain a reference to the functional clock(s),
> > -  - power-domains: Must contain a reference to the PM domain.
> > -Please refer to the binding documentation for the clock and/or PM domain
> > -providers for more details.
> > -
> > -
> > -Example:
> > -
> > -     bsc: bus@fec10000 {
> > -             compatible = "renesas,bsc-sh73a0", "renesas,bsc",
> > -                          "simple-pm-bus";
> > -             #address-cells = <1>;
> > -             #size-cells = <1>;
> > -             ranges = <0 0 0x20000000>;
> > -             reg = <0xfec10000 0x400>;
> > -             interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
> > -             clocks = <&zb_clk>;
> > -             power-domains = <&pd_a4s>;
> > -     };
> > diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > new file mode 100644
> > index 000000000000..72a3644974e3
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > @@ -0,0 +1,68 @@
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/bus/simple-pm-bus.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Simple Power-Managed Bus
> > +
> > +maintainers:
> > +  - Geert Uytterhoeven <geert+renesas@glider.be>
> > +
> > +description: |
> > +  A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> > +  driver, as it's typically initialized by the boot loader.
> > +
> > +  However, its bus controller is part of a PM domain, or under the control
> > +  of a functional clock.  Hence, the bus controller's PM domain and/or
> > +  clock must be enabled for child devices connected to the bus (either
> > +  on-SoC or externally) to function.
> > +
> > +  While "simple-pm-bus" follows the "simple-bus" set of properties, as
> > +  specified in the Devicetree Specification, it is not an extension of
> > +  "simple-bus".
> > +
> > +
>
> There is an extra blank line above, I will plan to remove it in v2.
>
> > +properties:
> > +  compatible:
> > +    items:
> > +       - const: simple-pm-bus
>
> The following patch, for Renesas BSC, also
> describes the simple-pm-bus but also requires other compatible
> strings to be present.
>
> In order to facilitate that I tried the following:
>
>    compatible:
>       contains:
>          const: simple-pm-bus
>       additionalItems: true
>
> This allows make dtbs_check DT_SCHEMA_FILES=.../simple-pm-bus.yaml to pass
> in cases where there are more compat strings pesent. However
> make dtbs_check DT_SCHEMA_FILES=...renesas,bsc.yaml (schema file
> introduced in following patch) fails in the case
> where the only compat string is simple-pm-bus.
>
> make dtbs_check DT_SCHEMA_FILES=...renesas,bsc.yaml also fails
> due to the reg property not being present for the same compat case,
> which should be valid according to simple-pm-bus.yaml.
>
> Does anyone have any guidance on how to proceed?

You'll need a custom 'select' in renesas,bsc.yaml that leaves out
"simple-pm-bus". See "panel-lvds" users in linux-next for an example.

Rob
Simon Horman Sept. 19, 2019, 2:59 p.m. UTC | #6
On Tue, Sep 17, 2019 at 07:48:17AM -0500, Rob Herring wrote:
> On Tue, Sep 17, 2019 at 6:29 AM Simon Horman <horms@verge.net.au> wrote:
> > On Mon, Sep 16, 2019 at 05:33:56PM +0200, Simon Horman wrote:

...

> > > +properties:
> > > +  compatible:
> > > +    items:
> > > +       - const: simple-pm-bus
> >
> > The following patch, for Renesas BSC, also
> > describes the simple-pm-bus but also requires other compatible
> > strings to be present.
> >
> > In order to facilitate that I tried the following:
> >
> >    compatible:
> >       contains:
> >          const: simple-pm-bus
> >       additionalItems: true
> >
> > This allows make dtbs_check DT_SCHEMA_FILES=.../simple-pm-bus.yaml to pass
> > in cases where there are more compat strings pesent. However
> > make dtbs_check DT_SCHEMA_FILES=...renesas,bsc.yaml (schema file
> > introduced in following patch) fails in the case
> > where the only compat string is simple-pm-bus.
> >
> > make dtbs_check DT_SCHEMA_FILES=...renesas,bsc.yaml also fails
> > due to the reg property not being present for the same compat case,
> > which should be valid according to simple-pm-bus.yaml.
> >
> > Does anyone have any guidance on how to proceed?
> 
> You'll need a custom 'select' in renesas,bsc.yaml that leaves out
> "simple-pm-bus". See "panel-lvds" users in linux-next for an example.

Thanks, I think I have that working now.
Simon Horman Sept. 19, 2019, 3:10 p.m. UTC | #7
On Tue, Sep 17, 2019 at 07:12:16AM -0500, Rob Herring wrote:
> On Mon, Sep 16, 2019 at 10:35 AM Simon Horman
> <horms+renesas@verge.net.au> wrote:
> >
> > Convert Simple Power-Managed Bus bindings documentation to json-schema.
> >
> > As a side effect of this change only simple-pm-bus is used in example. A
> > follow-up patch will provide an example for the separately documented
> > Renesas Bus State Controller (BSC) that uses "renesas,bsc-sh73a0" and
> > "renesas,bsc" compat strings.
> >
> > Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
> > ---
> > * Tested using:
> >   # ARCH=arm64 make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> >   # ARCH=arm   make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > ---
> >  .../devicetree/bindings/bus/simple-pm-bus.txt      | 44 --------------
> >  .../devicetree/bindings/bus/simple-pm-bus.yaml     | 68 ++++++++++++++++++++++
> >  2 files changed, 68 insertions(+), 44 deletions(-)
> >  delete mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> >  create mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> 
> > diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > new file mode 100644
> > index 000000000000..72a3644974e3
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > @@ -0,0 +1,68 @@
> 
> SPDX tag?
> 
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/bus/simple-pm-bus.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Simple Power-Managed Bus
> > +
> > +maintainers:
> > +  - Geert Uytterhoeven <geert+renesas@glider.be>
> > +
> > +description: |
> > +  A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> > +  driver, as it's typically initialized by the boot loader.
> > +
> > +  However, its bus controller is part of a PM domain, or under the control
> > +  of a functional clock.  Hence, the bus controller's PM domain and/or
> > +  clock must be enabled for child devices connected to the bus (either
> > +  on-SoC or externally) to function.
> > +
> > +  While "simple-pm-bus" follows the "simple-bus" set of properties, as
> > +  specified in the Devicetree Specification, it is not an extension of
> > +  "simple-bus".
> > +
> > +
> > +properties:
> 
> Add $nodename in here.


For now I have gone with:

  $nodename:
    pattern: "^bus@[0-9a-f]+$"

But this implies updating both msm8996.dtsi and the proposed
example (see below) to use bus@ rather than agnoc@.

If this is the right way to to then perhaps it is best to use the
following until msm8996.dtsi is updated.

  $nodename:
    pattern: "^(bus|agnoc)@[0-9a-f]+$"

> 
> > +  compatible:
> > +    items:
> > +       - const: simple-pm-bus
> 
> extra leading space.
> 
> > +
> > +  '#address-cells':
> > +    const: 1
> > +
> > +  '#size-cells':
> > +    const: 1
> 
> 1 or 2 should be valid...
> 
> > +
> > +  ranges:
> > +    # Mapping between parent address and child address spaces.
> > +    maxItems: 1
> 
> empty or multiple ranges should be possible.
> 
> > +
> > +  clocks:
> > +    # Functional clocks
> > +    # Required if power-domains is absent, optional otherwise
> > +    minItems: 1
> 
> This will imply maxItems is 1 which I don't think you want.
> 
> Though more than 1 starts to mean you need to know specifically what the h/w is.

I have changed this to:

  clocks: true
    # Functional clocks
    # Required if power-domains is absent, optional otherwise

> > +
> > +  power-domains:
> > +    # Required if clocks is absent, optional otherwise
> > +    minItems: 1
> > +
> > +required:
> > +  - compatible
> > +  - '#address-cells'
> > +  - '#size-cells'
> > +  - ranges
> 
> This will capture what you commented above:
> 
> oneOf:
>   - required:
>       - clocks
>   - required:
>       - power-domains

Thanks. Unfortunately dtbs_check does not seem happy
if both clocks and power-domains are present.

# cr make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
...
/home/horms/projects/linux/renesas/arch/arm/boot/dts/r8a73a4-ape6evm.dt.yaml: bus@fec10000: {'compatible': ['renesas,bsc-r8a73a4', 'renesas,bsc', 'simple-pm-bus'], '#address-cells': [[1]], '#size-cells': [[1]], 'ranges': [[0, 0, 0, 536870912]], 'reg': [[0, 4274061312, 0, 1024]], 'clocks': [[27]], 'power-domains': [[15]], 'flash@0': {'compatible': ['cfi-flash', 'mtd-rom'], 'reg': [[0, 134217728]], 'bank-width': [[2]], 'partitions': {'compatible': ['fixed-partitions'], '#address-cells': [[1]], '#size-cells': [[1]], 'partition@0': {'label': ['uboot'], 'reg': [[0, 262144]], 'read-only': True}, 'partition@40000': {'label': ['uboot-env'], 'reg': [[262144, 262144]], 'read-only': True}, 'partition@80000': {'label': ['flash'], 'reg': [[524288, 133693440]]}}}, 'ethernet@8000000': {'compatible': ['smsc,lan9220', 'smsc,lan9115'], 'reg': [[134217728, 4096]], 'interrupt-parent': [[18]], 'interrupts': [[8, 4]], 'phy-mode': ['mii'], 'reg-io-width': [[4]], 'smsc,irq-active-high': True, 'smsc,irq-push
 -pull': True, 'vdd33a-supply': [[23]], 'vddvario-supply': [[28]]}, '$nodename': ['bus@fec10000']} is valid under each of {'required': ['power-domains']}, {'required': ['clocks']}
{'$filename': '/home/horms/projects/linux/renesas/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml',
 '$id': 'http://devicetree.org/schemas/bus/simple-pm-bus.yaml#',
 '$schema': 'http://devicetree.org/meta-schemas/core.yaml#',
 '$select_validator': <jsonschema.validators.create.<locals>.Validator object at 0x7fa9f2596048>,
 'oneOf': [{'required': ['clocks']}, {'required': ['power-domains']}],
 'patternProperties': {'pinctrl-[0-9]+': True},
 'properties': {'#address-cells': {'items': {'items': {'const': 1},
                                             'type': 'array'},
                                   'type': 'array'},
                '#size-cells': {'items': {'items': {'enum': [1, 2]},
                                          'type': 'array'},
                                'type': 'array'},
                '$nodename': {'additionalItems': False,
                              'items': [{'pattern': '^(bus|agnoc)(@.*|-[0-9a-f])*$'}],
                              'maxItems': 1,
                              'minItems': 1,
                              'type': 'array'},
                'clocks': True,
                'compatible': {'contains': {'const': 'simple-pm-bus'}},
                'phandle': True,
                'pinctrl-names': True,
                'power-domains': {'maxItems': 1, 'minItems': 1},
                'ranges': True,
                'status': True},
 'required': ['compatible', '#address-cells', '#size-cells', 'ranges'],
 'select': {'properties': {'compatible': {'contains': {'enum': ['simple-pm-bus']}}},
            'required': ['compatible']},
 'title': 'Simple Power-Managed Bus'}

> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/irq.h>
> > +
> > +    bsc: bus@fec10000 {
> > +        compatible = "simple-pm-bus";
> > +        #address-cells = <1>;
> > +        #size-cells = <1>;
> > +        ranges = <0 0 0x20000000>;
> > +        reg = <0xfec10000 0x400>;
> 
> If you have reg, then it shouldn't be "simple-pm-bus" unless you can
> function without accessing the regs.
> 
> > +        interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
> 
> Not documented?
> 
> > +        clocks = <&zb_clk>;
> > +        power-domains = <&pd_a4s>;
> > +    };

As per discussion elsewhere in this thread, I have updated this to the
example in msm8996.dtsi.

    agnoc@0 {
        power-domains = <&gcc AGGRE0_NOC_GDSC>;
        compatible = "simple-pm-bus";
        #address-cells = <1>;
        #size-cells = <1>;
        ranges;
    };

> > --
> > 2.11.0
> >
>
Rob Herring Sept. 19, 2019, 7:33 p.m. UTC | #8
On Thu, Sep 19, 2019 at 10:10 AM Simon Horman <horms@verge.net.au> wrote:
>
> On Tue, Sep 17, 2019 at 07:12:16AM -0500, Rob Herring wrote:
> > On Mon, Sep 16, 2019 at 10:35 AM Simon Horman
> > <horms+renesas@verge.net.au> wrote:
> > >
> > > Convert Simple Power-Managed Bus bindings documentation to json-schema.
> > >
> > > As a side effect of this change only simple-pm-bus is used in example. A
> > > follow-up patch will provide an example for the separately documented
> > > Renesas Bus State Controller (BSC) that uses "renesas,bsc-sh73a0" and
> > > "renesas,bsc" compat strings.
> > >
> > > Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
> > > ---
> > > * Tested using:
> > >   # ARCH=arm64 make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > >   # ARCH=arm   make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > > ---
> > >  .../devicetree/bindings/bus/simple-pm-bus.txt      | 44 --------------
> > >  .../devicetree/bindings/bus/simple-pm-bus.yaml     | 68 ++++++++++++++++++++++
> > >  2 files changed, 68 insertions(+), 44 deletions(-)
> > >  delete mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.txt
> > >  create mode 100644 Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> >
> > > diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > > new file mode 100644
> > > index 000000000000..72a3644974e3
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> > > @@ -0,0 +1,68 @@
> >
> > SPDX tag?
> >
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/bus/simple-pm-bus.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: Simple Power-Managed Bus
> > > +
> > > +maintainers:
> > > +  - Geert Uytterhoeven <geert+renesas@glider.be>
> > > +
> > > +description: |
> > > +  A Simple Power-Managed Bus is a transparent bus that doesn't need a real
> > > +  driver, as it's typically initialized by the boot loader.
> > > +
> > > +  However, its bus controller is part of a PM domain, or under the control
> > > +  of a functional clock.  Hence, the bus controller's PM domain and/or
> > > +  clock must be enabled for child devices connected to the bus (either
> > > +  on-SoC or externally) to function.
> > > +
> > > +  While "simple-pm-bus" follows the "simple-bus" set of properties, as
> > > +  specified in the Devicetree Specification, it is not an extension of
> > > +  "simple-bus".
> > > +
> > > +
> > > +properties:
> >
> > Add $nodename in here.
>
>
> For now I have gone with:
>
>   $nodename:
>     pattern: "^bus@[0-9a-f]+$"
>
> But this implies updating both msm8996.dtsi and the proposed
> example (see below) to use bus@ rather than agnoc@.
>
> If this is the right way to to then perhaps it is best to use the
> following until msm8996.dtsi is updated.

I prefer to leave the warning there.

>
>   $nodename:
>     pattern: "^(bus|agnoc)@[0-9a-f]+$"
>
> >
> > > +  compatible:
> > > +    items:
> > > +       - const: simple-pm-bus
> >
> > extra leading space.
> >
> > > +
> > > +  '#address-cells':
> > > +    const: 1
> > > +
> > > +  '#size-cells':
> > > +    const: 1
> >
> > 1 or 2 should be valid...
> >
> > > +
> > > +  ranges:
> > > +    # Mapping between parent address and child address spaces.
> > > +    maxItems: 1
> >
> > empty or multiple ranges should be possible.
> >
> > > +
> > > +  clocks:
> > > +    # Functional clocks
> > > +    # Required if power-domains is absent, optional otherwise
> > > +    minItems: 1
> >
> > This will imply maxItems is 1 which I don't think you want.
> >
> > Though more than 1 starts to mean you need to know specifically what the h/w is.
>
> I have changed this to:
>
>   clocks: true
>     # Functional clocks
>     # Required if power-domains is absent, optional otherwise
>
> > > +
> > > +  power-domains:
> > > +    # Required if clocks is absent, optional otherwise
> > > +    minItems: 1
> > > +
> > > +required:
> > > +  - compatible
> > > +  - '#address-cells'
> > > +  - '#size-cells'
> > > +  - ranges
> >
> > This will capture what you commented above:
> >
> > oneOf:
> >   - required:
> >       - clocks
> >   - required:
> >       - power-domains
>
> Thanks. Unfortunately dtbs_check does not seem happy
> if both clocks and power-domains are present.

I was thinking it was either or. Use 'anyOf' instead.


>
> # cr make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
> ...
> /home/horms/projects/linux/renesas/arch/arm/boot/dts/r8a73a4-ape6evm.dt.yaml: bus@fec10000: {'compatible': ['renesas,bsc-r8a73a4', 'renesas,bsc', 'simple-pm-bus'], '#address-cells': [[1]], '#size-cells': [[1]], 'ranges': [[0, 0, 0, 536870912]], 'reg': [[0, 4274061312, 0, 1024]], 'clocks': [[27]], 'power-domains': [[15]], 'flash@0': {'compatible': ['cfi-flash', 'mtd-rom'], 'reg': [[0, 134217728]], 'bank-width': [[2]], 'partitions': {'compatible': ['fixed-partitions'], '#address-cells': [[1]], '#size-cells': [[1]], 'partition@0': {'label': ['uboot'], 'reg': [[0, 262144]], 'read-only': True}, 'partition@40000': {'label': ['uboot-env'], 'reg': [[262144, 262144]], 'read-only': True}, 'partition@80000': {'label': ['flash'], 'reg': [[524288, 133693440]]}}}, 'ethernet@8000000': {'compatible': ['smsc,lan9220', 'smsc,lan9115'], 'reg': [[134217728, 4096]], 'interrupt-parent': [[18]], 'interrupts': [[8, 4]], 'phy-mode': ['mii'], 'reg-io-width': [[4]], 'smsc,irq-active-high': True, 'smsc,irq-push-pull': True, 'vdd33a-supply': [[23]], 'vddvario-supply': [[28]]}, '$nodename': ['bus@fec10000']} is valid under each of {'required': ['power-domains']}, {'required': ['clocks']}
> {'$filename': '/home/horms/projects/linux/renesas/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml',
>  '$id': 'http://devicetree.org/schemas/bus/simple-pm-bus.yaml#',
>  '$schema': 'http://devicetree.org/meta-schemas/core.yaml#',
>  '$select_validator': <jsonschema.validators.create.<locals>.Validator object at 0x7fa9f2596048>,
>  'oneOf': [{'required': ['clocks']}, {'required': ['power-domains']}],
>  'patternProperties': {'pinctrl-[0-9]+': True},
>  'properties': {'#address-cells': {'items': {'items': {'const': 1},
>                                              'type': 'array'},
>                                    'type': 'array'},
>                 '#size-cells': {'items': {'items': {'enum': [1, 2]},
>                                           'type': 'array'},
>                                 'type': 'array'},
>                 '$nodename': {'additionalItems': False,
>                               'items': [{'pattern': '^(bus|agnoc)(@.*|-[0-9a-f])*$'}],
>                               'maxItems': 1,
>                               'minItems': 1,
>                               'type': 'array'},
>                 'clocks': True,
>                 'compatible': {'contains': {'const': 'simple-pm-bus'}},
>                 'phandle': True,
>                 'pinctrl-names': True,
>                 'power-domains': {'maxItems': 1, 'minItems': 1},
>                 'ranges': True,
>                 'status': True},
>  'required': ['compatible', '#address-cells', '#size-cells', 'ranges'],
>  'select': {'properties': {'compatible': {'contains': {'enum': ['simple-pm-bus']}}},
>             'required': ['compatible']},
>  'title': 'Simple Power-Managed Bus'}
>
> > > +
> > > +examples:
> > > +  - |
> > > +    #include <dt-bindings/interrupt-controller/irq.h>
> > > +
> > > +    bsc: bus@fec10000 {
> > > +        compatible = "simple-pm-bus";
> > > +        #address-cells = <1>;
> > > +        #size-cells = <1>;
> > > +        ranges = <0 0 0x20000000>;
> > > +        reg = <0xfec10000 0x400>;
> >
> > If you have reg, then it shouldn't be "simple-pm-bus" unless you can
> > function without accessing the regs.
> >
> > > +        interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
> >
> > Not documented?
> >
> > > +        clocks = <&zb_clk>;
> > > +        power-domains = <&pd_a4s>;
> > > +    };
>
> As per discussion elsewhere in this thread, I have updated this to the
> example in msm8996.dtsi.
>
>     agnoc@0 {

s/agnoc/bus/

Also there shouldn't be a unit address unless there's 'reg' or non-empty ranges.

There's no reason that examples have to match anything real. Doing so
just invites pointless fixes to examples.

>         power-domains = <&gcc AGGRE0_NOC_GDSC>;
>         compatible = "simple-pm-bus";
>         #address-cells = <1>;
>         #size-cells = <1>;
>         ranges;
>     };
>
> > > --
> > > 2.11.0
> > >
> >
Simon Horman Sept. 23, 2019, 11:53 a.m. UTC | #9
On Thu, Sep 19, 2019 at 02:33:58PM -0500, Rob Herring wrote:
> On Thu, Sep 19, 2019 at 10:10 AM Simon Horman <horms@verge.net.au> wrote:
> >
> > On Tue, Sep 17, 2019 at 07:12:16AM -0500, Rob Herring wrote:
> > > On Mon, Sep 16, 2019 at 10:35 AM Simon Horman
> > > <horms+renesas@verge.net.au> wrote:

...

> > > > +
> > > > +  power-domains:
> > > > +    # Required if clocks is absent, optional otherwise
> > > > +    minItems: 1
> > > > +
> > > > +required:
> > > > +  - compatible
> > > > +  - '#address-cells'
> > > > +  - '#size-cells'
> > > > +  - ranges
> > >
> > > This will capture what you commented above:
> > >
> > > oneOf:
> > >   - required:
> > >       - clocks
> > >   - required:
> > >       - power-domains
> >
> > Thanks. Unfortunately dtbs_check does not seem happy
> > if both clocks and power-domains are present.
> 
> I was thinking it was either or. Use 'anyOf' instead.

Thanks, perhaps the tooling needs updating to handle this.

I now have:

required:
  - compatible
  - '#address-cells'
  - '#size-cells'
  - ranges

anyOf:
  - required:
      - clocks
  - required:
      - power-domains

And see:

# cr make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
...

Traceback (most recent call last):
  File "/usr/local/lib/python3.7/dist-packages/dtschema/lib.py", line 429, in process_schema
    DTValidator.check_schema(schema)
  File "/usr/local/lib/python3.7/dist-packages/dtschema/lib.py", line 575, in check_schema
    raise jsonschema.SchemaError.create_from(error)
jsonschema.exceptions.SchemaError: Additional properties are not allowed ('anyOf' was unexpected)

Failed validating 'additionalProperties' in metaschema['allOf'][0]:
    {'$id': 'http://devicetree.org/meta-schemas/base.yaml#',
     '$schema': 'http://json-schema.org/draft-07/schema#',
     'additionalProperties': False,
     'allOf': [{'$ref': 'http://json-schema.org/draft-07/schema#'}],
     'description': 'Metaschema for devicetree binding documentation',
     'properties': {'$id': {'pattern': 'http://devicetree.org/schemas/.*\\.yaml#'},
                    '$schema': {'enum': ['http://devicetree.org/meta-schemas/core.yaml#',
                                         'http://devicetree.org/meta-schemas/base.yaml#']},
                    'additionalProperties': {'type': 'boolean'},
                    'allOf': {'items': {'propertyNames': {'enum': ['$ref',
                                                                   'if',
                                                                   'then',
                                                                   'else']}}},
                    'definitions': True,
                    'dependencies': True,
                    'description': True,
                    'else': True,
                    'examples': {'items': {'type': 'string'},
                                 'type': 'array'},
                    'if': True,
                    'maintainers': {'items': {'format': 'email',
                                              'type': 'string'},
                                    'type': 'array'},
                    'oneOf': True,
                    'patternProperties': True,
                    'properties': True,
                    'required': True,
                    'select': {'allOf': [{'$ref': 'http://json-schema.org/draft-07/schema#'},
                                         {'oneOf': [{'properties': {'properties': True,
                                                                    'required': True},
                                                     'type': 'object'},
                                                    {'type': 'boolean'}]}]},
                    'then': True,
                    'title': {'maxLength': 100},
                    'unevaluatedProperties': {'type': 'boolean'}},
     'required': ['$id', '$schema', 'title', 'maintainers']}

On schema:
    {'$id': 'http://devicetree.org/schemas/bus/simple-pm-bus.yaml#',
     '$schema': 'http://devicetree.org/meta-schemas/core.yaml#',
     'anyOf': [{'required': ['clocks']}, {'required': ['power-domains']}],
     'description': 'A Simple Power-Managed Bus is a transparent bus that '
                    "doesn't need a real\n"
                    "driver, as it's typically initialized by the boot "
                    'loader.\n'
                    '\n'
                    'However, its bus controller is part of a PM domain, '
                    'or under the control\n'
                    "of a functional clock.  Hence, the bus controller's "
                    'PM domain and/or\n'
                    'clock must be enabled for child devices connected to '
                    'the bus (either\n'
                    'on-SoC or externally) to function.\n'
                    '\n'
                    'While "simple-pm-bus" follows the "simple-bus" set of '
                    'properties, as\n'
                    'specified in the Devicetree Specification, it is not '
                    'an extension of\n'
                    '"simple-bus".\n',
     'examples': ['#include <dt-bindings/clock/qcom,gcc-msm8996.h>\n'
                  '#include <dt-bindings/interrupt-controller/irq.h>\n'
                  '\n'
                  'bus@0 {\n'
                  '    power-domains = <&gcc AGGRE0_NOC_GDSC>;\n'
                  '    compatible = "simple-pm-bus";\n'
                  '    #address-cells = <1>;\n'
                  '    #size-cells = <1>;\n'
                  '    ranges;\n'
                  '};\n'],
     'maintainers': ['Geert Uytterhoeven <geert+renesas@glider.be>'],
     'properties': {'#address-cells': {'const': 1},
                    '#size-cells': {'enum': [1, 2]},
                    '$nodename': {'pattern': '^bus@[0-9a-f]+$'},
                    'clocks': True,
                    'compatible': {'contains': {'const': 'simple-pm-bus'},
                                   'description': 'Shall contain '
                                                  '"simple-pm-bus" in '
                                                  'addition to a optional '
                                                  'bus-specific compatible '
                                                  'strings defined in '
                                                  'individual pm-bus '
                                                  'bindings.'},
                    'power-domains': {'minItems': 1},
                    'ranges': True},
     'required': ['compatible', '#address-cells', '#size-cells', 'ranges'],
     'title': 'Simple Power-Managed Bus'}

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/local/bin/dt-mk-schema", line 32, in <module>
    schemas = dtschema.process_schemas(args.schemas, core_schema=(not args.useronly))
  File "/usr/local/lib/python3.7/dist-packages/dtschema/lib.py", line 470, in process_schemas
    sch = process_schema(os.path.abspath(filename))
  File "/usr/local/lib/python3.7/dist-packages/dtschema/lib.py", line 431, in process_schema
    print(filename + ": ignoring, error in schema '%s'" % exc.path[-1])
IndexError: deque index out of range
Rob Herring Sept. 23, 2019, 12:40 p.m. UTC | #10
On Mon, Sep 23, 2019 at 6:53 AM Simon Horman <horms@verge.net.au> wrote:
>
> On Thu, Sep 19, 2019 at 02:33:58PM -0500, Rob Herring wrote:
> > On Thu, Sep 19, 2019 at 10:10 AM Simon Horman <horms@verge.net.au> wrote:
> > >
> > > On Tue, Sep 17, 2019 at 07:12:16AM -0500, Rob Herring wrote:
> > > > On Mon, Sep 16, 2019 at 10:35 AM Simon Horman
> > > > <horms+renesas@verge.net.au> wrote:
>
> ...
>
> > > > > +
> > > > > +  power-domains:
> > > > > +    # Required if clocks is absent, optional otherwise
> > > > > +    minItems: 1
> > > > > +
> > > > > +required:
> > > > > +  - compatible
> > > > > +  - '#address-cells'
> > > > > +  - '#size-cells'
> > > > > +  - ranges
> > > >
> > > > This will capture what you commented above:
> > > >
> > > > oneOf:
> > > >   - required:
> > > >       - clocks
> > > >   - required:
> > > >       - power-domains
> > >
> > > Thanks. Unfortunately dtbs_check does not seem happy
> > > if both clocks and power-domains are present.
> >
> > I was thinking it was either or. Use 'anyOf' instead.
>
> Thanks, perhaps the tooling needs updating to handle this.

Indeed. Now fixed.

Rob
Simon Horman Sept. 24, 2019, 9:22 a.m. UTC | #11
On Mon, Sep 23, 2019 at 07:40:28AM -0500, Rob Herring wrote:
> On Mon, Sep 23, 2019 at 6:53 AM Simon Horman <horms@verge.net.au> wrote:
> >
> > On Thu, Sep 19, 2019 at 02:33:58PM -0500, Rob Herring wrote:
> > > On Thu, Sep 19, 2019 at 10:10 AM Simon Horman <horms@verge.net.au> wrote:
> > > >
> > > > On Tue, Sep 17, 2019 at 07:12:16AM -0500, Rob Herring wrote:
> > > > > On Mon, Sep 16, 2019 at 10:35 AM Simon Horman
> > > > > <horms+renesas@verge.net.au> wrote:
> >
> > ...
> >
> > > > > > +
> > > > > > +  power-domains:
> > > > > > +    # Required if clocks is absent, optional otherwise
> > > > > > +    minItems: 1
> > > > > > +
> > > > > > +required:
> > > > > > +  - compatible
> > > > > > +  - '#address-cells'
> > > > > > +  - '#size-cells'
> > > > > > +  - ranges
> > > > >
> > > > > This will capture what you commented above:
> > > > >
> > > > > oneOf:
> > > > >   - required:
> > > > >       - clocks
> > > > >   - required:
> > > > >       - power-domains
> > > >
> > > > Thanks. Unfortunately dtbs_check does not seem happy
> > > > if both clocks and power-domains are present.
> > >
> > > I was thinking it was either or. Use 'anyOf' instead.
> >
> > Thanks, perhaps the tooling needs updating to handle this.
> 
> Indeed. Now fixed.

Thanks, the above seems to be working nicely now.

Patch
diff mbox series

diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt b/Documentation/devicetree/bindings/bus/simple-pm-bus.txt
deleted file mode 100644
index 6f15037131ed..000000000000
--- a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt
+++ /dev/null
@@ -1,44 +0,0 @@ 
-Simple Power-Managed Bus
-========================
-
-A Simple Power-Managed Bus is a transparent bus that doesn't need a real
-driver, as it's typically initialized by the boot loader.
-
-However, its bus controller is part of a PM domain, or under the control of a
-functional clock.  Hence, the bus controller's PM domain and/or clock must be
-enabled for child devices connected to the bus (either on-SoC or externally)
-to function.
-
-While "simple-pm-bus" follows the "simple-bus" set of properties, as specified
-in the Devicetree Specification, it is not an extension of "simple-bus".
-
-
-Required properties:
-  - compatible: Must contain at least "simple-pm-bus".
-		Must not contain "simple-bus".
-		It's recommended to let this be preceded by one or more
-		vendor-specific compatible values.
-  - #address-cells, #size-cells, ranges: Must describe the mapping between
-		parent address and child address spaces.
-
-Optional platform-specific properties for clock or PM domain control (at least
-one of them is required):
-  - clocks: Must contain a reference to the functional clock(s),
-  - power-domains: Must contain a reference to the PM domain.
-Please refer to the binding documentation for the clock and/or PM domain
-providers for more details.
-
-
-Example:
-
-	bsc: bus@fec10000 {
-		compatible = "renesas,bsc-sh73a0", "renesas,bsc",
-			     "simple-pm-bus";
-		#address-cells = <1>;
-		#size-cells = <1>;
-		ranges = <0 0 0x20000000>;
-		reg = <0xfec10000 0x400>;
-		interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
-		clocks = <&zb_clk>;
-		power-domains = <&pd_a4s>;
-	};
diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
new file mode 100644
index 000000000000..72a3644974e3
--- /dev/null
+++ b/Documentation/devicetree/bindings/bus/simple-pm-bus.yaml
@@ -0,0 +1,68 @@ 
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/bus/simple-pm-bus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Simple Power-Managed Bus
+
+maintainers:
+  - Geert Uytterhoeven <geert+renesas@glider.be>
+
+description: |
+  A Simple Power-Managed Bus is a transparent bus that doesn't need a real
+  driver, as it's typically initialized by the boot loader.
+
+  However, its bus controller is part of a PM domain, or under the control
+  of a functional clock.  Hence, the bus controller's PM domain and/or
+  clock must be enabled for child devices connected to the bus (either
+  on-SoC or externally) to function.
+
+  While "simple-pm-bus" follows the "simple-bus" set of properties, as
+  specified in the Devicetree Specification, it is not an extension of
+  "simple-bus".
+
+
+properties:
+  compatible:
+    items:
+       - const: simple-pm-bus
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 1
+
+  ranges:
+    # Mapping between parent address and child address spaces.
+    maxItems: 1
+
+  clocks:
+    # Functional clocks
+    # Required if power-domains is absent, optional otherwise
+    minItems: 1
+
+  power-domains:
+    # Required if clocks is absent, optional otherwise
+    minItems: 1
+
+required:
+  - compatible
+  - '#address-cells'
+  - '#size-cells'
+  - ranges
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    bsc: bus@fec10000 {
+        compatible = "simple-pm-bus";
+        #address-cells = <1>;
+        #size-cells = <1>;
+        ranges = <0 0 0x20000000>;
+        reg = <0xfec10000 0x400>;
+        interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
+        clocks = <&zb_clk>;
+        power-domains = <&pd_a4s>;
+    };