Compared to the previous generation IC, the MT8189 uses 34-bit iova
address-space (16GB) and requires a single clock configuration.
Therefore, add "mediatek,mt8189-jpgdec" compatible to the binding document.
Additionally, it corrects the inheritance for MT8188, aligning it
with MT8189 due to their shared architecture and 34-bit iova address
space (16GB) and singlesingle clock requirement.
Previously, MT8188 was incorrectly defined alongside SoCs with 32-bit
iova address-space (4GB), such as "mediatek,mt2701-jpgdec". This mismatch
results in an ABI break, as MT8188 cannot function correctly under
the 32-bit iova address-space (4GB) configuration.

Key changes include:
- Introducing "mediatek,mt8189-jpgdec" as a new compatible string to
  represent the correct architecture.
- Updating MT8188 to inherit from MT8189, ensuring proper support for
  34-bit iova address-space (16GB) and simplifying clock configuration.
- Add property "mediatek,larb" for MT8189 requirements.
- Improved formatting for better readability and consistency.

These changes ensure that both MT8188 and MT8189 are correctly supported
with the necessary 34-bit iova address-space (16GB), while maintaining
compatibility with their shared architecture.

Extensive internal review and testing have been conducted to validate
these changes and ensure compliance with DT binding standards.

Signed-off-by: Jianhua Lin <jianhua.lin@mediatek.com>
---
 .../bindings/media/mediatek-jpeg-decoder.yaml | 50 ++++++++++++++++---
 1 file changed, 44 insertions(+), 6 deletions(-)

diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml
index a4aacd3eb189..814b53ef46e7 100644
--- a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml
+++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml
@@ -17,13 +17,19 @@ properties:
     oneOf:
       - items:
           - enum:
-              - mediatek,mt8173-jpgdec
               - mediatek,mt2701-jpgdec
+              - mediatek,mt8173-jpgdec
+      - items:
+          - enum:
+              - mediatek,mt8189-jpgdec
       - items:
           - enum:
               - mediatek,mt7623-jpgdec
-              - mediatek,mt8188-jpgdec
           - const: mediatek,mt2701-jpgdec
+      - items:
+          - enum:
+              - mediatek,mt8188-jpgdec
+          - const: mediatek,mt8189-jpgdec
 
   reg:
     maxItems: 1
@@ -32,13 +38,16 @@ properties:
     maxItems: 1
 
   clocks:
+    minItems: 1
     maxItems: 2
-    minItems: 2
 
   clock-names:
-    items:
-      - const: jpgdec-smi
-      - const: jpgdec
+    minItems: 1
+    maxItems: 2
+
+  mediatek,larb:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: a phandle to the smi_larb node.
 
   power-domains:
     maxItems: 1
@@ -51,6 +60,35 @@ properties:
       Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details.
       Ports are according to the HW.
 
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - mediatek,mt2701-jpgdec
+              - mediatek,mt8173-jpgdec
+
+    then:
+      properties:
+        clock-names:
+          items:
+            - const: jpgdec-smi
+            - const: jpgdec
+
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - mediatek,mt8189-jpgdec
+
+    then:
+      properties:
+        clock-names:
+          items:
+            - const: jpgdec
+
 required:
   - compatible
   - reg
-- 
2.45.2

Hi,

Le mercredi 24 décembre 2025 à 11:17 +0800, Jianhua Lin a écrit :
> Compared to the previous generation IC, the MT8189 uses 34-bit iova
> address-space (16GB) and requires a single clock configuration.
> Therefore, add "mediatek,mt8189-jpgdec" compatible to the binding document.
> Additionally, it corrects the inheritance for MT8188, aligning it
> with MT8189 due to their shared architecture and 34-bit iova address
> space (16GB) and singlesingle clock requirement.

singlesingle -> single

> Previously, MT8188 was incorrectly defined alongside SoCs with 32-bit
> iova address-space (4GB), such as "mediatek,mt2701-jpgdec". This mismatch
> results in an ABI break, as MT8188 cannot function correctly under
> the 32-bit iova address-space (4GB) configuration.

Was already mentioned earlier, badly introduce DT code create an ABI, and fixing
it is the ABI break, not the other way around. The MT8188 issue should be fixed
on its own, with proper Fixes: tag.

> 
> Key changes include:
> - Introducing "mediatek,mt8189-jpgdec" as a new compatible string to
>   represent the correct architecture.
> - Updating MT8188 to inherit from MT8189, ensuring proper support for

It is odd to have older chips inherit from newer one, should be reversed
assuming you can fix MT8188. See more comment below.

>   34-bit iova address-space (16GB) and simplifying clock configuration.
> - Add property "mediatek,larb" for MT8189 requirements.
> - Improved formatting for better readability and consistency.

Do style change in it own commit, I don't mixing reformating, with fixed and new
feature in one patch will create much interest in your set from the DT
maintainers. So please break this into at least 3 patches.

> These changes ensure that both MT8188 and MT8189 are correctly supported
> with the necessary 34-bit iova address-space (16GB), while maintaining
> compatibility with their shared architecture.
> 
> Extensive internal review and testing have been conducted to validate
> these changes and ensure compliance with DT binding standards.

This last paragraph does not seem relevant as a commit message. Consider reading
this message in 5 years, would it be useful, and answer is not, since we can't
see the review and testing process.

