Re: [PATCH 02/14] dt-bindings: media: add apple,avd

[Krzysztof Kozlowski]

On 18/09/2026 15:15, Sofus Forstreuter wrote:
> Document the Apple Video Decoder. A hardware video decoder present on
> Apple hardware.
> 
> Signed-off-by: Sofus Forstreuter <sofus.c@xxxxxxxxxx>
> ---
>  .../devicetree/bindings/media/apple,avd.yaml       | 112 +++++++++++++++++++++
>  MAINTAINERS                                        |   1 +
>  2 files changed, 113 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/media/apple,avd.yaml b/Documentation/devicetree/bindings/media/apple,avd.yaml
> new file mode 100644
> index 000000000000..34a4129d6a46
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/media/apple,avd.yaml
> @@ -0,0 +1,112 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/media/apple,avd.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Apple Video Decoder (AVD)
> +
> +description: |
> +  AVD is a stateless video decode IP block present on Apple devices.
> +  Notably it includes an ARM Cortex-M3 and associated DMA controller.
> +  AVD is capable of decoding H264, H265, VP9 and AV1 on never SoCs.
> +
> +  The IP does not change much, with changes being mostly the CM3 having more
> +  memory and interrupts.
> +
> +maintainers:
> +  - Sofus Forstreuter <sofus.c@xxxxxxxxxx>
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - items:
> +          - enum:
> +              - apple,t6030-avd
> +              - apple,t6031-avd
> +          - const: apple,t8122-avd
> +      - enum:
> +          - apple,t8103-avd
> +          - apple,t8112-avd
> +          - apple,t8122-avd
> +          - apple,t6000-avd
> +          - apple,t6020-avd
> +
> +  reg:
> +    minItems: 4
> +    items:
> +      - description: Cortex-M3 code (unsigned)
> +      - description: Cortex-M3 sram
> +      - description: Mailbox
> +      - description: Video decode control
> +      - description: DMA control
> +
> +  reg-names:
> +    items:
> +      - const: code
> +      - const: sram
> +      - const: mbox
> +      - const: ctrl

Sashiko comments are valid.

> +
> +  iommus:
> +    minItems: 1
> +    maxItems: 3
> +    description: |
> +      The block contains 3 iommus, one for decode operations, one the DMA
> +      controller can use and the last for decoding drm-protected content.

List the items with description with minItems instead.

> +
> +  power-domains:
> +    maxItems: 1
> +
> +  resets:
> +    maxItems: 1
> +
> +  interrupts:
> +    minItems: 2
> +    items:
> +      - description: mailbox 0
> +      - description: mailbox 1
> +      - description: mailbox 2
> +      - description: mailbox 3
> +      - description: flag 0
> +      - description: flag 1
> +      - description: DMA status
> +    description: |
> +      Notably there are no decode related interrupts. All decode related
> +      interrupts are sent to the CM3.
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - reg-names
> +  - iommus
> +  - power-domains
> +  - resets
> +

Why properties are unconstrained per each variant? Why are they flexible?

> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/apple-aic.h>
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    soc {
> +        #address-cells = <2>;
> +        #size-cells = <2>;
> +
> +        avd: avd@289080000 {

Drop unused label

Node names should be generic. See also an explanation and list of
examples (not exhaustive) in DT specification:
https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation
If you cannot find a name matching your device, please check in kernel
sources for similar cases or you can grow the spec (via pull request to
DT spec repo).

Don't use custom names, like apple. Codecs are usually video-codecs. Or
isp if this is ISP.

Best regards,
Krzysztof