[1/2] ASoC: dt-bindings: Add adi,ssm3515 amp schema

Message ID 20230509163828.86003-1-povik+lin@cutebit.org
State New
Headers
Series [1/2] ASoC: dt-bindings: Add adi,ssm3515 amp schema |

Commit Message

Martin Povišer May 9, 2023, 4:38 p.m. UTC
  Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
mono amplifier with digital input.

Signed-off-by: Martin Povišer <povik+lin@cutebit.org>
---
 .../bindings/sound/adi,ssm3515.yaml           | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
  

Comments

Conor Dooley May 9, 2023, 6:25 p.m. UTC | #1
Hey Martin,

On Tue, May 09, 2023 at 06:38:27PM +0200, Martin Povišer wrote:
> Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
> mono amplifier with digital input.
> 
> Signed-off-by: Martin Povišer <povik+lin@cutebit.org>
> ---
>  .../bindings/sound/adi,ssm3515.yaml           | 66 +++++++++++++++++++
>  1 file changed, 66 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
> 
> diff --git a/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml b/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
> new file mode 100644
> index 000000000000..19b7185ae8e2
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
> @@ -0,0 +1,66 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +# Copyright (C) 2019-20 Texas Instruments Incorporated

Copyright here looks a little odd, copy & paste from the TI bindings you
send patches for earlier, or intended?

> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/sound/adi,ssm3515.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"

Drop the quotes on these please.

> +
> +title: Analog Devices SSM3515 Audio Amplifier
> +
> +maintainers:
> +  - Martin Povišer <povik+lin@cutebit.org>
> +
> +description: |
> +  SSM3515 is a mono Class-D audio amplifier with digital input.
> +
> +  https://www.analog.com/media/en/technical-documentation/data-sheets/SSM3515.pdf
> +
> +allOf:
> +  - $ref: dai-common.yaml#
> +
> +properties:
> +  compatible:
> +    enum:
> +      - adi,ssm3515
> +
> +  reg:
> +    maxItems: 1
> +
> +  adi,ana-gain:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [0, 1, 2, 3]
> +    description: |
> +      The value to be set in the ANA_GAIN register field on the codec. This determines
> +      the full voltage span of the codec's analog output.
> +
> +      To quote the datasheet on the available options:
> +
> +        00: 8.4 V Full-Scale Gain Mapping
> +        01: 12.6 V Full-Scale Gain Mapping
> +        10: 14 V Full-Scale Gain Mapping
> +        11: 15 V Full-Scale Gain Mapping

Putting register values into the DT does not seem correct, although
I know nothing about sound and will have to defer to Krzysztof & Co. on
that front.

Cheers,
Conor.

> +
> +  '#sound-dai-cells':
> +    const: 0
> +
> +required:
> +  - compatible
> +  - reg
> +  - adi,ana-gain
> +
> +additionalProperties: true
> +
> +examples:
> +  - |
> +    i2c {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      codec@14 {
> +        compatible = "adi,ssm3515";
> +        reg = <0x14>;
> +        #sound-dai-cells = <0>;
> +        adi,ana-gain = <0>;
> +        sound-name-prefix = "Left Tweeter";
> +      };
> +    };
> -- 
> 2.38.3
>
  
Martin Povišer May 9, 2023, 7:38 p.m. UTC | #2
Hello Conor,

> On 9. 5. 2023, at 20:25, Conor Dooley <conor@kernel.org> wrote:
> 
> Hey Martin,
> 
> On Tue, May 09, 2023 at 06:38:27PM +0200, Martin Povišer wrote:
>> Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
>> mono amplifier with digital input.
>> 
>> Signed-off-by: Martin Povišer <povik+lin@cutebit.org>
>> ---
>> .../bindings/sound/adi,ssm3515.yaml           | 66 +++++++++++++++++++
>> 1 file changed, 66 insertions(+)
>> create mode 100644 Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
>> 
>> diff --git a/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml b/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
>> new file mode 100644
>> index 000000000000..19b7185ae8e2
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
>> @@ -0,0 +1,66 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +# Copyright (C) 2019-20 Texas Instruments Incorporated
> 
> Copyright here looks a little odd, copy & paste from the TI bindings you
> send patches for earlier, or intended?

