Adds a binding for the HEVC decoder found on the BCM2711 / Raspberry Pi 4,
and BCM2712 / Raspberry Pi 5.

Signed-off-by: Dave Stevenson <dave.stevenson@raspberrypi.com>
---
 .../bindings/media/raspberrypi,hevc-dec.yaml       | 70 ++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/Documentation/devicetree/bindings/media/raspberrypi,hevc-dec.yaml b/Documentation/devicetree/bindings/media/raspberrypi,hevc-dec.yaml
new file mode 100644
index 000000000000..b86534f2689f
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/raspberrypi,hevc-dec.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/raspberrypi,hevc-dec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Raspberry Pi HEVC Decoder
+
+maintainers:
+  - John Cox <john.cox@raspberrypi.com>
+  - Dom Cobley <dom@raspberrypi.com>
+  - Dave Stevenson <dave.stevenson@raspberrypi.com>
+  - Raspberry Pi internal review list <kernel-list@raspberrypi.com>
+
+description:
+  The Raspberry Pi HEVC decoder is a hardware video decode accelerator block
+  found in the BCM2711 and BCM2712 processors used on Raspberry Pi 4 and 5
+  boards respectively.
+
+properties:
+  compatible:
+    items:
+      - enum:
+          - brcm,bcm2711-hevc-dec
+          - brcm,bcm2712-hevc-dec
+      - const: raspberrypi,hevc-dec
+
+  reg:
+    items:
+      - description: The HEVC main register region
+      - description: The Interrupt control register region
+
+  reg-names:
+    items:
+      - const: hevc
+      - const: intc
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    items:
+      - description: The HEVC block clock
+
+required:
+  - compatible
+  - reg
+  - reg-names
+  - interrupts
+  - clocks
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    video-codec@7eb10000 {
+        compatible = "brcm,bcm2711-hevc-dec", "raspberrypi,hevc-dec";
+        reg = <0x7eb00000 0x10000>, /* HEVC */
+              <0x7eb10000 0x1000>;  /* INTC */
+        reg-names = "hevc",
+                    "intc";
+
+        interrupts = <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>;
+
+        clocks = <&clk 0>;
+    };
+
+...

-- 
2.34.1

On Wed, Apr 23, 2025 at 06:20:20PM GMT, Dave Stevenson wrote:
> Adds a binding for the HEVC decoder found on the BCM2711 / Raspberry Pi 4,
> and BCM2712 / Raspberry Pi 5.
> 
> Signed-off-by: Dave Stevenson <dave.stevenson@raspberrypi.com>

Also:
subject: only one media prefix. You really do not need two prefixes.

See DT submitting patches.

Best regards,
Krzysztof

On Wed, Apr 23, 2025 at 06:20:20PM GMT, Dave Stevenson wrote:
> Adds a binding for the HEVC decoder found on th +maintainers:
> +  - John Cox <john.cox@raspberrypi.com>
> +  - Dom Cobley <dom@raspberrypi.com>
> +  - Dave Stevenson <dave.stevenson@raspberrypi.com>

> +  - Raspberry Pi internal review list <kernel-list@raspberrypi.com>

Drop, no mailing lists in bindings maintainers. These must be people.

> +
> +description:
> +  The Raspberry Pi HEVC decoder is a hardware video decode accelerator block
> +  found in the BCM2711 and BCM2712 processors used on Raspberry Pi 4 and 5
> +  boards respectively.
> +
> +properties:
> +  compatible:
> +    items:
> +      - enum:
> +          - brcm,bcm2711-hevc-dec
> +          - brcm,bcm2712-hevc-dec
> +      - const: raspberrypi,hevc-dec

Not what Rob asked. You should use specific SoC compatible as fallback.

You referred to file "raspberrypi,pisbe.yaml" before, but there is no
such file in the next.

Before you reply that there is a binding using different rules: well,
there is always poor code. Above two comments are repeated, especially
this about specific compatible - all the time, so these are not new
rules. These are given in reviews since some years.

Best regards,
Krzysztof

Hi Krzysztof

