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

Rob Herring
2021-12-21T18:49:50Z

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