Yeah, that must have been a copypaste from the other schemas. Not intended
in any case. Thanks for the catch.

> 
>> +%YAML 1.2
>> +---
>> +$id: "http://devicetree.org/schemas/sound/adi,ssm3515.yaml#"
>> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> 
> Drop the quotes on these please.

OK

>> +
>> +  adi,ana-gain:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    enum: [0, 1, 2, 3]
>> +    description: |
>> +      The value to be set in the ANA_GAIN register field on the codec. This determines
>> +      the full voltage span of the codec's analog output.
>> +
>> +      To quote the datasheet on the available options:
>> +
>> +        00: 8.4 V Full-Scale Gain Mapping
>> +        01: 12.6 V Full-Scale Gain Mapping
>> +        10: 14 V Full-Scale Gain Mapping
>> +        11: 15 V Full-Scale Gain Mapping
> 
> Putting register values into the DT does not seem correct, although
> I know nothing about sound and will have to defer to Krzysztof & Co. on
> that front.

It’s an analog gain selection, it just seemed most honest and convenient
to defer to the register field in describing of what this property does.

I thought this should be here, and not with the other gain controls to be
exported to userspace, since it relates to the supply voltage. You probably
can’t select a gain value close or over the amp’s supply and expect proper
functioning, so the value here should be the system’s integrator choice.

On second thought there doesn’t seem to be any risk of damage to the amp
itself, so the knowledge of what’s the optimal value could be left up to
ALSA use-case configuration, and there’s no real downside in treating it
like other gain controls.

I think I will remove it in the next iteration.

> Cheers,
> Conor.

Cheers, Martin
  
Mark Brown May 10, 2023, 2:10 a.m. UTC | #3
On Tue, May 09, 2023 at 09:38:46PM +0200, Martin Povišer wrote:
> > On 9. 5. 2023, at 20:25, Conor Dooley <conor@kernel.org> wrote:

> >> +        00: 8.4 V Full-Scale Gain Mapping
> >> +        01: 12.6 V Full-Scale Gain Mapping
> >> +        10: 14 V Full-Scale Gain Mapping
> >> +        11: 15 V Full-Scale Gain Mapping

> > Putting register values into the DT does not seem correct, although
> > I know nothing about sound and will have to defer to Krzysztof & Co. on
> > that front.

> I thought this should be here, and not with the other gain controls to be
> exported to userspace, since it relates to the supply voltage. You probably
> can’t select a gain value close or over the amp’s supply and expect proper
> functioning, so the value here should be the system’s integrator choice.

> On second thought there doesn’t seem to be any risk of damage to the amp
> itself, so the knowledge of what’s the optimal value could be left up to
> ALSA use-case configuration, and there’s no real downside in treating it
> like other gain controls.

Alternatively why not just query the supply voltage via the regulator
API?  Those are kind of weird numbers (eg, 12.6V rather than 12V)
though, it looks like they're not expected to be the actual maximum
supply values but rather something slightly less.
  
Krzysztof Kozlowski May 10, 2023, 7:51 a.m. UTC | #4
On 09/05/2023 18:38, Martin Povišer wrote:
> Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
> mono amplifier with digital input.
> 
> Signed-off-by: Martin Povišer <povik+lin@cutebit.org>


> +  reg:
> +    maxItems: 1
> +
> +  adi,ana-gain:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [0, 1, 2, 3]
> +    description: |
> +      The value to be set in the ANA_GAIN register field on the codec. This determines
> +      the full voltage span of the codec's analog output.
> +
> +      To quote the datasheet on the available options:
> +
> +        00: 8.4 V Full-Scale Gain Mapping
> +        01: 12.6 V Full-Scale Gain Mapping
> +        10: 14 V Full-Scale Gain Mapping
> +        11: 15 V Full-Scale Gain Mapping
> +
> +  '#sound-dai-cells':
> +    const: 0
> +
> +required:
> +  - compatible
> +  - reg
> +  - adi,ana-gain
> +
> +additionalProperties: true

