Re: [PATCH v2] ASoC: dt-bindings: renesas,rsnd: switch to yaml base Documentation

[Rob Herring]

On Fri, Feb 14, 2020 at 02:12:39PM +0900, Kuninori Morimoto wrote:
> From: Kuninori Morimoto <kuninori.morimoto.gx@xxxxxxxxxxx>
> 
> This patch switches from .txt base to .yaml base Document.
> It is still keeping detail explanations at .txt
> 
> Signed-off-by: Kuninori Morimoto <kuninori.morimoto.gx@xxxxxxxxxxx>
> ---
> v1 -> v2
> 	- fixup dtc error
> 
>  .../bindings/sound/renesas,rsnd.txt           | 518 -----------------
>  .../bindings/sound/renesas,rsnd.yaml          | 529 ++++++++++++++++++
>  2 files changed, 529 insertions(+), 518 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/sound/renesas,rsnd.yaml


> diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml
> new file mode 100644
> index 000000000000..0958255c8542
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.yaml
> @@ -0,0 +1,529 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/sound/renesas,rsnd.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Renesas R-Car Sound Driver Device Tree Bindings
> +
> +maintainers:
> +  - Kuninori Morimoto <kuninori.morimoto.gx@xxxxxxxxxxx>
> +
> +properties:
> +  $nodename:
> +    pattern: "^sound@.*"
> +
> +  compatible:
> +    oneOf:
> +      # for Gen1 SoC
> +      - items:
> +        - enum:

nit: Should be indented 2 more spaces.

> +          - renesas,rcar_sound-r8a7778 # R-Car M1A
> +          - renesas,rcar_sound-r8a7779 # R-Car H1
> +        - enum:
> +          - renesas,rcar_sound-gen1
> +      # for Gen2 SoC
> +      - items:
> +        - enum:
> +          - renesas,rcar_sound-r8a7743   # RZ/G1M
> +          - renesas,rcar_sound-r8a7744   # RZ/G1N
> +          - renesas,rcar_sound-r8a7745   # RZ/G1E
> +          - renesas,rcar_sound-r8a77470  # RZ/G1C
> +          - renesas,rcar_sound-r8a7790   # R-Car H2
> +          - renesas,rcar_sound-r8a7791   # R-Car M2-W
> +          - renesas,rcar_sound-r8a7793   # R-Car M2-N
> +          - renesas,rcar_sound-r8a7794   # R-Car E2
> +        - enum:
> +          - renesas,rcar_sound-gen2
> +      # for Gen3 SoC
> +      - items:
> +        - enum:
> +          - renesas,rcar_sound-r8a774a1  # RZ/G2M
> +          - renesas,rcar_sound-r8a774b1  # RZ/G2N
> +          - renesas,rcar_sound-r8a774c0  # RZ/G2E
> +          - renesas,rcar_sound-r8a7795   # R-Car H3
> +          - renesas,rcar_sound-r8a7796   # R-Car M3-W
> +          - renesas,rcar_sound-r8a77965  # R-Car M3-N
> +          - renesas,rcar_sound-r8a77990  # R-Car E3
> +          - renesas,rcar_sound-r8a77995  # R-Car D3
> +        - enum:
> +          - renesas,rcar_sound-gen3
> +      # for Generic
> +      - items:
> +        - enum:
> +          - renesas,rcar_sound-gen1
> +          - renesas,rcar_sound-gen2
> +          - renesas,rcar_sound-gen3
> +
> +  reg:
> +    minItems: 3 # Gen1
> +    maxItems: 5 # Gen2/Gen3
> +
> +  reg-names:
> +    description: |
> +      Should contain the register names.
> +      scu/adg/ssi              if generation1
> +      scu/adg/ssiu/ssi/audmapp if generation2/generation3
> +    minItems: 3 # Gen1
> +    maxItems: 5 # Gen2/Gen3
> +    allOf:
> +      - items:
> +          enum:
> +            - scu
> +            - adg
> +            - ssiu
> +            - ssi
> +            - audmapp

This should be 2 'oneOf' entries listing out the exact names and index.

> +
> +  "#sound-dai-cells":
> +    description: |
> +      it must be 0 if your system is using single DAI
> +      it must be 1 if your system is using multi  DAIs
> +    enum: [0, 1]
> +
> +  "#clock-cells":
> +    description: |
> +      it must be 0 if your system has audio_clkout
> +      it must be 1 if your system has audio_clkout0/1/2/3
> +    enum: [0, 1]
> +
> +  clock-frequency:
> +    description: for audio_clkout0/1/2/3
> +    $ref: /schemas/types.yaml#/definitions/uint32-array

