ASoC: dt-bindings: nau8825: Convert to dtschema

Convert the NAU8825 audio CODEC bindings to DT schema.

Signed-off-by: David Lin <CTLIN0@nuvoton.com>
---
 .../devicetree/bindings/sound/nau8825.txt     | 111 ---------
 .../bindings/sound/nuvoton,nau8825.yaml       | 220 ++++++++++++++++++
 2 files changed, 220 insertions(+), 111 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/nau8825.txt
 create mode 100644 Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml

On Tue, 09 May 2023 13:10:55 +0800, David Lin wrote:
> Convert the NAU8825 audio CODEC bindings to DT schema.
> 
> Signed-off-by: David Lin <CTLIN0@nuvoton.com>
> ---
>  .../devicetree/bindings/sound/nau8825.txt     | 111 ---------
>  .../bindings/sound/nuvoton,nau8825.yaml       | 220 ++++++++++++++++++
>  2 files changed, 220 insertions(+), 111 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/sound/nau8825.txt
>  create mode 100644 Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:
./Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml:172:4: [warning] wrong indentation: expected 4 but found 3 (indentation)
./Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml:177:4: [warning] wrong indentation: expected 4 but found 3 (indentation)

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/nuvoton,nau8825.example.dtb: nau8825@1a: Unevaluated properties are not allowed ('interrupts' was unexpected)
	From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml

See https://patchwork.ozlabs.org/patch/1778742

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.

On 09/05/2023 07:10, David Lin wrote:
> Convert the NAU8825 audio CODEC bindings to DT schema.
> 
> Signed-off-by: David Lin <CTLIN0@nuvoton.com>
> ---
>  .../devicetree/bindings/sound/nau8825.txt     | 111 ---------
>  .../bindings/sound/nuvoton,nau8825.yaml       | 220 ++++++++++++++++++
>  2 files changed, 220 insertions(+), 111 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/sound/nau8825.txt
>  create mode 100644 Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml

Does not look like you tested the bindings. Please run `make
dt_binding_check` (see
Documentation/devicetree/bindings/writing-schema.rst for instructions).

> 
> diff --git a/Documentation/devicetree/bindings/sound/nau8825.txt b/Documentation/devicetree/bindings/sound/nau8825.txt
> deleted file mode 100644
> index a9c34526f4cb..000000000000
> --- a/Documentation/devicetree/bindings/sound/nau8825.txt
> +++ /dev/null
> @@ -1,111 +0,0 @@
> -Nuvoton NAU8825 audio codec

(...)

> +  nuvoton,jkdet-enable:
> +    description:
> +      Enable jack detection via JKDET pin.
> +    type: boolean
> +
> +  nuvoton,jkdet-pull-enable:
> +    description:
> +      Enable JKDET pin pull.
> +      If set - pin pull enabled, otherwise pin in high impedance state.
> +    type: boolean
> +
> +  nuvoton,jkdet-pull-up:
> +    description:
> +      Pull-up JKDET pin.
> +      If set then JKDET pin is pull up, otherwise pull down.
> +    type: boolean
> +
> +  nuvoton,jkdet-polarity:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      JKDET pin polarity.
> +    enum:
> +      - 0 # active high
> +      - 1 # active low

Since this is optional:
default: ?

Same in other places.

> +
> +  nuvoton,vref-impedance:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      VREF Impedance selection.
> +    enum:
> +      - 0 # Open
> +      - 1 # 25 kOhm
> +      - 2 # 125 kOhm
> +      - 3 # 2.5 kOhm
> +
> +  nuvoton,micbias-voltage:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      Micbias voltage level.
> +    enum:
> +      - 0 # VDDA
> +      - 1 # VDDA
> +      - 2 # VDDA * 1.1
> +      - 3 # VDDA * 1.2
> +      - 4 # VDDA * 1.3
> +      - 5 # VDDA * 1.4
> +      - 6 # VDDA * 1.53
> +      - 7 # VDDA * 1.53
> +
> +  nuvoton,sar-threshold-num:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      Number of buttons supported.
> +    minimum: 1
> +    maximum: 4
> +
> +  nuvoton,sar-threshold:
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    description:
> +      Impedance threshold for each button. Array that contains up to 8 buttons
> +      configuration. SAR value is calculated as
> +      SAR = 255 * MICBIAS / SAR_VOLTAGE * R / (2000 + R) where MICBIAS is
> +      configured by 'nuvoton,micbias-voltage', SAR_VOLTAGE is configured by
> +      'nuvoton,sar-voltage', R - button impedance.
> +      Refer datasheet section 10.2 for more information about threshold
> +      calculation.
> +    minItems: 1
> +    maxItems: 4
> +    items:
> +      minimum: 0
> +      maximum: 255
> +
> +  nuvoton,sar-hysteresis:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      Button impedance measurement hysteresis.
> +
> +  nuvoton,sar-voltage:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      Reference voltage for button impedance measurement.
> +    enum:
> +      - 0 # VDDA
> +      - 1 # VDDA
> +      - 2 # VDDA * 1.1
> +      - 3 # VDDA * 1.2
> +      - 4 # VDDA * 1.3
> +      - 5 # VDDA * 1.4
> +      - 6 # VDDA * 1.53
> +      - 7 # VDDA * 1.53
> +
> +  nuvoton,sar-compare-time:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      SAR compare time.
> +    enum:
> +      - 0 # 500ns
> +      - 1 # 1us
> +      - 2 # 2us
> +      - 3 # 4us
> +
> +  nuvoton,sar-sampling-time:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      SAR sampling time.
> +    enum:
> +      - 0 # 2us
> +      - 1 # 4us
> +      - 2 # 8us
> +      - 3 # 16us
> +
> +  nuvoton,short-key-debounce:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      Button short key press debounce time.
> +    enum:
> +      - 0 # 30 ms
> +      - 1 # 50 ms
> +      - 2 # 100 ms
> +
> +  nuvoton,jack-insert-debounce:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      number from 0 to 7 that sets debounce time to 2^(n+2) ms.