uinevaluatedProperties: false instead, so users can have name-prefix.

Best regards,
Krzysztof
  
Krzysztof Kozlowski May 10, 2023, 7:51 a.m. UTC | #5
On 09/05/2023 20:25, Conor Dooley wrote:
> Hey Martin,
> 
> On Tue, May 09, 2023 at 06:38:27PM +0200, Martin Povišer wrote:
>> Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
>> mono amplifier with digital input.
>>
>> Signed-off-by: Martin Povišer <povik+lin@cutebit.org>
>> ---
>>  .../bindings/sound/adi,ssm3515.yaml           | 66 +++++++++++++++++++
>>  1 file changed, 66 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml b/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
>> new file mode 100644
>> index 000000000000..19b7185ae8e2
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
>> @@ -0,0 +1,66 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +# Copyright (C) 2019-20 Texas Instruments Incorporated
> 
> Copyright here looks a little odd, copy & paste from the TI bindings you
> send patches for earlier, or intended?
> 
>> +%YAML 1.2
>> +---
>> +$id: "http://devicetree.org/schemas/sound/adi,ssm3515.yaml#"
>> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> 
> Drop the quotes on these please.
> 
>> +
>> +title: Analog Devices SSM3515 Audio Amplifier
>> +
>> +maintainers:
>> +  - Martin Povišer <povik+lin@cutebit.org>
>> +
>> +description: |
>> +  SSM3515 is a mono Class-D audio amplifier with digital input.
>> +
>> +  https://www.analog.com/media/en/technical-documentation/data-sheets/SSM3515.pdf
>> +
>> +allOf:
>> +  - $ref: dai-common.yaml#
>> +
>> +properties:
>> +  compatible:
>> +    enum:
>> +      - adi,ssm3515
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  adi,ana-gain:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    enum: [0, 1, 2, 3]
>> +    description: |
>> +      The value to be set in the ANA_GAIN register field on the codec. This determines
>> +      the full voltage span of the codec's analog output.
>> +
>> +      To quote the datasheet on the available options:
>> +
>> +        00: 8.4 V Full-Scale Gain Mapping
>> +        01: 12.6 V Full-Scale Gain Mapping
>> +        10: 14 V Full-Scale Gain Mapping
>> +        11: 15 V Full-Scale Gain Mapping
> 
> Putting register values into the DT does not seem correct, although
> I know nothing about sound and will have to defer to Krzysztof & Co. on
> that front.

Depends whether these are really voltages or something else (e.g. gain)
just related to voltage.

Best regards,
Krzysztof
  
Martin Povišer May 10, 2023, 8:15 a.m. UTC | #6
> On 10. 5. 2023, at 9:51, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
> 
> On 09/05/2023 18:38, Martin Povišer wrote:
>> Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
>> mono amplifier with digital input.
>> 
>> Signed-off-by: Martin Povišer <povik+lin@cutebit.org>
> 
> 
>> +  reg:
>> +    maxItems: 1
>> +
>> +  adi,ana-gain:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    enum: [0, 1, 2, 3]
>> +    description: |
>> +      The value to be set in the ANA_GAIN register field on the codec. This determines
>> +      the full voltage span of the codec's analog output.
>> +
>> +      To quote the datasheet on the available options:
>> +
>> +        00: 8.4 V Full-Scale Gain Mapping
>> +        01: 12.6 V Full-Scale Gain Mapping
>> +        10: 14 V Full-Scale Gain Mapping
>> +        11: 15 V Full-Scale Gain Mapping
>> +
>> +  '#sound-dai-cells':
>> +    const: 0
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +  - adi,ana-gain
>> +
>> +additionalProperties: true
> 
> uinevaluatedProperties: false instead, so users can have name-prefix.

