[PATCH v1 12/27] dt-bindings: gpu: panthor: Document panthor-arbitration bindings

[Karunika Choo <karunika.choo@arm.com>]

Mali 5th-Gen AM GPUs expose arbitration registers outside the GPU node.
The arbitration device contains partition-control and resource-group
register blocks used to grant, yield, and close access windows.

Document partition and resource-group child nodes, each with its own
register range, interrupt and hardware ID.

Signed-off-by: Karunika Choo <karunika.choo@arm.com>
---
 .../gpu/arm,mali-gen5-am-arbitration.yaml     | 125 ++++++++++++++++++
 .../bindings/gpu/arm,mali-gen5-am-system.yaml |   9 ++
 2 files changed, 134 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-arbitration.yaml

diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-arbitration.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-arbitration.yaml
new file mode 100644
index 0000000000000..9ea2b4bb9a344
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-arbitration.yaml
@@ -0,0 +1,125 @@
+# 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-arbitration.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Mali 5th-Gen GPU Arbitration Device
+
+maintainers:
+  - Liviu Dudau <liviu.dudau@arm.com>
+  - Boris Brezillon <boris.brezillon@collabora.com>
+
+description:
+  The arbitration device manages partition-control and resource-group blocks.
+  Each block is described by a child node with its own register range,
+  interrupt and hardware ID. Partition and resource-group IDs are separate
+  namespaces. Access-window IDs are global to the GPU.
+
+properties:
+  $nodename:
+    const: panthor-arbitration
+
+  compatible:
+    const: arm,mali-gen5-am-arbitration
+
+  "#address-cells": true
+
+  "#size-cells": true
+
+  ranges: true
+
+patternProperties:
+  "^partition@[0-9a-f]+$":
+    type: object
+    additionalProperties: false
+    description:
+      Partition control block and its initial resource assignments.
+
+    properties:
+      reg:
+        maxItems: 1
+        description: Partition control register range.
+
+      interrupts:
+        maxItems: 1
+        description: Partition control interrupt.
+
+      arm,id:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Hardware partition control index. Must identify a partition present on
+          the GPU and be unique among this device's partition nodes.
+
+    required:
+      - reg
+      - interrupts
+      - arm,id
+
+  "^resource-group@[0-9a-f]+$":
+    type: object
+    additionalProperties: false
+    description:
+      Resource group block used for access-window messaging.
+
+    properties:
+      reg:
+        maxItems: 1
+        description: Resource group register range.
+
+      interrupts:
+        maxItems: 1
+        description: Resource group interrupt.
+
+      arm,id:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Hardware resource group index. Must identify a resource group
+          present on the GPU and be unique among this device's resource group
+          nodes.
+
+    required:
+      - reg
+      - interrupts
+      - arm,id
+
+  "^gpu@[0-9a-f]+$":
+    $ref: arm,mali-valhall-csf.yaml#
+    properties:
+      compatible:
+        const: arm,mali-gen5-am
+
+required:
+  - compatible
+  - "#address-cells"
+  - "#size-cells"
+  - ranges
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    panthor-arbitration {
+        compatible = "arm,mali-gen5-am-arbitration";
+        #address-cells = <1>;
+        #size-cells = <1>;
+        ranges;
+
+        partition@50000 {
+            reg = <0x50000 0x10000>;
+            interrupts = <GIC_SPI 92 IRQ_TYPE_LEVEL_HIGH 0>;
+            arm,id = <0>;
+        };
+
+        resource-group@c0000 {
+            reg = <0xc0000 0x10000>;
+            interrupts = <GIC_SPI 92 IRQ_TYPE_LEVEL_HIGH 0>;
+            arm,id = <0>;
+        };
+    };
+
+...
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-system.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-system.yaml
index f0689bb8f05a2..a027dc5f4f890 100644
--- a/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-system.yaml
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-system.yaml
@@ -41,6 +41,15 @@ properties:
 
   dma-coherent: true
 
+  "#address-cells": true
+
+  "#size-cells": true
+
+  ranges: true
+
+  panthor-arbitration:
+    $ref: arm,mali-gen5-am-arbitration.yaml#
+
 required:
   - compatible
   - reg
-- 
2.43.0