[PATCH v2 13/28] dt-bindings: gpu: panthor: Document panthor-arbitration bindings

[Karunika Choo]

Mali 5th-Gen AM GPUs expose partition-control and resource-group
registers outside the GPU node.

Document named register and interrupt resources in the arbitration node.
The pcN and rgN names identify the hardware blocks.

Document initial access-window and slice assignments in partition child
nodes. The reg property identifies the partition-control index.

Signed-off-by: Karunika Choo <karunika.choo@xxxxxxx>
---
v2:
- Return to using named register and interrupt arrays instead of
  individual entries in child nodes.
- Added register and interrupt entries for partition-capable GPUs
  (rg[0-3], pc[0-3]).
- Introduce partition nodes to define default access-window and slice
  masks.
- Point child Panthor device node to new arm,mali-gen5-am.yaml
- Added partition-capable GPU example entry.

v2:
- Introduce assignment_lock to protect assignments allowing serialized
  lookup without the need for READ_ONCE or WRITE_ONCE.
- Add pending_aw_request_mask to track and replay pending requests
  arriving before AW assignments are initialized.

 .../gpu/arm,mali-gen5-am-arbitration.yaml     | 198 ++++++++++++++++++
 1 file changed, 198 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..633dd823bd3d5
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-gen5-am-arbitration.yaml
@@ -0,0 +1,198 @@
+# 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@xxxxxxx>
+  - Boris Brezillon <boris.brezillon@xxxxxxxxxxxxx>
+
+description:
+  The arbitration device manages GPU partition-control and resource-group
+  blocks. Register and interrupt names pcN and rgN identify their hardware
+  indices. Partition child nodes describe initial resource assignments,
+  with reg identifying the partition-control index. Access-window and slice
+  indices are global to the GPU, each resource may be assigned to at most one
+  partition.
+
+properties:
+  compatible:
+    const: arm,mali-gen5-am-arbitration
+
+  reg:
+    minItems: 2
+    maxItems: 8
+
+  reg-names:
+    minItems: 2
+    maxItems: 8
+    items:
+      enum: [pc0, pc1, pc2, pc3, rg0, rg1, rg2, rg3]
+
+  interrupts:
+    minItems: 2
+    maxItems: 8
+
+  interrupt-names:
+    minItems: 2
+    maxItems: 8
+    items:
+      enum: [pc0, pc1, pc2, pc3, rg0, rg1, rg2, rg3]
+
+  "#address-cells": true
+  "#size-cells": true
+  ranges: true
+
+  partitions:
+    type: object
+    additionalProperties: false
+
+    properties:
+      "#address-cells":
+        const: 1
+      "#size-cells":
+        const: 0
+
+    required:
+      - "#address-cells"
+      - "#size-cells"
+
+    patternProperties:
+      "^partition@[0-3]$":
+        type: object
+        additionalProperties: false
+        description:
+          Initial partition resource assignments.
+
+        properties:
+          reg:
+            items:
+              - maximum: 3
+            description: Partition control number.
+
+          arm,access-window-mask:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            maximum: 0xffff
+            default: 0
+            description:
+              Initial access window assignment mask. Bit N selects global
+              access window ID N. Masks must be disjoint across partitions.
+              If omitted on partitioning-capable GPUs, no access windows are
+              assigned by default. Non-partitioning GPUs will have all AWs
+              assigned to pc0 if value is 0 or not defined.
+
+          arm,slice-mask:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            maximum: 0xff
+            default: 0
+            description:
+              Initial slice assignment mask. Bit N selects global slice ID N.
+              Masks must be disjoint across partitions. If omitted, no
+              partitions are created by default. This property is only valid for
+              partition-capable GPUs.
+
+        required:
+          - reg
+
+patternProperties:
+  "^gpu@[0-9a-f]+$":
+    $ref: arm,mali-gen5-am.yaml#
+
+required:
+  - compatible
+  - reg
+  - reg-names
+  - interrupts
+  - interrupt-names
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    gpu-arbitration@50000 {
+      compatible = "arm,mali-gen5-am-arbitration";
+      reg = <0x50000 0x10000>,
+            <0xC0000 0x10000>;
+      reg-names = "pc0", "rg0";
+      interrupts = <GIC_SPI 92 IRQ_TYPE_LEVEL_HIGH 0>,
+                    <GIC_SPI 92 IRQ_TYPE_LEVEL_HIGH 0>;
+      interrupt-names = "pc0", "rg0";
+
+      partitions {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        partition@0 {
+            reg = <0x0>;
+            arm,access-window-mask = <0xffff>;
+        };
+      };
+    };
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    gpu-arbitration@40000 {
+      compatible = "arm,mali-gen5-am-arbitration";
+      reg = <0x40000 0x10000>,
+            <0x50000 0x10000>,
+            <0xC0000 0x10000>;
+      reg-names = "pc0", "pc1", "rg0";
+      interrupts = <GIC_SPI 92 IRQ_TYPE_LEVEL_HIGH 0>,
+                    <GIC_SPI 93 IRQ_TYPE_LEVEL_HIGH 0>,
+                    <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH 0>;
+      interrupt-names = "pc0", "pc1", "rg0";
+
+      partitions {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        partition@0 {
+            reg = <0x0>;
+            arm,access-window-mask = <0xf>;
+            arm,slice-mask = <0x3>;
+        };
+        partition@1 {
+            reg = <0x1>;
+            arm,access-window-mask = <0xf0>;
+            arm,slice-mask = <0xc>;
+        };
+      };
+    };
+
+    gpu-arbitration@60000 {
+      compatible = "arm,mali-gen5-am-arbitration";
+      reg = <0x60000 0x10000>,
+            <0x70000 0x10000>,
+            <0xD0000 0x10000>;
+      reg-names = "pc2", "pc3", "rg1";
+      interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH 0>,
+                    <GIC_SPI 96 IRQ_TYPE_LEVEL_HIGH 0>,
+                    <GIC_SPI 97 IRQ_TYPE_LEVEL_HIGH 0>;
+      interrupt-names = "pc2", "pc3", "rg1";
+
+      partitions {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        partition@2 {
+            reg = <0x2>;
+            arm,access-window-mask = <0xf00>;
+            arm,slice-mask = <0x30>;
+        };
+        partition@3 {
+            reg = <0x3>;
+            arm,access-window-mask = <0xf000>;
+            arm,slice-mask = <0xc0>;
+        };
+      };
+    };
+
+...
-- 
2.43.0