I actually tweaked this to have the example passing, which has sound-name-prefix,
which I guess is what you have in mind. Not that I exactly understand what these
options do (both additionalProperties and unevaluatedProperties), the schema docs
didn’t enlighten me right away when I looked into it.

If 'unevaluatedProperties: false' is the way to go here, I will change it.

Kind regards,
Martin

> Best regards,
> Krzysztof
  
Krzysztof Kozlowski May 10, 2023, 8:23 a.m. UTC | #7
On 10/05/2023 10:15, Martin Povišer wrote:
> 
>> On 10. 5. 2023, at 9:51, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
>>
>> On 09/05/2023 18:38, Martin Povišer wrote:
>>> Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
>>> mono amplifier with digital input.
>>>
>>> Signed-off-by: Martin Povišer <povik+lin@cutebit.org>
>>
>>
>>> +  reg:
>>> +    maxItems: 1
>>> +
>>> +  adi,ana-gain:
>>> +    $ref: /schemas/types.yaml#/definitions/uint32
>>> +    enum: [0, 1, 2, 3]
>>> +    description: |
>>> +      The value to be set in the ANA_GAIN register field on the codec. This determines
>>> +      the full voltage span of the codec's analog output.
>>> +
>>> +      To quote the datasheet on the available options:
>>> +
>>> +        00: 8.4 V Full-Scale Gain Mapping
>>> +        01: 12.6 V Full-Scale Gain Mapping
>>> +        10: 14 V Full-Scale Gain Mapping
>>> +        11: 15 V Full-Scale Gain Mapping
>>> +
>>> +  '#sound-dai-cells':
>>> +    const: 0
>>> +
>>> +required:
>>> +  - compatible
>>> +  - reg
>>> +  - adi,ana-gain
>>> +
>>> +additionalProperties: true
>>
>> uinevaluatedProperties: false instead, so users can have name-prefix.
> 
> I actually tweaked this to have the example passing, which has sound-name-prefix,

true is not allowed anyway - it makes your schema simply not effective
almost at all as it allows anything...

> which I guess is what you have in mind. Not that I exactly understand what these
> options do (both additionalProperties and unevaluatedProperties), the schema docs
> didn’t enlighten me right away when I looked into it.

The way to go and to start always is to look at example-schema. It tells
you explicitly to use additionalProperties:false and switch to
unevaluated "If and only if another schema is referenced".


Best regards,
Krzysztof
  
Martin Povišer May 10, 2023, 8:29 a.m. UTC | #8
> On 10. 5. 2023, at 10:23, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
> 
> On 10/05/2023 10:15, Martin Povišer wrote:
>> 
>>> On 10. 5. 2023, at 9:51, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
>>> 
>>> On 09/05/2023 18:38, Martin Povišer wrote:
>>>> Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
>>>> mono amplifier with digital input.
>>>> 
>>>> Signed-off-by: Martin Povišer <povik+lin@cutebit.org>

>>>> +additionalProperties: true
>>> 
>>> uinevaluatedProperties: false instead, so users can have name-prefix.
>> 
>> I actually tweaked this to have the example passing, which has sound-name-prefix,
> 
> true is not allowed anyway - it makes your schema simply not effective
> almost at all as it allows anything...

That makes sense.

>> which I guess is what you have in mind. Not that I exactly understand what these
>> options do (both additionalProperties and unevaluatedProperties), the schema docs
>> didn’t enlighten me right away when I looked into it.
> 
> The way to go and to start always is to look at example-schema. It tells
> you explicitly to use additionalProperties:false and switch to
> unevaluated "If and only if another schema is referenced".

OK. While I have you on the line, what does unevaluated do? In what sense are props
unevaluated?

> Best regards,
> Krzysztof

Regards,
Martin
  