maximum: 7

> +
> +  nuvoton,jack-eject-debounce:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      number from 0 to 7 that sets debounce time to 2^(n+2) ms

maximum: 7

> +
> +  nuvoton,crosstalk-enable:
> +    description:
> +      make crosstalk function enable if set.
> +    type: boolean
> +
> +  nuvoton,adcout-drive-strong:
> +    description:
> +      make the drive strength of ADCOUT IO PIN strong if set.
> +      Otherwise, the drive keeps normal strength.
> +    type: boolean
> +
> +  nuvoton,adc-delay-ms:
> +    description:
> +      Delay (in ms) to make input path stable and avoid pop noise.
> +      The default value is 125 and range between 125 to 500 ms.
> +    minimum: 125
> +    maximum: 500
> +
> +  clocks:
> +   description:
> +     list of phandle and clock specifier pairs according to common clock
> +     bindings for the clocks described in clock-names.

Drop description. maxItems: 1.

> +
> +  clock-names:
> +   description:
> +     should include "mclk" for the MCLK master clock.

No, you need to list entries with items.

> +
> +required:
> +  - compatible
> +  - reg
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/tegra-gpio.h>
> +    #include <dt-bindings/soc/tegra-pmc.h>
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +        headset: nau8825@1a {

Node names should be generic, audio-codec for example.
https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation

> +            compatible = "nuvoton,nau8825";
> +            reg = <0x1a>;
Best regards,
Krzysztof

On 5/9/2023 2:22 PM, Krzysztof Kozlowski wrote:
> On 09/05/2023 07:10, David Lin wrote:
>> Convert the NAU8825 audio CODEC bindings to DT schema.
>>
>> Signed-off-by: David Lin <CTLIN0@nuvoton.com>
>> ---
>>   .../devicetree/bindings/sound/nau8825.txt     | 111 ---------
>>   .../bindings/sound/nuvoton,nau8825.yaml       | 220 ++++++++++++++++++
>>   2 files changed, 220 insertions(+), 111 deletions(-)
>>   delete mode 100644 Documentation/devicetree/bindings/sound/nau8825.txt
>>   create mode 100644 Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
> Does not look like you tested the bindings. Please run `make
> dt_binding_check` (see
> Documentation/devicetree/bindings/writing-schema.rst for instructions).

No, I had ever run 'make dt_binding_check', the result is no errors.

However, regarding your bot found the warnings, I check my environment
is not the latest dtschema and without yamllint.

>> diff --git a/Documentation/devicetree/bindings/sound/nau8825.txt b/Documentation/devicetree/bindings/sound/nau8825.txt
>> deleted file mode 100644
>> index a9c34526f4cb..000000000000
>> --- a/Documentation/devicetree/bindings/sound/nau8825.txt
>> +++ /dev/null
>> @@ -1,111 +0,0 @@
>> -Nuvoton NAU8825 audio codec
> (...)
>
>> +  nuvoton,jkdet-enable:
>> +    description:
>> +      Enable jack detection via JKDET pin.
>> +    type: boolean
>> +
>> +  nuvoton,jkdet-pull-enable:
>> +    description:
>> +      Enable JKDET pin pull.
>> +      If set - pin pull enabled, otherwise pin in high impedance state.
>> +    type: boolean
>> +
>> +  nuvoton,jkdet-pull-up:
>> +    description:
>> +      Pull-up JKDET pin.
>> +      If set then JKDET pin is pull up, otherwise pull down.
>> +    type: boolean
>> +
>> +  nuvoton,jkdet-polarity:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      JKDET pin polarity.
>> +    enum:
>> +      - 0 # active high
>> +      - 1 # active low
> Since this is optional:
> default: ?
>
> Same in other places.
OK~I will add default value to these optional properties.
>> +
>> +  nuvoton,vref-impedance:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      VREF Impedance selection.
>> +    enum:
>> +      - 0 # Open
>> +      - 1 # 25 kOhm
>> +      - 2 # 125 kOhm
>> +      - 3 # 2.5 kOhm
>> +
>> +  nuvoton,micbias-voltage:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      Micbias voltage level.
>> +    enum:
>> +      - 0 # VDDA
>> +      - 1 # VDDA
>> +      - 2 # VDDA * 1.1
>> +      - 3 # VDDA * 1.2
>> +      - 4 # VDDA * 1.3
>> +      - 5 # VDDA * 1.4
>> +      - 6 # VDDA * 1.53
>> +      - 7 # VDDA * 1.53
>> +
>> +  nuvoton,sar-threshold-num:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      Number of buttons supported.
>> +    minimum: 1
>> +    maximum: 4
>> +
>> +  nuvoton,sar-threshold:
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    description:
>> +      Impedance threshold for each button. Array that contains up to 8 buttons
>> +      configuration. SAR value is calculated as
>> +      SAR = 255 * MICBIAS / SAR_VOLTAGE * R / (2000 + R) where MICBIAS is
>> +      configured by 'nuvoton,micbias-voltage', SAR_VOLTAGE is configured by
>> +      'nuvoton,sar-voltage', R - button impedance.
>> +      Refer datasheet section 10.2 for more information about threshold
>> +      calculation.
>> +    minItems: 1
>> +    maxItems: 4
>> +    items:
>> +      minimum: 0
>> +      maximum: 255
>> +
>> +  nuvoton,sar-hysteresis:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      Button impedance measurement hysteresis.
>> +
>> +  nuvoton,sar-voltage:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      Reference voltage for button impedance measurement.
>> +    enum:
>> +      - 0 # VDDA
>> +      - 1 # VDDA
>> +      - 2 # VDDA * 1.1
>> +      - 3 # VDDA * 1.2
>> +      - 4 # VDDA * 1.3
>> +      - 5 # VDDA * 1.4
>> +      - 6 # VDDA * 1.53
>> +      - 7 # VDDA * 1.53
>> +
>> +  nuvoton,sar-compare-time:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      SAR compare time.
>> +    enum:
>> +      - 0 # 500ns
>> +      - 1 # 1us
>> +      - 2 # 2us
>> +      - 3 # 4us
>> +
>> +  nuvoton,sar-sampling-time:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      SAR sampling time.
>> +    enum:
>> +      - 0 # 2us
>> +      - 1 # 4us
>> +      - 2 # 8us
>> +      - 3 # 16us
>> +
>> +  nuvoton,short-key-debounce:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      Button short key press debounce time.
>> +    enum:
>> +      - 0 # 30 ms
>> +      - 1 # 50 ms
>> +      - 2 # 100 ms
>> +
>> +  nuvoton,jack-insert-debounce:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      number from 0 to 7 that sets debounce time to 2^(n+2) ms.
> maximum: 7
>
>> +
>> +  nuvoton,jack-eject-debounce:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description:
>> +      number from 0 to 7 that sets debounce time to 2^(n+2) ms
> maximum: 7
Regarding the description have limitation for range, so your comment is
great.
>
>> +
>> +  nuvoton,crosstalk-enable:
>> +    description:
>> +      make crosstalk function enable if set.
>> +    type: boolean
>> +
>> +  nuvoton,adcout-drive-strong:
>> +    description:
>> +      make the drive strength of ADCOUT IO PIN strong if set.
>> +      Otherwise, the drive keeps normal strength.
>> +    type: boolean
>> +
>> +  nuvoton,adc-delay-ms:
>> +    description:
>> +      Delay (in ms) to make input path stable and avoid pop noise.
>> +      The default value is 125 and range between 125 to 500 ms.
>> +    minimum: 125
>> +    maximum: 500
>> +
>> +  clocks:
>> +   description:
>> +     list of phandle and clock specifier pairs according to common clock
>> +     bindings for the clocks described in clock-names.
> Drop description. maxItems: 1.
OK~I will add  it.
>
>> +
>> +  clock-names:
>> +   description:
>> +     should include "mclk" for the MCLK master clock.
> No, you need to list entries with items.
OK~I will add  it.
>
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +
>> +unevaluatedProperties: false
>> +
>> +examples:
>> +  - |
>> +    #include <dt-bindings/gpio/tegra-gpio.h>
>> +    #include <dt-bindings/soc/tegra-pmc.h>
>> +    #include <dt-bindings/interrupt-controller/irq.h>
>> +    i2c {
>> +        #address-cells = <1>;
>> +        #size-cells = <0>;
>> +        headset: nau8825@1a {
> Node names should be generic, audio-codec for example.
> https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation
OK~I can follow it.
>> +            compatible = "nuvoton,nau8825";
>> +            reg = <0x1a>;
> Best regards,
> Krzysztof
>