[PATCH 1/4] dt-bindings: interrupt-controller: arm,gic: Document symbolic definitions

Wed Mar 4 09:21:56 PST 2026

Currently, the various GIC DT bindings document the magic GIC and
interrupt numbers used in interrupts properties, but omit any references
to the corresponding symbolic DT binding definitions.

Add references to these symbolic definitions, and convert the examples
to make use of them.  This improves readability, and makes the examples
more similar to what actual users look like.

Signed-off-by: Geert Uytterhoeven <geert+renesas at glider.be>
---
 .../bindings/interrupt-controller/arm,gic-v3.yaml    | 12 +++++++++---
 .../interrupt-controller/arm,gic-v5-iwb.yaml         |  2 ++
 .../bindings/interrupt-controller/arm,gic-v5.yaml    |  2 ++
 .../bindings/interrupt-controller/arm,gic.yaml       | 11 +++++++++--
 4 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
index 360a0643a0b567a4..d1a4b36f06bc3bdb 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
@@ -46,6 +46,7 @@ properties:
       The 1st cell is the interrupt type; 0 for SPI interrupts, 1 for PPI
       interrupts, 2 for interrupts in the Extended SPI range, 3 for the
       Extended PPI range. Other values are reserved for future use.
+      See <dt-bindings/interrupt-controller/arm-gic.h> for symbolic values.
 
       The 2nd cell contains the interrupt number for the interrupt type.
       SPI interrupts are in the range [0-987]. PPI interrupts are in the
@@ -56,6 +57,7 @@ properties:
       bits[3:0] trigger type and level flags.
         1 = edge triggered
         4 = level triggered
+      See <dt-bindings/interrupt-controller/irq.h> for symbolic values.
 
       The 4th cell is a phandle to a node describing a set of CPUs this
       interrupt is affine to. The interrupt must be a PPI, and the node
@@ -237,6 +239,8 @@ additionalProperties: false
 
 examples:
   - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
     gic: interrupt-controller at 2cf00000 {
       compatible = "arm,gic-v3";
       #interrupt-cells = <3>;
@@ -249,7 +253,7 @@ examples:
             <0x2c000000 0x2000>,  // GICC
             <0x2c010000 0x2000>,  // GICH
             <0x2c020000 0x2000>;  // GICV
-      interrupts = <1 9 4>;
+      interrupts = <GIC_PPI 9 IRQ_TYPE_LEVEL_HIGH>;
 
       msi-controller;
       mbi-ranges = <256 128>;
@@ -263,6 +267,8 @@ examples:
     };
 
   - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
     interrupt-controller at 2c010000 {
       compatible = "arm,gic-v3";
       #interrupt-cells = <4>;
@@ -278,7 +284,7 @@ examples:
             <0x2c040000 0x2000>,  // GICC
             <0x2c060000 0x2000>,  // GICH
             <0x2c080000 0x2000>;  // GICV
-      interrupts = <1 9 4 0>;
+      interrupts = <GIC_PPI 9 IRQ_TYPE_LEVEL_HIGH 0>;
 
       msi-controller at 2c200000 {
         compatible = "arm,gic-v3-its";
@@ -307,7 +313,7 @@ examples:
 
     device at 0 {
       reg = <0 4>;
-      interrupts = <1 1 4 &part0>;
+      interrupts = <GIC_PPI 1 IRQ_TYPE_LEVEL_HIGH &part0>;
     };
 
 ...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5-iwb.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5-iwb.yaml
index 99a266a62385a354..3103d314fdcae94c 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5-iwb.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5-iwb.yaml
@@ -46,6 +46,8 @@ properties:
       4 = active high level-sensitive
       8 = active low level-sensitive
 
+      See <dt-bindings/interrupt-controller/irq.h> for symbolic values.
+
     const: 2
 
   interrupt-controller: true
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml
index 86ca7f3ac2810312..16c66b043210d815 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml
@@ -57,6 +57,8 @@ properties:
         4 = active high level-sensitive
         8 = active low level-sensitive
 
+      See <dt-bindings/interrupt-controller/irq.h> for symbolic values.
+
     const: 3
 
   interrupt-controller: true
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml
index ee4c77dac201ad8f..f05917d0071b5446 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml
@@ -74,6 +74,7 @@ properties:
     description: |
       The 1st cell is the interrupt type; 0 for SPI interrupts, 1 for PPI
       interrupts.
+      See <dt-bindings/interrupt-controller/arm-gic.h> for symbolic values.
 
       The 2nd cell contains the interrupt number for the interrupt type.
       SPI interrupts are in the range [0-987].  PPI interrupts are in the
@@ -85,6 +86,7 @@ properties:
           2 = high-to-low edge triggered (invalid for SPIs)
           4 = active high level-sensitive
           8 = active low level-sensitive (invalid for SPIs).
+        See <dt-bindings/interrupt-controller/irq.h> for symbolic values.
         bits[15:8] PPI interrupt cpu mask.  Each bit corresponds to each of
         the 8 possible cpus attached to the GIC.  A bit set to '1' indicated
         the interrupt is wired to that CPU.  Only valid for PPI interrupts.
@@ -92,6 +94,7 @@ properties:
         DEFINED and as such not guaranteed to be present (most SoC available
         in 2014 seem to ignore the setting of this flag and use the hardware
         default value).
+        See <dt-bindings/interrupt-controller/arm-gic.h> for symbolic values.
 
   reg:
     description: |
@@ -201,6 +204,8 @@ examples:
 
   - |
     // GICv2
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
     interrupt-controller at 2c001000 {
       compatible = "arm,cortex-a15-gic";
       #interrupt-cells = <3>;
@@ -209,18 +214,20 @@ examples:
             <0x2c002000 0x2000>,
             <0x2c004000 0x2000>,
             <0x2c006000 0x2000>;
-      interrupts = <1 9 0xf04>;
+      interrupts = <GIC_PPI 9 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>;
     };
 
   - |
     // GICv2m extension for MSI/MSI-x support
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
     interrupt-controller at e1101000 {
       compatible = "arm,gic-400";
       #interrupt-cells = <3>;
       #address-cells = <1>;
       #size-cells = <1>;
       interrupt-controller;
-      interrupts = <1 8 0xf04>;
+      interrupts = <GIC_PPI 8 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>;
       ranges = <0 0xe1100000 0x100000>;
       reg = <0xe1110000 0x01000>,
             <0xe112f000 0x02000>,
-- 
2.43.0