Krzysztof Kozlowski May 10, 2023, 8:30 a.m. UTC | #9
On 10/05/2023 10:29, Martin Povišer wrote:
> 
> 
>> On 10. 5. 2023, at 10:23, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
>>
>> On 10/05/2023 10:15, Martin Povišer wrote:
>>>
>>>> On 10. 5. 2023, at 9:51, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
>>>>
>>>> On 09/05/2023 18:38, Martin Povišer wrote:
>>>>> Add a DT schema for the SSM3515 amp by Analog Devices. It's a simple
>>>>> mono amplifier with digital input.
>>>>>
>>>>> Signed-off-by: Martin Povišer <povik+lin@cutebit.org>
> 
>>>>> +additionalProperties: true
>>>>
>>>> uinevaluatedProperties: false instead, so users can have name-prefix.
>>>
>>> I actually tweaked this to have the example passing, which has sound-name-prefix,
>>
>> true is not allowed anyway - it makes your schema simply not effective
>> almost at all as it allows anything...
> 
> That makes sense.
> 
>>> which I guess is what you have in mind. Not that I exactly understand what these
>>> options do (both additionalProperties and unevaluatedProperties), the schema docs
>>> didn’t enlighten me right away when I looked into it.
>>
>> The way to go and to start always is to look at example-schema. It tells
>> you explicitly to use additionalProperties:false and switch to
>> unevaluated "If and only if another schema is referenced".
> 
> OK. While I have you on the line, what does unevaluated do? In what sense are props
> unevaluated?

Properties can be evaluated by some other referenced schema (e.g.
dai-common.yaml). If nothing evaluated them, they are unevaluated, thus
unknown and not allowed.

Best regards,
Krzysztof
  
Mark Brown May 11, 2023, 1:11 a.m. UTC | #10
On Wed, May 10, 2023 at 09:51:50AM +0200, Krzysztof Kozlowski wrote:
> On 09/05/2023 20:25, Conor Dooley wrote:
> > On Tue, May 09, 2023 at 06:38:27PM +0200, Martin Povišer wrote:

> >> +        00: 8.4 V Full-Scale Gain Mapping
> >> +        01: 12.6 V Full-Scale Gain Mapping
> >> +        10: 14 V Full-Scale Gain Mapping
> >> +        11: 15 V Full-Scale Gain Mapping

> > Putting register values into the DT does not seem correct, although
> > I know nothing about sound and will have to defer to Krzysztof & Co. on
> > that front.

> Depends whether these are really voltages or something else (e.g. gain)
> just related to voltage.

They are configuring the voltage range that the output will generate.
  

Patch

diff --git a/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml b/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
new file mode 100644
index 000000000000..19b7185ae8e2
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/adi,ssm3515.yaml
@@ -0,0 +1,66 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2019-20 Texas Instruments Incorporated
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/sound/adi,ssm3515.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+title: Analog Devices SSM3515 Audio Amplifier
+
+maintainers:
+  - Martin Povišer <povik+lin@cutebit.org>
+
+description: |
+  SSM3515 is a mono Class-D audio amplifier with digital input.
+
+  https://www.analog.com/media/en/technical-documentation/data-sheets/SSM3515.pdf
+
+allOf:
+  - $ref: dai-common.yaml#
+
+properties:
+  compatible:
+    enum:
+      - adi,ssm3515
+
+  reg:
+    maxItems: 1
+
+  adi,ana-gain:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [0, 1, 2, 3]
+    description: |
+      The value to be set in the ANA_GAIN register field on the codec. This determines
+      the full voltage span of the codec's analog output.
+
+      To quote the datasheet on the available options:
+
+        00: 8.4 V Full-Scale Gain Mapping
+        01: 12.6 V Full-Scale Gain Mapping
+        10: 14 V Full-Scale Gain Mapping
+        11: 15 V Full-Scale Gain Mapping
+
+  '#sound-dai-cells':
+    const: 0
+
+required:
+  - compatible
+  - reg
+  - adi,ana-gain
+
+additionalProperties: true
+
+examples:
+  - |
+    i2c {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      codec@14 {
+        compatible = "adi,ssm3515";
+        reg = <0x14>;
+        #sound-dai-cells = <0>;
+        adi,ana-gain = <0>;
+        sound-name-prefix = "Left Tweeter";
+      };
+    };