On Fri, 25 Apr 2025 at 08:53, Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On Wed, Apr 23, 2025 at 06:20:20PM GMT, Dave Stevenson wrote:
> > Adds a binding for the HEVC decoder found on th +maintainers:
> > +  - John Cox <john.cox@raspberrypi.com>
> > +  - Dom Cobley <dom@raspberrypi.com>
> > +  - Dave Stevenson <dave.stevenson@raspberrypi.com>
>
> > +  - Raspberry Pi internal review list <kernel-list@raspberrypi.com>
>
> Drop, no mailing lists in bindings maintainers. These must be people.

Ack

> > +
> > +description:
> > +  The Raspberry Pi HEVC decoder is a hardware video decode accelerator block
> > +  found in the BCM2711 and BCM2712 processors used on Raspberry Pi 4 and 5
> > +  boards respectively.
> > +
> > +properties:
> > +  compatible:
> > +    items:
> > +      - enum:
> > +          - brcm,bcm2711-hevc-dec
> > +          - brcm,bcm2712-hevc-dec
> > +      - const: raspberrypi,hevc-dec
>
> Not what Rob asked. You should use specific SoC compatible as fallback.

In which case I don't understand what Rob was asking for.
I asked for clarification in [1], but got no reply. Sending a new
version has at least got an answer, but I'm none the wiser.

Staring at this trying to work out your meaning, you want the generic
first, and SoC specific second? ie
+  compatible:
+    items:
+      - const: raspberrypi,hevc-dec
+      - enum:
+          - brcm,bcm2711-hevc-dec
+          - brcm,bcm2712-hevc-dec

> You referred to file "raspberrypi,pisbe.yaml" before, but there is no
> such file in the next.

Typo.
https://github.com/torvalds/linux/blob/master/Documentation/devicetree/bindings/media/raspberrypi%2Cpispbe.yaml
Reviewed by Rob only just over a year ago [2]

> Before you reply that there is a binding using different rules: well,
> there is always poor code. Above two comments are repeated, especially
> this about specific compatible - all the time, so these are not new
> rules. These are given in reviews since some years.

My Google-foo is totally failing with the only directly relevant
mention of "fallback compatible" I find is [3], which just says to use
them.

You're effectively saying I can't take anything in the kernel tree as
being a valid example as it could be poor code, and a layman such as
myself has no way of telling.
Could you please point me at documentation and examples I can rely on,
or educate me with what is wanted in this situation to avoid me having
to guess?

