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

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