[PATCH v2 11/28] dt-bindings: gpu: panthor: Document AM system bindings

[Karunika Choo]

Mali 5th-Gen AM GPUs expose an AM_SYSTEM block for GPU-wide control and
the AM_ASSIGN block for HW resource assignment outside the GPU
job submission register window.

Document the system node compatible, register and interrupt resources,
GPU clock, and assignment properties for HW resource assignment.

Signed-off-by: Karunika Choo <karunika.choo@xxxxxxx>
---
v2:
- Add an optional AM_ASSIGN register range. Require this range when the
  assignments node is present.
- Describe resource-group assignments for AXI buses, partitions, slices
  and access windows on partition-capable GPUs.
- Allow gpu-arbitration child nodes and the #address-cells, #size-cells
  and ranges properties.
- Remove the panthor-system node-name restriction.
- Remove gpu-supply from the schema and example.
- Add an example with assignments for partition-capable GPU with four
  resource groups.
- Move the MAINTAINERS update to the GPU schema patch.

 .../bindings/gpu/arm,mali-gen5-am-system.yaml | 196 ++++++++++++++++++
 1 file changed, 196 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-system.yaml

diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-system.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-system.yaml
new file mode 100644
index 0000000000000..9e0477b8b723a
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-system.yaml
@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+# Copyright 2026 ARM Limited. All rights reserved.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/arm,mali-gen5-am-system.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Mali 5th-Gen GPU System Device
+
+maintainers:
+  - Liviu Dudau <liviu.dudau@xxxxxxx>
+  - Boris Brezillon <boris.brezillon@xxxxxxxxxxxxx>
+
+properties:
+  compatible:
+    items:
+      - const: arm,mali-gen5-am-system
+
+  reg:
+    minItems: 1
+    maxItems: 2
+
+  reg-names:
+    minItems: 1
+    items:
+      - const: system
+      - const: assign
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  dma-coherent: true
+
+  "#address-cells": true
+
+  "#size-cells": true
+
+  ranges: true
+
+  assignments:
+    type: object
+    additionalProperties: false
+    description:
+      Resource group HW resource assignment. Only valid for partition-capable
+      GPUs.
+
+    properties:
+      "#address-cells":
+        const: 1
+      "#size-cells":
+        const: 0
+
+    required:
+      - "#address-cells"
+      - "#size-cells"
+
+    patternProperties:
+      "^resource-group@[0-3]$":
+        type: object
+        additionalProperties: false
+
+        properties:
+          reg:
+            items:
+              - maximum: 3
+            description: Resource group number.
+
+          arm,axi-bus:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            maximum: 1
+            default: 0
+            description:
+              Static resource-group to AXI bus assignment. Valid field values
+              are 0 for AXI_A and 1 for AXI_B.
+
+          arm,partition-mask:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            maximum: 0xf
+            default: 0
+            description:
+              Static partition-control to resource-group assignment. Bit N
+              selects partition control ID N. Mask must be disjoint across
+              resource groups. Unassigned partitions will be assigned to
+              resource group 0 by default.
+
+          arm,slice-mask:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            maximum: 0xff
+            default: 0
+            description:
+              Static slice to resource-group assignment. Bit N selects slice ID
+              N. Mask must be disjoint across resource groups. Unassigned slices
+              will be assigned to resource group 0 by default.
+
+          arm,access-window-mask:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            maximum: 0xffff
+            default: 0
+            description:
+              Static access-window to resource-group assignment.  Bit N selects
+              access window ID N. Masks must be disjoint across resource groups.
+              Unassigned access-windows will be assigned to resource group 0 by
+              default.
+
+        required:
+          - reg
+
+patternProperties:
+  '^gpu-arbitration@[a-f0-9]+$':
+    $ref: arm,mali-gen5-am-arbitration.yaml#
+
+required:
+  - compatible
+  - reg
+  - reg-names
+  - interrupts
+  - clocks
+
+additionalProperties: false
+
+allOf:
+  - if:
+      required:
+        - assignments
+    then:
+      properties:
+        reg:
+          minItems: 2
+        reg-names:
+          minItems: 2
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    gpu-system@68000000 {
+      compatible = "arm,mali-gen5-am-system";
+      reg = <0x68000000 0x10000>;
+      reg-names = "system";
+      interrupts = <GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>;
+      clocks = <&mali_gpu_clk>;
+    };
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    gpu-system@68000000 {
+      compatible = "arm,mali-gen5-am-system";
+      reg = <0x68000000 0x10000>, <0x68010000 0x10000>;
+      reg-names = "system", "assign";
+      interrupts = <GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>;
+      clocks = <&mali_gpu_clk>;
+
+      assignments {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        resource-group@0 {
+          reg = <0>;
+          arm,axi-bus = <0>;
+          arm,partition-mask = <0x1>;
+          arm,slice-mask = <0x3>;
+          arm,access-window-mask = <0xf>;
+        };
+
+        resource-group@1 {
+          reg = <1>;
+          arm,axi-bus = <0>;
+          arm,partition-mask = <0x2>;
+          arm,slice-mask = <0xc>;
+          arm,access-window-mask = <0xf0>;
+        };
+
+        resource-group@2 {
+          reg = <2>;
+          arm,axi-bus = <1>;
+          arm,partition-mask = <0x4>;
+          arm,slice-mask = <0x30>;
+          arm,access-window-mask = <0xf00>;
+        };
+
+        resource-group@3 {
+          reg = <3>;
+          arm,axi-bus = <1>;
+          arm,partition-mask = <0x8>;
+          arm,slice-mask = <0xc0>;
+          arm,access-window-mask = <0xf000>;
+        };
+      };
+    };
+
+...
-- 
2.43.0