Date:   Tue, 7 Dec 2021 15:12:54 -0600
From:   Rob Herring <robh@kernel.org>
To:     David Heidelberg <david@ixit.cz>
Cc:     Dmitry Torokhov <dmitry.torokhov@gmail.com>,
        Sebastian Reichel <sre@kernel.org>,
        ~okias/devicetree@lists.sr.ht, linux-input@vger.kernel.org,
        devicetree@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH] dt-bindings: input: pwm-vibrator: Convert txt bindings
 to yaml
Message-ID: <Ya/OVqLj5gbkBpuj@robh.at.kernel.org>
References: <20211127130941.38684-1-david@ixit.cz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20211127130941.38684-1-david@ixit.cz>
Precedence: bulk

On Sat, Nov 27, 2021 at 02:09:40PM +0100, David Heidelberg wrote:
> Converts txt binding to new YAML format and simplify example.
> 
> Signed-off-by: David Heidelberg <david@ixit.cz>
> ---
>  .../bindings/input/pwm-vibrator.txt           | 66 -------------------
>  .../bindings/input/pwm-vibrator.yaml          | 59 +++++++++++++++++
>  2 files changed, 59 insertions(+), 66 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/input/pwm-vibrator.txt
>  create mode 100644 Documentation/devicetree/bindings/input/pwm-vibrator.yaml
> 
> diff --git a/Documentation/devicetree/bindings/input/pwm-vibrator.txt b/Documentation/devicetree/bindings/input/pwm-vibrator.txt
> deleted file mode 100644
> index 88c775a3fe21..000000000000
> --- a/Documentation/devicetree/bindings/input/pwm-vibrator.txt
> +++ /dev/null
> @@ -1,66 +0,0 @@
> -* PWM vibrator device tree bindings
> -
> -Registers a PWM device as vibrator. It is expected, that the vibrator's
> -strength increases based on the duty cycle of the enable PWM channel
> -(100% duty cycle meaning strongest vibration, 0% meaning no vibration).
> -
> -The binding supports an optional direction PWM channel, that can be
> -driven at fixed duty cycle. If available this is can be used to increase
> -the vibration effect of some devices.
> -
> -Required properties:
> -- compatible: should contain "pwm-vibrator"
> -- pwm-names: Should contain "enable" and optionally "direction"
> -- pwms: Should contain a PWM handle for each entry in pwm-names
> -
> -Optional properties:
> -- vcc-supply: Phandle for the regulator supplying power
> -- direction-duty-cycle-ns: Duty cycle of the direction PWM channel in
> -                           nanoseconds, defaults to 50% of the channel's
> -			   period.
> -
> -Example from Motorola Droid 4:
> -
> -&omap4_pmx_core {
> -	vibrator_direction_pin: pinmux_vibrator_direction_pin {
> -		pinctrl-single,pins = <
> -		OMAP4_IOPAD(0x1ce, PIN_OUTPUT | MUX_MODE1) /* dmtimer8_pwm_evt (gpio_27) */
> -		>;
> -	};
> -
> -	vibrator_enable_pin: pinmux_vibrator_enable_pin {
> -		pinctrl-single,pins = <
> -		OMAP4_IOPAD(0X1d0, PIN_OUTPUT | MUX_MODE1) /* dmtimer9_pwm_evt (gpio_28) */
> -		>;
> -	};
> -};
> -
> -/ {
> -	pwm8: dmtimer-pwm {
> -		pinctrl-names = "default";
> -		pinctrl-0 = <&vibrator_direction_pin>;
> -
> -		compatible = "ti,omap-dmtimer-pwm";
> -		#pwm-cells = <3>;
> -		ti,timers = <&timer8>;
> -		ti,clock-source = <0x01>;
> -	};
> -
> -	pwm9: dmtimer-pwm {
> -		pinctrl-names = "default";
> -		pinctrl-0 = <&vibrator_enable_pin>;
> -
> -		compatible = "ti,omap-dmtimer-pwm";
> -		#pwm-cells = <3>;
> -		ti,timers = <&timer9>;
> -		ti,clock-source = <0x01>;
> -	};
> -
> -	vibrator {
> -		compatible = "pwm-vibrator";
> -		pwms = <&pwm9 0 1000000000 0>,
> -                       <&pwm8 0 1000000000 0>;
> -		pwm-names = "enable", "direction";
> -		direction-duty-cycle-ns = <1000000000>;
> -	};
> -};
> diff --git a/Documentation/devicetree/bindings/input/pwm-vibrator.yaml b/Documentation/devicetree/bindings/input/pwm-vibrator.yaml
> new file mode 100644
> index 000000000000..ec2466c63fe6
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/input/pwm-vibrator.yaml
> @@ -0,0 +1,59 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/input/pwm-vibrator.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +title: PWM vibrator
> +
> +maintainers:
> +  - Sebastian Reichel <sre@kernel.org>
> +
> +description: >
> +  Registers a PWM device as vibrator. It is expected, that the vibrator's
> +  strength increases based on the duty cycle of the enable PWM channel
> +  (100% duty cycle meaning strongest vibration, 0% meaning no vibration).
> +
> +  The binding supports an optional direction PWM channel, that can be
> +  driven at fixed duty cycle. If available this is can be used to increase
> +  the vibration effect of some devices.
> +
> +properties:
> +  compatible:
> +    const: pwm-vibrator
> +
> +  pwm-names:
> +    anyOf:
> +      - items:
> +          - const: enable
> +      - items:
> +          - const: enable
> +          - const: direction

This can be expressed with just the 2nd entry and 'minItems: 1'.

> +
> +  pwms:
> +    minItems: 1
> +    maxItems: 2
> +
> +  vcc-supply: true
> +
> +  direction-duty-cycle-ns:
> +    description: >
> +      Duty cycle of the direction PWM channel in nanoseconds,
> +      defaults to 50% of the channel's period.
> +
> +required:
> +  - compatible
> +  - pwm-names
> +  - pwms
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    vibrator {
> +        compatible = "pwm-vibrator";
> +        pwms = <&pwm9 0 1000000000 0>,
> +               <&pwm8 0 1000000000 0>;
> +        pwm-names = "enable", "direction";
> +        direction-duty-cycle-ns = <1000000000>;
> +    };
> -- 
> 2.33.0
> 
>