[PATCH 3/5 v7] dt-bindings: input: pwm-beeper: add documentation for volume devcetree bindings

[PATCH 3/5 v7] dt-bindings: input: pwm-beeper: add documentation for volume devcetree bindings

[Manuel Traut]

This patch adds the documentation for the devicetree bindings to set
the volume levels.

Signed-off-by: Frieder Schrempf <frieder.schrempf@kontron.de>
Signed-off-by: Manuel Traut <manuel.traut@mt.com>
Acked-by: Rob Herring <robh@kernel.org>
---
 .../devicetree/bindings/input/pwm-beeper.yaml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/devicetree/bindings/input/pwm-beeper.yaml b/Documentation/devicetree/bindings/input/pwm-beeper.yaml
index 24a40f0f77c1..fe1bbc10147b 100644
--- a/Documentation/devicetree/bindings/input/pwm-beeper.yaml
+++ b/Documentation/devicetree/bindings/input/pwm-beeper.yaml
@@ -28,6 +28,23 @@ properties:
 	beeper-hz:
 		description: bell frequency in Hz
 
+
+	volume-levels:
+		description: >
+			Array of PWM duty cycle values that correspond to
+			linear volume levels. These need to be in the range of
+			0 to 500, while 0 means 0% duty cycle (mute) and 500
+			means 50% duty cycle (max volume).
+			Please note that the actual volume of most beepers is
+			highly non-linear, which means that low volume levels
+			are probably somewhere in the range of 1 to 30 (0.1-3%
+			duty cycle).
+
+	default-volume-level:
+		description: >
+			The default volume level (index into the array defined
+			by the "volume-levels" property).
+
 required:
 	- compatible
 	- pwms
@@ -45,4 +62,6 @@ examples:
 			compatible = "pwm-beeper";
 			pwms = <&pwm0>;
 			amp-supply = <&beeper_amp>;
+			volume-levels = <0 8 20 40 500>;
+			default-volume-level = <4>;
 		};
-- 
2.39.0

Re: [PATCH 3/5 v7] dt-bindings: input: pwm-beeper: add documentation for volume devcetree bindings

[Krzysztof Kozlowski]

On 24/01/2023 17:41, Manuel Traut wrote:
> This patch adds the documentation for the devicetree bindings to set
> the volume levels.

Please use scripts/get_maintainers.pl to get a list of necessary people
and lists to CC.  It might happen, that command when run on an older
kernel, gives you outdated entries.  Therefore please be sure you base
your patches on recent Linux kernel. You did not cc anyone, so that
won't work.



Do not use "This commit/patch".
https://elixir.bootlin.com/linux/v5.17.1/source/Documentation/process/submitting-patches.rst#L95

Subject: drop second/last, redundant "documentation and "devicetree
bindings". The "dt-bindings" prefix is already stating that these are
bindings.

> 
> Signed-off-by: Frieder Schrempf <frieder.schrempf@kontron.de>
> Signed-off-by: Manuel Traut <manuel.traut@mt.com>
> Acked-by: Rob Herring <robh@kernel.org>
> ---
>  .../devicetree/bindings/input/pwm-beeper.yaml | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/input/pwm-beeper.yaml b/Documentation/devicetree/bindings/input/pwm-beeper.yaml
> index 24a40f0f77c1..fe1bbc10147b 100644
> --- a/Documentation/devicetree/bindings/input/pwm-beeper.yaml
> +++ b/Documentation/devicetree/bindings/input/pwm-beeper.yaml
> @@ -28,6 +28,23 @@ properties:
>  	beeper-hz:
>  		description: bell frequency in Hz
>  
> +
> +	volume-levels:
> +		description: >
> +			Array of PWM duty cycle values that correspond to
> +			linear volume levels. These need to be in the range of
> +			0 to 500, while 0 means 0% duty cycle (mute) and 500
> +			means 50% duty cycle (max volume).
> +			Please note that the actual volume of most beepers is
> +			highly non-linear, which means that low volume levels
> +			are probably somewhere in the range of 1 to 30 (0.1-3%
> +			duty cycle).

Wrong indentation. This should use property units -percent. If it is not
percent, then missing ref.
https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml

I doubt this was even tested...

> +
> +	default-volume-level:
> +		description: >
> +			The default volume level (index into the array defined
> +			by the "volume-levels" property).

Same problem.

> +
>  required:

Best regards,
Krzysztof