> 
> Signed-off-by: Jianhua Lin <jianhua.lin@mediatek.com>
> ---
>  .../bindings/media/mediatek-jpeg-decoder.yaml | 50 ++++++++++++++++---
>  1 file changed, 44 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml
> index a4aacd3eb189..814b53ef46e7 100644
> --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml
> +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml
> @@ -17,13 +17,19 @@ properties:
>      oneOf:
>        - items:
>            - enum:
> -              - mediatek,mt8173-jpgdec
>                - mediatek,mt2701-jpgdec
> +              - mediatek,mt8173-jpgdec

I guess you sorted these, this is the type of style change that makes reviewer
unhappy, do this cleanup on it own.

One thing the driver implementation tells me is that mediatek,mt8173-jpgdec is
not different from mediatek,mt2701-jpgdec, so in theory, the DTS should have
aimed for the second item and an implementation of:

  compatible = "mediatek,mt8173-jpgdec", "mediatek,mt2701-jpgdec";

That just shows the screw-up started a while ago, I'm not saying to change that
now.

> +      - items:
> +          - enum:
> +              - mediatek,mt8189-jpgdec

That one make no sense, if you want to allow this compatible alone, put it the
very first item, its meant for that. Though, considering the chronology, it
would be logical to say that MT8189 is based on MT8188. If we go that way,
MT8188 should get added into the single item choice and the enum/const pair
shoudl be reversed.

>        - items:
>            - enum:
>                - mediatek,mt7623-jpgdec
> -              - mediatek,mt8188-jpgdec

This must be kept, its unfortunate, but its in the ABI.

>            - const: mediatek,mt2701-jpgdec
> +      - items:
> +          - enum:
> +              - mediatek,mt8188-jpgdec
> +          - const: mediatek,mt8189-jpgdec

This would be reversed.

On the implementation side, in code, you'd introduce a variants that matches
mediatek,mt8188-jpgdec, this will ensure the driver now works properly with past
DTS.

Then in DTS, which is not my domain here at all, what is appropriate will depend
on what happens if you assume MT8188 is same as MT2701. In my personal opinion,
if that is unusable or worse crash or hang the systems, I'd drop the broken
"mediatek,mt2701-jpgdec" so it won't probe anymore on older drivers. If its
usable / used in some ways, e.g. if it work on 4GB systems, you'll have to leave
it this way, since you'd regress some users.

The rest is a bit over my head, I've a simple users of DT like you, but
hopefully these hints are good enough to un-lock the situation. Notice the
chronology logic needs to be applied down below too.

>  
>    reg:
>      maxItems: 1
> @@ -32,13 +38,16 @@ properties:
>      maxItems: 1
>  
>    clocks:
> +    minItems: 1
>      maxItems: 2
> -    minItems: 2
>  
>    clock-names:
> -    items:
> -      - const: jpgdec-smi
> -      - const: jpgdec

So what happened once the driver on MT8188 tried to enable jpgdec-smi clock ?
This is relevant to what can and cannot be changed, was it completely unusable ?

regards,
Nicolas

> +    minItems: 1
> +    maxItems: 2
> +
> +  mediatek,larb:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: a phandle to the smi_larb node.
>  
>    power-domains:
>      maxItems: 1
> @@ -51,6 +60,35 @@ properties:
>        Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details.
>        Ports are according to the HW.
>  
> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - mediatek,mt2701-jpgdec
> +              - mediatek,mt8173-jpgdec
> +
> +    then:
> +      properties:
> +        clock-names:
> +          items:
> +            - const: jpgdec-smi
> +            - const: jpgdec
> +
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - mediatek,mt8189-jpgdec
> +
> +    then:
> +      properties:
> +        clock-names:
> +          items:
> +            - const: jpgdec
> +
>  required:
>    - compatible
>    - reg

On Wed, Dec 24, 2025 at 11:17:19AM +0800, Jianhua Lin wrote:
> Compared to the previous generation IC, the MT8189 uses 34-bit iova
> address-space (16GB) and requires a single clock configuration.
> Therefore, add "mediatek,mt8189-jpgdec" compatible to the binding document.
> Additionally, it corrects the inheritance for MT8188, aligning it
> with MT8189 due to their shared architecture and 34-bit iova address
> space (16GB) and singlesingle clock requirement.
> Previously, MT8188 was incorrectly defined alongside SoCs with 32-bit
> iova address-space (4GB), such as "mediatek,mt2701-jpgdec". This mismatch
> results in an ABI break, as MT8188 cannot function correctly under
> the 32-bit iova address-space (4GB) configuration.
> 
> Key changes include:
> - Introducing "mediatek,mt8189-jpgdec" as a new compatible string to
>   represent the correct architecture.
> - Updating MT8188 to inherit from MT8189, ensuring proper support for
>   34-bit iova address-space (16GB) and simplifying clock configuration.
> - Add property "mediatek,larb" for MT8189 requirements.
> - Improved formatting for better readability and consistency.
> 
> These changes ensure that both MT8188 and MT8189 are correctly supported
> with the necessary 34-bit iova address-space (16GB), while maintaining
> compatibility with their shared architecture.
> 
> Extensive internal review and testing have been conducted to validate
> these changes and ensure compliance with DT binding standards.

That's not even true. If you did extensive internal review, then people
would have tell you that you never mix fixes with new features in one
commit. Never, that's like basic rule.

Best regards,
Krzysztof