Re: [PATCH 2/6] dt-bindings: regulator: pwm: Convert to json-schema

[Rob Herring <robh@kernel.org>]

On Fri, Dec 17, 2021 at 06:05:03PM +0100, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Convert the generic PWM regulator bindings from the free-form text
> format to json-schema.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  .../bindings/regulator/pwm-regulator.txt      |  92 -------------
>  .../bindings/regulator/pwm-regulator.yaml     | 121 ++++++++++++++++++
>  2 files changed, 121 insertions(+), 92 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/regulator/pwm-regulator.txt
>  create mode 100644 Documentation/devicetree/bindings/regulator/pwm-regulator.yaml
> 

> diff --git a/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml b/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml
> new file mode 100644
> index 000000000000..d87e8110989d
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/regulator/pwm-regulator.yaml
> @@ -0,0 +1,121 @@
> +# SPDX-License-Identifier: GPL-2.0-only
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/regulator/pwm-regulator.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Generic PWM Regulator
> +
> +maintainers:
> +  - Rob Herring <robh+dt@kernel.org>
> +  - Mark Brown <broonie@kernel.org>
> +
> +description: |
> +  Currently supports 2 modes of operation:
> +
> +    - Voltage Table: When in this mode, a voltage table (See below) of predefined voltage <=>
> +      duty-cycle values must be provided via DT. Limitations are that the regulator can only
> +      operate at the voltages supplied in the table. Intermediary duty-cycle values which would
> +      normally allow finer grained voltage selection are ignored and rendered useless. Although
> +      more control is given to the user if the assumptions made in continuous-voltage mode do not
> +      reign true.
> +
> +    - Continuous Voltage: This mode uses the regulator's maximum and minimum supplied voltages
> +      specified in the regulator-{min,max}-microvolt properties to calculate appropriate duty-cycle
> +      values. This allows for a much more fine grained solution when compared with voltage-table
> +      mode above. This solution does make an assumption that a %50 duty-cycle value will cause the
> +      regulator voltage to run at half way between the supplied max_uV and min_uV values.
> +
> +  NB: To be clear, if voltage-table is provided, then the device will be used
> +  in Voltage Table Mode.  If no voltage-table is provided, then the device will
> +  be used in Continuous Voltage Mode.
> +
> +  Any property defined as part of the core regulator binding can also be used. (See:
> +  ../regulator/regulator.txt)
> +
> +properties:
> +  compatible:
> +    const: pwm-regulator
> +
> +  pwms:
> +    $ref: "/schemas/types.yaml#/definitions/phandle-array"

Already has a type. Just need 'maxItems: 1'

> +    description: phandle and PWM specifier (see ../pwm/pwm.txt)
> +
> +  # Only required for Voltage Table Mode:
> +  voltage-table:
> +    description: Voltage and Duty-Cycle table consisting of 2 cells. The first cell is the voltage
> +      in microvolts (uV) and the second cell is duty-cycle in percent (%).
> +    $ref: "/schemas/types.yaml#/definitions/uint32-matrix"

items:
  maxItems: 2
  minItems: 2


> +
> +  # Optional properties for Continuous mode:
> +  pwm-dutycycle-unit:
> +    description: Integer value encoding the duty cycle unit. If not defined, <100> is assumed,
> +      meaning that pwm-dutycycle-range contains values expressed in percent.
> +    $ref: "/schemas/types.yaml#/definitions/uint32"
> +
> +  pwm-dutycycle-range:
> +    description: Should contain 2 entries. The first entry is encoding the dutycycle for
> +      regulator-min-microvolt and the second one the dutycycle for regulator-max-microvolt. Duty
> +      cycle values are expressed in pwm-dutycycle-unit. If not defined, <0 100> is assumed.
> +    $ref: "/schemas/types.yaml#/definitions/uint32-array"

maxItems: 2

> +
> +  # Optional properties:
> +  enable-gpios:
> +    description: GPIO to use to enable/disable the regulator

maxItems: 1

> +
> +  # from regulator.yaml
> +  regulator-enable-ramp-delay: true
> +  regulator-max-microvolt: true
> +  regulator-min-microvolt: true
> +  regulator-name: true
> +  regulator-ramp-delay: true
> +  regulator-settling-time-us: true

Given the other properties still missing, probably better to drop all 
these and use unevaluatedProperties.

> +  vin-supply: true
> +
> +allOf:
> +  - $ref: "regulator.yaml"
> +
> +additionalProperties: false
> +
> +required:
> +  - compatible
> +  - pwms
> +
> +examples:
> +  # Continuous Voltage With Enable GPIO:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    pwm_regulator {
> +        compatible = "pwm-regulator";
> +        pwms = <&pwm1 0 8448 0>;
> +        enable-gpios = <&gpio0 23 GPIO_ACTIVE_HIGH>;
> +        regulator-min-microvolt = <1016000>;
> +        regulator-max-microvolt = <1114000>;
> +        regulator-name = "vdd_logic";
> +        /* unit == per-mille */
> +        pwm-dutycycle-unit = <1000>;
> +        /*
> +         * Inverted PWM logic, and the duty cycle range is limited
> +         * to 30%-70%.
> +         */
> +        pwm-dutycycle-range = <700 300>; /* */
> +    };
> +
> +  # Voltage Table:
> +  - |
> +    regulator {
> +        compatible = "pwm-regulator";
> +        pwms = <&pwm1 0 8448 0>;
> +        regulator-min-microvolt = <1016000>;
> +        regulator-max-microvolt = <1114000>;
> +        regulator-name = "vdd_logic";
> +
> +        /* Voltage Duty-Cycle */
> +        voltage-table = <1114000 0>,
> +                        <1095000 10>,
> +                        <1076000 20>,
> +                        <1056000 30>,
> +                        <1036000 40>,
> +                        <1016000 50>;
> +    };
> -- 
> 2.34.1
> 
>