Re: [PATCH v3] ASoC: dt-bindings: simple-card: switch to yaml base Documentation

Rob Herring
2020-03-30T19:40:00Z

On Mon, Mar 16, 2020 at 02:24:50PM +0900, Kuninori Morimoto wrote:
> From: Kuninori Morimoto <kuninori.morimoto.gx@renesas.com>
>
> This patch switches from .txt base to .yaml base Document.
> This patch is assuming that "sound-dai" is already defined.
>
> Signed-off-by: Kuninori Morimoto <kuninori.morimoto.gx@renesas.com>
> ---
> v2 -> v3
>
> - uses maxItems for many place which were already defined.
> - assuming that "sound-dai" is already defined
> - (@.*) -> (@[0-9a-f]+)
>
> .../devicetree/bindings/sound/simple-card.txt | 351 -------------
> .../bindings/sound/simple-card.yaml | 487 ++++++++++++++++++
> 2 files changed, 487 insertions(+), 351 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/sound/simple-card.txt
> create mode 100644 Documentation/devicetree/bindings/sound/simple-card.yaml

> diff --git a/Documentation/devicetree/bindings/sound/simple-card.yaml b/Documentation/devicetree/bindings/sound/simple-card.yaml
> new file mode 100644
> index 000000000000..cd5ea50daa22
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/simple-card.yaml
> @@ -0,0 +1,487 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/sound/simple-card.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Simple Audio Card Driver Device Tree Bindings
> +
> +maintainers:
> + - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com>
> +
> +definitions:
> +
> + frame-master:
> + description: Indicates dai-link frame master.
> + allOf:
> + - $ref: /schemas/types.yaml#/definitions/phandle-array
> + - maxItems: 1
> +
> + bitclock-master:
> + description: Indicates dai-link bit clock master
> + allOf:
> + - $ref: /schemas/types.yaml#/definitions/phandle-array
> + - maxItems: 1
> +
> + frame-inversion:
> + description: dai-link uses frame clock inversion
> + $ref: /schemas/types.yaml#/definitions/flag
> +
> + bitclock-inversion:
> + description: dai-link uses bit clock inversion
> + $ref: /schemas/types.yaml#/definitions/flag
> +
> + dai-tdm-slot-num:
> + description: see tdm-slot.txt.
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + dai-tdm-slot-width:
> + description: see tdm-slot.txt.
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + clocks:
> + maxItems: 1

Only used in one place, just move there.

> +
> + system-clock-frequency:
> + description: |
> + If a clock is specified and a multiplication factor is given with
> + mclk-fs, the clock will be set to the calculated mclk frequency
> + when the stream starts.
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + system-clock-direction-out:
> + description: |
> + specifies clock direction as 'out' on initialization.
> + It is useful for some aCPUs with fixed clocks.
> + $ref: /schemas/types.yaml#/definitions/flag
> +
> + mclk-fs:
> + description: |
> + Multiplication factor between stream rate and codec mclk.
> + When defined, mclk-fs property defined in dai-link sub nodes are ignored.
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + aux-devs:
> + description: |
> + List of phandles pointing to auxiliary devices, such
> + as amplifiers, to be added to the sound card.
> + $ref: /schemas/types.yaml#/definitions/phandle-array
> +
> + convert-rate:
> + description: CPU to Codec rate convert.
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + convert-channels:
> + description: CPU to Codec rate channels.
> + $ref: /schemas/types.yaml#/definitions/uint32
> +
> + prefix:
> + description: "device name prefix"
> + $ref: /schemas/types.yaml#/definitions/string
> +
> + label:
> + maxItems: 1
> +
> + routing:
> + description: |
> + A list of the connections between audio components.
> + Each entry is a pair of strings, the first being the
> + connection's sink, the second being the connection's source.
> + $ref: /schemas/types.yaml#/definitions/non-unique-string-array
> +
> + widgets:
> + description: User specified audio sound widgets.
> + $ref: /schemas/types.yaml#/definitions/non-unique-string-array
> +
> + pin-switches:
> + description: the widget names for which pin switches must be created.
> + $ref: /schemas/types.yaml#/definitions/string-array
> +
> + format:
> + description: audio format.
> + items:
> + enum:
> + - i2s
> + - right_j
> + - left_j
> + - dsp_a
> + - dsp_b
> + - ac97
> + - pdm
> + - msb
> + - lsb
> +
> + dai:
> + type: object
> + properties:
> + sound-dai:
> + maxItems: 1
> +
> + # common properties
> + mclk-fs:
> + $ref: "#/definitions/mclk-fs"
> + prefix:
> + $ref: "#/definitions/prefix"
> + frame-inversion:
> + $ref: "#/definitions/frame-inversion"
> + bitclock-inversion:
> + $ref: "#/definitions/bitclock-inversion"
> + frame-master:
> + $ref: /schemas/types.yaml#/definitions/flag
> + bitclock-master:
> + $ref: /schemas/types.yaml#/definitions/flag
> +
> + dai-tdm-slot-num:
> + $ref: "#/definitions/dai-tdm-slot-num"
> + dai-tdm-slot-width:
> + $ref: "#/definitions/dai-tdm-slot-width"
> + clocks:
> + $ref: "#/definitions/clocks"
> + system-clock-frequency:
> + $ref: "#/definitions/system-clock-frequency"
> + system-clock-direction-out:
> + $ref: "#/definitions/system-clock-direction-out"
> + required:
> + - sound-dai
> +
> +properties:
> + compatible:
> + contains:
> + enum:
> + - simple-audio-card
> + - simple-scu-audio-card
> +
> + "#address-cells":
> + const: 1
> + "#size-cells":
> + const: 0
> +
> + label:
> + $ref: "#/definitions/label"
> +
> + simple-audio-card,name:
> + description: User specified audio sound card name.
> + $ref: /schemas/types.yaml#/definitions/string
> +
> +# use patternProperties to use "#definitions/xxx"

