Skip to contentSkip to conversation

dt-bindings: interrupt-controller: aspeed: Refine AST2700 binding description and example

PATCH In review Ryan Chen 3 participants 7 messages Jul 14, 2025

Subsystems (3)
lore
Share & tools
lore

Ryan Chen

author reviewer
#0 lore raw

PATCH 1/1 dt-bindings: interrupt-controller: aspeed: Refine AST2700 binding description and example

- Update block diagram for better readability and accuracy.
- Clarify the relationship and function of INTC0, INTC1, and the GIC.
- Documentation and example refine.

This enhances the documentation quality and helps developers understand the interrupt controller hierarchy and usage.

---
 .../aspeed,ast2700-intc.yaml                  | 155 +++++++++++++-----
 1 file changed, 112 insertions(+), 43 deletions(-)
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml +112 -43
index 55636d06a674..751a07d49c90 100644
@@ -10,6 +10,33 @@ description:
   This interrupt controller hardware is second level interrupt controller that
   is hooked to a parent interrupt controller. It's useful to combine multiple
   interrupt sources into 1 interrupt to parent interrupt controller.
+  Depend to which INTC0 or INTC1 used.
+  INTC0 and INTC1 are two kinds of interrupt controller with enable and raw
+  status registers for use.
+  INTC0 is used to assert GIC if interrupt in INTC1 asserted.
+  INTC1 is used to assert INTC0 if interrupt of modules asserted.
+  +-----+   +---------+
+  | GIC |---|  INTC0  |
+  +-----+   +---------+
+            +---------+
+            |         |---module0
+            | INTC0_0 |---module1
+            |         |---...
+            +---------+---module31
+            |---....  |
+            +---------+
+            |         |     +---------+
+            | INTC0_11| +---| INTC1   |
+            |         |     +---------+
+            +---------+     +---------+---module0
+                            | INTC1_0 |---module1
+                            |         |---...
+                            +---------+---module31
+                            ...
+                            +---------+---module0
+                            | INTC1_5 |---module1
+                            |         |---...
+                            +---------+---module31
 
 maintainers:
   - Kevin Chen <[email protected]>
@@ -17,49 +44,67 @@ maintainers:
 properties:
   compatible:
     enum:
-      - aspeed,ast2700-intc-ic
+      - aspeed,ast2700-intc0
+      - aspeed,ast2700-intc1
 
   reg:
     maxItems: 1
 
-  interrupt-controller: true
+  'address-cells':
+    const: 2
 
-  '#interrupt-cells':
+  'size-cells':
     const: 2
-    description:
-      The first cell is the IRQ number, the second cell is the trigger
-      type as defined in interrupt.txt in this directory.
-
-  interrupts:
-    maxItems: 6
-    description: |
-      Depend to which INTC0 or INTC1 used.
-      INTC0 and INTC1 are two kinds of interrupt controller with enable and raw
-      status registers for use.
-      INTC0 is used to assert GIC if interrupt in INTC1 asserted.
-      INTC1 is used to assert INTC0 if interrupt of modules asserted.
-      +-----+   +-------+     +---------+---module0
-      | GIC |---| INTC0 |--+--| INTC1_0 |---module2
-      |     |   |       |  |  |         |---...
-      +-----+   +-------+  |  +---------+---module31
-                           |
-                           |   +---------+---module0
-                           +---| INTC1_1 |---module2
-                           |   |         |---...
-                           |   +---------+---module31
-                          ...
-                           |   +---------+---module0
-                           +---| INTC1_5 |---module2
-                               |         |---...
-                               +---------+---module31
 
+  ranges: true
+
+patternProperties:
+  "^interrupt-controller@":
+    type: object
+    description: Interrupt group child nodes
+    additionalProperties: false
+
+    properties:
+      compatible:
+        enum:
+          - aspeed,ast2700-intc-ic
+
+      reg:
+        maxItems: 1
+
+      interrupt-controller: true
+
+      '#interrupt-cells':
+        const: 2
+        description: |
+          The first cell is the IRQ number, the second cell is the trigger
+          type as defined in interrupt.txt in this directory.
+
+      interrupts:
+        minItems: 1
+        maxItems: 6
+        description: |
+          The interrupts provided by this interrupt controller.
+
+      interrupts-extended:
+        minItems: 1
+        maxItems: 6
+        description: |
+          This property is required when defining a cascaded interrupt controller
+          that is connected under another interrupt controller. It specifies the
+          parent interrupt(s) in the upstream controller to which this controller
+          is connected.
+
+    required:
+      - compatible
+      - reg
+      - interrupt-controller
+      - '#interrupt-cells'
+      - interrupts
 
 required:
   - compatible
   - reg
-  - interrupt-controller
-  - '#interrupt-cells'
-  - interrupts
 
 additionalProperties: false
 