A further mailing list search has brought up [4] which is a thread
with yourself from 2 years ago which looks to be a very similar
situation. Other than missing the const on the SoC strings (although
that isn't in the merged version of cnm,wave521c.yaml), and two SoC
specific strings, I'm not seeing an obvious difference between there
and here either.

Many thanks
  Dave

> Best regards,
> Krzysztof

[1] https://lore.kernel.org/linux-media/CAPY8ntD3Frq5HzV06OrS1051QfjJFzvqs9H4mUkVnd4QKqiMhg@mail.gmail.com/
[2] https://www.spinics.net/lists/linux-media/msg250095.html
[3] https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-bindings.html#properties
[4] https://patchwork.kernel.org/project/linux-arm-kernel/patch/20230929-wave5_v13_media_master-v13-6-5ac60ccbf2ce@collabora.com/#25567148

On 28/04/2025 12:03, Dave Stevenson wrote:
> Hi Krzysztof
> 
> On Fri, 25 Apr 2025 at 08:53, Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>
>> On Wed, Apr 23, 2025 at 06:20:20PM GMT, Dave Stevenson wrote:
>>> Adds a binding for the HEVC decoder found on th +maintainers:
>>> +  - John Cox <john.cox@raspberrypi.com>
>>> +  - Dom Cobley <dom@raspberrypi.com>
>>> +  - Dave Stevenson <dave.stevenson@raspberrypi.com>
>>
>>> +  - Raspberry Pi internal review list <kernel-list@raspberrypi.com>
>>
>> Drop, no mailing lists in bindings maintainers. These must be people.
> 
> Ack
> 
>>> +
>>> +description:
>>> +  The Raspberry Pi HEVC decoder is a hardware video decode accelerator block
>>> +  found in the BCM2711 and BCM2712 processors used on Raspberry Pi 4 and 5
>>> +  boards respectively.
>>> +
>>> +properties:
>>> +  compatible:
>>> +    items:
>>> +      - enum:
>>> +          - brcm,bcm2711-hevc-dec
>>> +          - brcm,bcm2712-hevc-dec
>>> +      - const: raspberrypi,hevc-dec
>>
>> Not what Rob asked. You should use specific SoC compatible as fallback.
> 
> In which case I don't understand what Rob was asking for.
> I asked for clarification in [1], but got no reply. Sending a new
> version has at least got an answer, but I'm none the wiser.
> 
> Staring at this trying to work out your meaning, you want the generic
> first, and SoC specific second? ie
> +  compatible:
> +    items:
> +      - const: raspberrypi,hevc-dec

Drop

> +      - enum:

That's enum, not fallback.

> +          - brcm,bcm2711-hevc-dec
> +          - brcm,bcm2712-hevc-dec
> 
>> You referred to file "raspberrypi,pisbe.yaml" before, but there is no
>> such file in the next.
> 
> Typo.
> https://github.com/torvalds/linux/blob/master/Documentation/devicetree/bindings/media/raspberrypi%2Cpispbe.yaml
> Reviewed by Rob only just over a year ago [2]

There were some discussions and reasons with explanations.

Feel free to use same arguments and accurately describe the hardware, so
we won't be needing to ask usual questions.

Anyway, we asked for fallback, so you need items, just like every SoC
compatible (see also example schema).


> 
>> Before you reply that there is a binding using different rules: well,
>> there is always poor code. Above two comments are repeated, especially
>> this about specific compatible - all the time, so these are not new
>> rules. These are given in reviews since some years.
> 
> My Google-foo is totally failing with the only directly relevant
> mention of "fallback compatible" I find is [3], which just says to use
> them.
> 
> You're effectively saying I can't take anything in the kernel tree as
> being a valid example as it could be poor code, and a layman such as
> myself has no way of telling.

No, I am saying that argument "I saw someone doing this, so I am allowed
to do the same" is not correct. There are good and bad examples. For
example in my talks I mentioned good examples. The list of good examples
was not accepted to the kernel so well... I just use as an example any
recent Qcom binding using specific compatibles.

> Could you please point me at documentation and examples I can rely on,
> or educate me with what is wanted in this situation to avoid me having
> to guess?
> 
> A further mailing list search has brought up [4] which is a thread
> with yourself from 2 years ago which looks to be a very similar
> situation. Other than missing the const on the SoC strings (although
> that isn't in the merged version of cnm,wave521c.yaml), and two SoC
> specific strings, I'm not seeing an obvious difference between there
> and here either.

How is the [4] relevant? That's IP block from other vendor.

https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-bindings.html#properties

https://elixir.bootlin.com/linux/v6.3-rc6/source/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml#L31

Best regards,
Krzysztof

Thanks Krzysztof

Sorry for the delay in replying - other priorities.

On Mon, 28 Apr 2025 at 18:57, Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On 28/04/2025 12:03, Dave Stevenson wrote:
> > Hi Krzysztof
> >
> > On Fri, 25 Apr 2025 at 08:53, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> >>
> >> On Wed, Apr 23, 2025 at 06:20:20PM GMT, Dave Stevenson wrote:
> >>> Adds a binding for the HEVC decoder found on th +maintainers:
> >>> +  - John Cox <john.cox@raspberrypi.com>
> >>> +  - Dom Cobley <dom@raspberrypi.com>
> >>> +  - Dave Stevenson <dave.stevenson@raspberrypi.com>
> >>
> >>> +  - Raspberry Pi internal review list <kernel-list@raspberrypi.com>
> >>
> >> Drop, no mailing lists in bindings maintainers. These must be people.
> >
> > Ack
> >
> >>> +
> >>> +description:
> >>> +  The Raspberry Pi HEVC decoder is a hardware video decode accelerator block
> >>> +  found in the BCM2711 and BCM2712 processors used on Raspberry Pi 4 and 5
> >>> +  boards respectively.
> >>> +
> >>> +properties:
> >>> +  compatible:
> >>> +    items:
> >>> +      - enum:
> >>> +          - brcm,bcm2711-hevc-dec
> >>> +          - brcm,bcm2712-hevc-dec
> >>> +      - const: raspberrypi,hevc-dec
> >>
> >> Not what Rob asked. You should use specific SoC compatible as fallback.
> >
> > In which case I don't understand what Rob was asking for.
> > I asked for clarification in [1], but got no reply. Sending a new
> > version has at least got an answer, but I'm none the wiser.
> >
> > Staring at this trying to work out your meaning, you want the generic
> > first, and SoC specific second? ie
> > +  compatible:
> > +    items:
> > +      - const: raspberrypi,hevc-dec
>
> Drop
>
> > +      - enum:
>
> That's enum, not fallback.
>
> > +          - brcm,bcm2711-hevc-dec
> > +          - brcm,bcm2712-hevc-dec
> >
> >> You referred to file "raspberrypi,pisbe.yaml" before, but there is no
> >> such file in the next.
> >
> > Typo.
> > https://github.com/torvalds/linux/blob/master/Documentation/devicetree/bindings/media/raspberrypi%2Cpispbe.yaml
> > Reviewed by Rob only just over a year ago [2]
>
> There were some discussions and reasons with explanations.
> Feel free to use same arguments and accurately describe the hardware, so
> we won't be needing to ask usual questions.

Sorry if the previous descriptions hadn't been clear. All the same
points as for raspberrypi,pispbe.yaml apply here, which is why I'd
tried to link to it originally.

Describe the hardware:
Raspberry Pi designed and are the sole owners of the IP for this HEVC
decoder block. This is *not* Broadcom IP.

That design was given to Broadcom as Verilog to wire into the
bus/interrupt/clock fabric of BCM2711, and to manufacture it via TSMC
on a 28nm process node.

A few years later the same design was given to Broadcom to wire into
BCM2712, and to manufacture it on a 16nm process node.

As it is Raspberry Pi owned IP it can be used in other places than
Broadcom SoCs.
Broadcom does not have a licence to use the IP in any other of their chips.

It is the same situation as for raspberrypi,pispbe.yaml except the
block already exists in 2 chips rather than just the 1. There also
isn't a version register in the hardware that is different between
those chips (an oversight noted for future chips).
It could be compared to a Synopsis or Cadence IP block dropped into an
SoC. The vendor prefix happens to be raspberrypi instead of snps or
cdns.

Is there any part that needs to be further clarified?

> Anyway, we asked for fallback, so you need items, just like every SoC
> compatible (see also example schema).
>
>
> >
> >> Before you reply that there is a binding using different rules: well,
> >> there is always poor code. Above two comments are repeated, especially
> >> this about specific compatible - all the time, so these are not new
> >> rules. These are given in reviews since some years.
> >
> > My Google-foo is totally failing with the only directly relevant
> > mention of "fallback compatible" I find is [3], which just says to use
> > them.
> >
> > You're effectively saying I can't take anything in the kernel tree as
> > being a valid example as it could be poor code, and a layman such as
> > myself has no way of telling.
>
> No, I am saying that argument "I saw someone doing this, so I am allowed
> to do the same" is not correct. There are good and bad examples. For
> example in my talks I mentioned good examples. The list of good examples
> was not accepted to the kernel so well... I just use as an example any
> recent Qcom binding using specific compatibles.
>
> > Could you please point me at documentation and examples I can rely on,
> > or educate me with what is wanted in this situation to avoid me having
> > to guess?
> >
> > A further mailing list search has brought up [4] which is a thread
> > with yourself from 2 years ago which looks to be a very similar
> > situation. Other than missing the const on the SoC strings (although
> > that isn't in the merged version of cnm,wave521c.yaml), and two SoC
> > specific strings, I'm not seeing an obvious difference between there
> > and here either.
>
> How is the [4] relevant? That's IP block from other vendor.

It was another example of an IP block belonging to vendor A being
added into an SoC from vendor B, same as the situation here. Raspberry
Pi != Broadcom.

Thanks
  Dave

> https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-bindings.html#properties
>
> https://elixir.bootlin.com/linux/v6.3-rc6/source/Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml#L31
>
> Best regards,
> Krzysztof

On 23/06/2025 19:54, Dave Stevenson wrote:
>>
>>> +          - brcm,bcm2711-hevc-dec
>>> +          - brcm,bcm2712-hevc-dec
>>>
>>>> You referred to file "raspberrypi,pisbe.yaml" before, but there is no
>>>> such file in the next.
>>>
>>> Typo.
>>> https://github.com/torvalds/linux/blob/master/Documentation/devicetree/bindings/media/raspberrypi%2Cpispbe.yaml
>>> Reviewed by Rob only just over a year ago [2]
>>
>> There were some discussions and reasons with explanations.
>> Feel free to use same arguments and accurately describe the hardware, so
>> we won't be needing to ask usual questions.
> 
> Sorry if the previous descriptions hadn't been clear. All the same
> points as for raspberrypi,pispbe.yaml apply here, which is why I'd
> tried to link to it originally.
> 
> Describe the hardware:
> Raspberry Pi designed and are the sole owners of the IP for this HEVC
> decoder block. This is *not* Broadcom IP.
> 
> That design was given to Broadcom as Verilog to wire into the
> bus/interrupt/clock fabric of BCM2711, and to manufacture it via TSMC
> on a 28nm process node.
> 
> A few years later the same design was given to Broadcom to wire into
> BCM2712, and to manufacture it on a 16nm process node.
> 
> As it is Raspberry Pi owned IP it can be used in other places than
> Broadcom SoCs.
> Broadcom does not have a licence to use the IP in any other of their chips.
> 
> It is the same situation as for raspberrypi,pispbe.yaml except the
> block already exists in 2 chips rather than just the 1. There also
> isn't a version register in the hardware that is different between
> those chips (an oversight noted for future chips).
> It could be compared to a Synopsis or Cadence IP block dropped into an
> SoC. The vendor prefix happens to be raspberrypi instead of snps or
> cdns.
> 
> Is there any part that needs to be further clarified?

Dunno, thread is way too old to be in my inbox. Anyway, it is part of
the SoC as you said, so SoC compatibles rules apply here. It's the same
for Synopsys.

> 
>> Anyway, we asked for fallback, so you need items, just like every SoC
>> compatible (see also example schema).

Just implement the feedback.

>>
>>
>>>
>>>> Before you reply that there is a binding using different rules: well,
>>>> there is always poor code. Above two comments are repeated, especially
>>>> this about specific compatible - all the time, so these are not new
>>>> rules. These are given in reviews since some years.
>>>
>>> My Google-foo is totally failing with the only directly relevant
>>> mention of "fallback compatible" I find is [3], which just says to use
>>> them.
>>>
>>> You're effectively saying I can't take anything in the kernel tree as
>>> being a valid example as it could be poor code, and a layman such as
>>> myself has no way of telling.
>>
>> No, I am saying that argument "I saw someone doing this, so I am allowed
>> to do the same" is not correct. There are good and bad examples. For
>> example in my talks I mentioned good examples. The list of good examples
>> was not accepted to the kernel so well... I just use as an example any
>> recent Qcom binding using specific compatibles.
>>
>>> Could you please point me at documentation and examples I can rely on,
>>> or educate me with what is wanted in this situation to avoid me having
>>> to guess?
>>>
>>> A further mailing list search has brought up [4] which is a thread
>>> with yourself from 2 years ago which looks to be a very similar
>>> situation. Other than missing the const on the SoC strings (although
>>> that isn't in the merged version of cnm,wave521c.yaml), and two SoC
>>> specific strings, I'm not seeing an obvious difference between there
>>> and here either.
>>
>> How is the [4] relevant? That's IP block from other vendor.
> 
> It was another example of an IP block belonging to vendor A being
> added into an SoC from vendor B, same as the situation here. Raspberry
> Pi != Broadcom.

People hide real explanation, real facts, so don't use one example for
other case. I was told *explicitly* that Raspberry ISP or whatetever it
was called, was NOT PART OF the SoC. Now you said:
"A few years later the same design was given to Broadcom to wire into
BCM2712, and to manufacture it on a 16nm process node."


Best regards,
Krzysztof