This already has a common definition and this conflicts with that. 
'clock-frequency' is a single uint32 or uint64.

> +
> +  clkout-lr-asynchronous:
> +    description: audio_clkoutn is asynchronizes with lr-clock.
> +    $ref: /schemas/types.yaml#/definitions/flag
> +
> +  power-domains: true
> +
> +  resets:
> +    description: References to SSI resets
> +    $ref: /schemas/types.yaml#/definitions/phandle-array
> +
> +  reset-names:
> +    description: List of valid reset names.
> +    allOf:

Don't need allOf here.

You do need to define how many items.

> +      - items:
> +          enum:
> +            - ssi-all
> +            - ssi.9
> +            - ssi.8
> +            - ssi.7
> +            - ssi.6
> +            - ssi.5
> +            - ssi.4
> +            - ssi.3
> +            - ssi.2
> +            - ssi.1
> +            - ssi.0

Looks like a pattern.

pattern: '^ssi(-all|\.[0-9])$'


> +
> +  clocks:
> +    $ref: /schemas/types.yaml#/definitions/phandle-array

Already has a type definition. Need to define how many.

> +    description: References to SSI/SRC/MIX/CTU/DVC/AUDIO_CLK clocks.
> +
> +  clock-names:
> +    description: List of necessary clock names.
> +    allOf:
> +      - items:
> +          enum:
> +            - ssi-all
> +            - ssi.9
> +            - ssi.8
> +            - ssi.7
> +            - ssi.6
> +            - ssi.5
> +            - ssi.4
> +            - ssi.3
> +            - ssi.2
> +            - ssi.1
> +            - ssi.0
> +            - src.9
> +            - src.8
> +            - src.7
> +            - src.6
> +            - src.5
> +            - src.4
> +            - src.3
> +            - src.2
> +            - src.1
> +            - src.0
> +            - mix.1
> +            - mix.0
> +            - ctu.1
> +            - ctu.0
> +            - dvc.1
> +            - dvc.0
> +            - clk_a
> +            - clk_b
> +            - clk_c
> +            - clk_i

Looks like a couple of patterns.

> +
> +  # For OF-graph
> +  port:
> +    description: OF-Graph subnode
> +    type: object
> +    properties:
> +      reg:
> +        $ref: /schemas/types.yaml#/definitions/uint32

No unit-address for 'port', so you don't need 'reg' here.

> +      endpoint:
> +        type: object
> +        properties:
> +          remote-endpoint:
> +            $ref: /schemas/types.yaml#/definitions/phandle-array

Assume this already has a type.

> +          dai-format:
> +            $ref: "simple-card.yaml#/definitions/format"
> +          playback:
> +            $ref: /schemas/types.yaml#/definitions/phandle-array
> +          capture:
> +            $ref: /schemas/types.yaml#/definitions/phandle-array
> +        required:
> +            - remote-endpoint
> +
> +  # For multi OF-graph
> +  ports:
> +    description: multi OF-Graph subnode
> +    type: object
> +    patternProperties:
> +      "port(@.*)?":

^port(@[0-9a-f])?$"

Perhaps there's max number of ports that's less than 0xf?

> +        $ref: "#properties/port"

Would be more simple to just always have 'ports'.

> +
> +patternProperties:
> +  "^rcar_sound,dvc$":

Not a pattern, but a fixed string...

> +    description: DVC subnode.
> +    type: object
> +    patternProperties:
> +      "dvc-.":
> +        type: object
> +        properties:
> +          dmas:
> +            $ref: /schemas/types.yaml#/definitions/phandle-array

Already has a type, just need 'maxItems: 1'.

> +          dma-names:
> +            const: "tx"
> +        required:
> +          - dmas
> +          - dma-names
> +    additionalProperties: false
> +
> +  "^rcar_sound,mix$":

Not a pattern...

> +    description: MIX subnode.
> +    type: object
> +    patternProperties:
> +      "mix-.":

foomix-bar is valid?

> +        type: object

Aren't there properties in this node?

> +    additionalProperties: false

Stopping here because the rest looks like more of the same comments.

Rob