Huh? The meta-schema gives you an error? We should fix that, not
work-around it.

> +patternProperties:
> + "^simple-audio-card,widgets$":
> + $ref: "#/definitions/widgets"
> + "^simple-audio-card,routing$":
> + $ref: "#/definitions/routing"
> + "^simple-audio-card,cpu(@[0-9a-f]+)?":
> + $ref: "#/definitions/dai"
> + "^simple-audio-card,codec(@[0-9a-f]+)?":
> + $ref: "#/definitions/dai"
> +
> + # common properties
> + "^simple-audio-card,frame-master$":
> + $ref: "#/definitions/frame-master"
> + "^simple-audio-card,bitclock-master$":
> + $ref: "#/definitions/bitclock-master"
> + "^simple-audio-card,frame-inversion$":
> + $ref: "#/definitions/frame-inversion"
> + "^simple-audio-card,bitclock-inversion$":
> + $ref: "#/definitions/bitclock-inversion"
> + "^simple-audio-card,format$":
> + $ref: "#/definitions/format"
> + "^simple-audio-card,mclk-fs$":
> + $ref: "#/definitions/mclk-fs"
> + "^simple-audio-card,aux-devs$":
> + $ref: "#/definitions/aux-devs"
> + "^simple-audio-card,convert-rate$":
> + $ref: "#/definitions/convert-rate"
> + "^simple-audio-card,convert-channels$":
> + $ref: "#/definitions/convert-channels"
> + "^simple-audio-card,prefix$":
> + $ref: "#/definitions/prefix"
> + "^simple-audio-card,pin-switches$":
> + $ref: "#/definitions/pin-switches"
> + "^simple-audio-card,hp-det-gpio$":
> + maxItems: 1
> + "^simple-audio-card,mic-det-gpio$":
> + maxItems: 1
> +
> + "^simple-audio-card,dai-link(@[0-9a-f]+)?$":
> + description: |
> + Container for dai-link level properties and the CPU and CODEC sub-nodes.
> + This container may be omitted when the card has only one DAI link.
> + type: object
> + properties:
> + reg:
> + maxItems: 1
> +
> + # common properties
> + frame-master:
> + $ref: "#/definitions/frame-master"
> + bitclock-master:
> + $ref: "#/definitions/bitclock-master"
> + frame-inversion:
> + $ref: "#/definitions/frame-inversion"
> + bitclock-inversion:
> + $ref: "#/definitions/bitclock-inversion"
> + format:
> + $ref: "#/definitions/format"
> + mclk-fs:
> + $ref: "#/definitions/mclk-fs"
> + aux-devs:
> + $ref: "#/definitions/aux-devs"
> + convert-rate:
> + $ref: "#/definitions/convert-rate"
> + convert-channels:
> + $ref: "#/definitions/convert-channels"
> + prefix:
> + $ref: "#/definitions/prefix"
> + pin-switches:
> + $ref: "#/definitions/pin-switches"
> + hp-det-gpio:
> + maxItems: 1
> + mic-det-gpio:
> + maxItems: 1
> +
> + patternProperties:
> + "^cpu(@[0-9a-f]+)?":
> + $ref: "#/definitions/dai"
> + "^codec(@[0-9a-f]+)?":
> + $ref: "#/definitions/dai"
> + additionalProperties: false
> +
> +required:
> + - compatible
> +
> +additionalProperties: false