@@ -68,19 +113,43 @@ examples:
     #include <dt-bindings/interrupt-controller/arm-gic.h>
 
     bus {
+      #address-cells = <2>;
+      #size-cells = <2>;
+
+      intc0: interrupt-controller@12100000 {
+        compatible = "aspeed,ast2700-intc0";
+        reg = <0 0x12100000 0 0x4000>;
+        ranges = <0x0 0x0 0x0 0x12100000 0x0 0x4000>;
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        intc0_11: interrupt-controller@1b00 {
+          compatible = "aspeed,ast2700-intc-ic";
+          reg = <0 0x12101b00 0x10>;
+          #interrupt-cells = <2>;
+          interrupt-controller;
+          interrupts = <GIC_SPI 192 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>,
+                       <GIC_SPI 193 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>,
+                       <GIC_SPI 194 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>,
+                       <GIC_SPI 195 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>,
+                       <GIC_SPI 196 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>,
+                       <GIC_SPI 197 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>;
+        };
+      };
+
+      intc1: interrupt-controller@14c18000 {
+        compatible = "aspeed,ast2700-intc1";
+        reg = <0 0x14c18000 0 0x400>;
+        ranges = <0x0 0x0 0x0 0x14c18000 0x0 0x400>;
         #address-cells = <2>;
         #size-cells = <2>;
 
-        interrupt-controller@12101b00 {
-            compatible = "aspeed,ast2700-intc-ic";
-            reg = <0 0x12101b00 0 0x10>;
-            #interrupt-cells = <2>;
-            interrupt-controller;
-            interrupts = <GIC_SPI 192 IRQ_TYPE_LEVEL_HIGH>,
-                         <GIC_SPI 193 IRQ_TYPE_LEVEL_HIGH>,
-                         <GIC_SPI 194 IRQ_TYPE_LEVEL_HIGH>,
-                         <GIC_SPI 195 IRQ_TYPE_LEVEL_HIGH>,
-                         <GIC_SPI 196 IRQ_TYPE_LEVEL_HIGH>,
-                         <GIC_SPI 197 IRQ_TYPE_LEVEL_HIGH>;
+        intc1_0: interrupt-controller@100 {
+          compatible = "aspeed,ast2700-intc-ic";
+          reg = <0x0 0x100 0x0 0x10>;
+          #interrupt-cells = <2>;
+          interrupt-controller;
+          interrupts-extended = <&intc0_11 0 (GIC_CPU_MASK_SIMPLE(4) | IRQ_TYPE_LEVEL_HIGH)>;
         };
+      };
     };
Signature · 1 line
2.34.1
#1 lore raw
Quoted 6 lines · Ryan Chen

- Update block diagram for better readability and accuracy.
- Clarify the relationship and function of INTC0, INTC1, and the GIC.
- Documentation and example refine.

This enhances the documentation quality and helps developers understand the interrupt controller hierarchy and usage.

Changing ABI (compatibles) is not enhancing quality and is not explained here.

Quoted 45 lines
---
 .../aspeed,ast2700-intc.yaml                  | 155 +++++++++++++-----
 1 file changed, 112 insertions(+), 43 deletions(-)
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml +27 -0
index 55636d06a674..751a07d49c90 100644
@@ -10,6 +10,33 @@ description:
   This interrupt controller hardware is second level interrupt controller that
   is hooked to a parent interrupt controller. It's useful to combine multiple
   interrupt sources into 1 interrupt to parent interrupt controller.
+  Depend to which INTC0 or INTC1 used.
+  INTC0 and INTC1 are two kinds of interrupt controller with enable and raw
+  status registers for use.
+  INTC0 is used to assert GIC if interrupt in INTC1 asserted.
+  INTC1 is used to assert INTC0 if interrupt of modules asserted.
+  +-----+   +---------+
+  | GIC |---|  INTC0  |
+  +-----+   +---------+
+            +---------+
+            |         |---module0
+            | INTC0_0 |---module1
+            |         |---...
+            +---------+---module31
+            |---....  |
+            +---------+
+            |         |     +---------+
+            | INTC0_11| +---| INTC1   |
+            |         |     +---------+
+            +---------+     +---------+---module0
+                            | INTC1_0 |---module1
+                            |         |---...
+                            +---------+---module31
+                            ...
+                            +---------+---module0
+                            | INTC1_5 |---module1
+                            |         |---...
+                            +---------+---module31
 
 maintainers:
   - Kevin Chen <[email protected]>

Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml maintainers: · line 48

Quoted 6 lines
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml +2 -1
@@ -17,49 +44,67 @@ maintainers:
 properties:
   compatible:
     enum:
-      - aspeed,ast2700-intc-ic
+      - aspeed,ast2700-intc0
+      - aspeed,ast2700-intc1

No, you cannot change compatibles.

You just rewrite entire bindings just because of wish to "refine"? Hardware changed? What happened here?

You need to clearly describe ABI impact and reasons, like possible bugs you address. You cannot just rewrite existing binding into something entirely else.

Best regards,
Krzysztof

author reviewer
#2 lore raw
Quoted 4 lines

Subject: Re: [PATCH] dt-bindings: interrupt-controller: aspeed: Refine AST2700 binding description and example

On 14/07/2025 09:17, Ryan Chen wrote:

Quoted 9 lines
Quoted 6 lines

- Update block diagram for better readability and accuracy.
- Clarify the relationship and function of INTC0, INTC1, and the GIC.
- Documentation and example refine.

This enhances the documentation quality and helps developers understand the interrupt controller hierarchy and usage.

Changing ABI (compatibles) is not enhancing quality and is not explained here.

Sorry, I would add following in description.
- add 'aspeed,ast2700-intc0' and 'aspeed,ast2700-intc1' compatible strings for parent interrupt controller nodes, in addition to the existing 'aspeed,ast2700-intc-ic' for child nodes.

Quoted 60 lines
Quoted 4 lines
---
 .../aspeed,ast2700-intc.yaml                  | 155

+++++++++++++-----

Quoted 13 lines
 1 file changed, 112 insertions(+), 43 deletions(-)

diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast270 0-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast270 0-intc.yaml index 55636d06a674..751a07d49c90 100644
---
a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast270 0-intc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/aspeed,as +++ t2700-intc.yaml

Review description: · line 10

Quoted 1 line
(quoted diff) +0 -0
@@ -10,6 +10,33 @@ description:
   This interrupt controller hardware is second level interrupt controller

that

Quoted 36 lines
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml +27 -0
   is hooked to a parent interrupt controller. It's useful to combine multiple
   interrupt sources into 1 interrupt to parent interrupt controller.
+  Depend to which INTC0 or INTC1 used.
+  INTC0 and INTC1 are two kinds of interrupt controller with enable
+ and raw  status registers for use.
+  INTC0 is used to assert GIC if interrupt in INTC1 asserted.
+  INTC1 is used to assert INTC0 if interrupt of modules asserted.
+  +-----+   +---------+
+  | GIC |---|  INTC0  |
+  +-----+   +---------+
+            +---------+
+            |         |---module0
+            | INTC0_0 |---module1
+            |         |---...
+            +---------+---module31
+            |---....  |
+            +---------+
+            |         |     +---------+
+            | INTC0_11| +---| INTC1   |
+            |         |     +---------+
+            +---------+     +---------+---module0
+                            | INTC1_0 |---module1
+                            |         |---...
+                            +---------+---module31
+                            ...
+                            +---------+---module0
+                            | INTC1_5 |---module1
+                            |         |---...
+                            +---------+---module31
 
 maintainers:
   - Kevin Chen <[email protected]> @@ -17,49 +44,67 @@

maintainers:
properties:
compatible:
enum:

Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml maintainers: · line 48

Quoted 3 lines
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml +2 -1
-      - aspeed,ast2700-intc-ic
+      - aspeed,ast2700-intc0
+      - aspeed,ast2700-intc1
Quoted 5 lines

No, you cannot change compatibles.

You just rewrite entire bindings just because of wish to "refine"? Hardware changed? What happened here?

Thank you for your feedback.
There is no hardware change.
My intention was to clarify the interrupt controller hierarchy by introducing separate compatible strings for the parent nodes.

Sorry, I don't change original compatibles, I add parent compatibles aspeed,ast2700-intc0, aspeed,ast2700-intc1. Modify original to be child nodes, and still keep the same compatible aspeed,ast2700-intc-ic

Quoted 5 lines

You need to clearly describe ABI impact and reasons, like possible bugs you address. You cannot just rewrite existing binding into something entirely else.

Best regards,
Krzysztof

#3 lore raw
Quoted 11 lines · Ryan Chen
Quoted 11 lines

Subject: Re: [PATCH] dt-bindings: interrupt-controller: aspeed: Refine AST2700 binding description and example

Quoted 6 lines · Ryan Chen

- Update block diagram for better readability and accuracy.
- Clarify the relationship and function of INTC0, INTC1, and the GIC.
- Documentation and example refine.

This enhances the documentation quality and helps developers understand the interrupt controller hierarchy and usage.

Quoted 7 lines
Quoted 2 lines

Changing ABI (compatibles) is not enhancing quality and is not explained here.

Sorry, I would add following in description.
- add 'aspeed,ast2700-intc0' and 'aspeed,ast2700-intc1' compatible strings for parent interrupt controller nodes, in addition to the existing 'aspeed,ast2700-intc-ic' for child nodes.

It does not say why is this needed in the first place...

Best regards,
Krzysztof

#4 lore raw
Quoted 14 lines · Krzysztof Kozlowski
Quoted 13 lines · Ryan Chen
Quoted 13 lines

Subject: Re: [PATCH] dt-bindings: interrupt-controller: aspeed: Refine AST2700 binding description and example

Quoted 6 lines · Ryan Chen

- Update block diagram for better readability and accuracy.
- Clarify the relationship and function of INTC0, INTC1, and the GIC.
- Documentation and example refine.

This enhances the documentation quality and helps developers understand the interrupt controller hierarchy and usage.

Changing ABI (compatibles) is not enhancing quality and is not explained here.

Quoted 8 lines
Quoted 5 lines

Sorry, I would add following in description.
- add 'aspeed,ast2700-intc0' and 'aspeed,ast2700-intc1' compatible strings for parent interrupt controller nodes, in addition to the existing 'aspeed,ast2700-intc-ic' for child nodes.

It does not say why is this needed in the first place...

And also never tested :/. I won't be reviewing it.

Best regards,
Krzysztof

author reviewer
#5 lore raw
Quoted 25 lines

Subject: Re: [PATCH] dt-bindings: interrupt-controller: aspeed: Refine AST2700 binding description and example

Quoted 5 lines · Krzysztof Kozlowski
Quoted 4 lines · Ryan Chen
Quoted 4 lines

Subject: Re: [PATCH] dt-bindings: interrupt-controller: aspeed:
Refine AST2700 binding description and example

On 14/07/2025 09:17, Ryan Chen wrote:

Quoted 8 lines
Quoted 8 lines
Quoted 8 lines
Quoted 6 lines

- Update block diagram for better readability and accuracy.
- Clarify the relationship and function of INTC0, INTC1, and the GIC.
- Documentation and example refine.

This enhances the documentation quality and helps developers understand the interrupt controller hierarchy and usage.

Changing ABI (compatibles) is not enhancing quality and is not explained

here.

Quoted 7 lines
Quoted 6 lines
Quoted 1 line

Sorry, I would add following in description.
- add 'aspeed,ast2700-intc0' and 'aspeed,ast2700-intc1' compatible strings for parent interrupt controller nodes, in addition to the existing 'aspeed,ast2700-intc-ic' for child nodes.

Quoted 3 lines
Quoted 2 lines

It does not say why is this needed in the first place...

And also never tested :/. I won't be reviewing it.

Thanks, will update example and test it, and send v2

Quoted 4 lines

Best regards,
Krzysztof

#6 lore raw
In reply to Ryan Chen
Quoted 4 lines · Ryan Chen

- Update block diagram for better readability and accuracy.
- Clarify the relationship and function of INTC0, INTC1, and the GIC.
- Documentation and example refine.

Quoted 8 lines

This enhances the documentation quality and helps developers understand the interrupt controller hierarchy and usage.

---
 .../aspeed,ast2700-intc.yaml                  | 155 +++++++++++++-----
 1 file changed, 112 insertions(+), 43 deletions(-)

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml: address-cells: missing type definition /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml: size-cells: missing type definition Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dts:39.15-41: Warning (reg_format): /example-0/bus/interrupt-controller@12100000/interrupt-controller@1b00:reg: property has invalid length (12 bytes) (#address-cells == 2, #size-cells == 2) Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: Warning (pci_device_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: Warning (pci_device_bus_num): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: Warning (simple_bus_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: Warning (i2c_bus_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: Warning (spi_bus_reg): Failed prerequisite 'reg_format' /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: interrupt-controller@12100000 (aspeed,ast2700-intc0): '#address-cells', '#size-cells' do not match any of the regexes: '^interrupt-controller@', '^pinctrl-[0-9]+$'
from schema $id: http://devicetree.org/schemas/interrupt-controller/aspeed,ast2700-intc.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: interrupt-controller@12100000 (aspeed,ast2700-intc0): interrupt-controller@1b00:reg:0: [0, 303045376, 16] is too short
from schema $id: http://devicetree.org/schemas/reg.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: interrupt-controller@14c18000 (aspeed,ast2700-intc1): '#address-cells', '#size-cells' do not match any of the regexes: '^interrupt-controller@', '^pinctrl-[0-9]+$'
from schema $id: http://devicetree.org/schemas/interrupt-controller/aspeed,ast2700-intc.yaml#
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.example.dtb: interrupt-controller@14c18000 (aspeed,ast2700-intc1): interrupt-controller@100: 'interrupts' is a required property
from schema $id: http://devicetree.org/schemas/interrupt-controller/aspeed,ast2700-intc.yaml#

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/[email protected]

The base for the series is generally the latest rc1. A different dependency should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above error(s), then make sure 'yamllint' is installed and dt-schema is up to date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note that DT_SCHEMA_FILES can be set to your schema file to speed up checking your schema. However, it must be unset to test all examples with your schema.