Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-interrupt.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/interrupt-controller/aspeed,ast2700-interrupt.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: ASPEED AST2700 Interrupt Controllers (INTC0/INTC1)

description: |
  The ASPEED AST2700 SoC integrates two interrupt controller designs:

    - INTC0: Primary controller that routes interrupt sources to upstream,
      processor-specific interrupt controllers

    - INTC1: Secondary controller whose interrupt outputs feed into INTC0

  The SoC contains four processors to which interrupts can be routed:

    - PSP: Primary Service Processor (Cortex-A35)
    - SSP: Secondary Service Processor (Cortex-M4)
    - TSP: Tertiary Service Processor (Cortex-M4)
    - BMCU: Boot MCU (a RISC-V microcontroller)

  The following diagram illustrates the overall architecture of the
  ASPEED AST2700 interrupt controllers:

                  +-----------+                +-----------+
                  |   INTC0   |                | INTC1(0)  |
                  +-----------+                +-----------+
                  |   Router  | +-----------+  |   Router  |
                  | out   int | +Peripheral +  | out   int |
  +-----------+   |  0     0  <-+Controllers+  | INTM      | +-----------+
  |PSP GIC  <-|---+  .     .  | +-----------+  |  .     .  <-+Peripheral +
  +-----------+   |  .     .  |                |  .     .  | +Controllers+
  +-----------+   |  .     .  |                |  .     .  | +-----------+
  |SSP NVIC <-|---+  .     .  <----------------+  .     .  |
  +-----------+   |  .     .  |                |  .     .  |
  +-----------+   |  .     .  <--------        |  .     .  |
  |TSP NVIC <-|---+  .     .  |       |    ----+  .     .  |
  +-----------+   |  .     .  |       |    |   |  O     P  |
                  |  .     .  |       |    |   +-----------+
                  |  .     .  <----   |    --------------------
                  |  .     .  |   |   |        +-----------+  |
                  |  M     N  |   |   ---------+  INTC1(1) |  |
                  +-----------+   |            +-----------+  |
                                  |                  .        |
                                  |            +-----------+  |
                                  -------------+  INTC1(N) |  |
                                               +-----------+  |
  +--------------+                                            |
  + BMCU APLIC <-+---------------------------------------------
  +--------------+

  INTC0 supports:
    - 128 local peripheral interrupt inputs
    - Fan-in from up to three INTC1 instances via banked interrupt lines (INTM)
    - Local peripheral interrupt outputs
    - Merged interrupt outputs
    - Software interrupt outputs (SWINT)
    - Configurable interrupt routes targeting the PSP, SSP, and TSP

  INTC1 supports:
    - 192 local peripheral interrupt inputs
    - Banked interrupt outputs (INTM, 5 x 6 banks x 32 interrupts per bank)
    - Configurable interrupt routes targeting the PSP, SSP, TSP, and BMCU

  One INTC1 instance is always present, on the SoC's IO die. A further two
  instances may be attached to the SoC's one INTC0 instance via LTPI (LVDS
  Tunneling Protocol & Interface).

  Interrupt numbering model
  -------------------------
  The binding uses a controller-local numbering model. Peripheral device
  nodes use the INTCx local interrupt number (hwirq) in their 'interrupts' or
  'interrupts-extended' properties.

  For AST2700, INTC0 exposes the following (inclusive) input ranges:

    - 000..479: Independent interrupts
    - 480..489: INTM0-INTM9
    - 490..499: INTM10-INTM19
    - 500..509: INTM20-INTM29
    - 510..519: INTM30-INTM39
    - 520..529: INTM40-INTM49

  INTC0's (inclusive) output ranges are as follows:

    - 000..127: 1:1 local peripheral interrupt output to PSP
    - 144..151: Software interrupts from the SSP output to PSP
    - 152..159: Software interrupts from the TSP output to PSP
    - 192..201: INTM0-INTM9 banked outputs to PSP
    - 208..217: INTM30-INTM39 banked outputs to PSP
    - 224..233: INTM40-INTM49 banked outputs to PSP
    - 256..383: 1:1 local peripheral interrupt output to SSP
    - 384..393: INTM10-INTM19 banked outputs to SSP
    - 400..407: Software interrupts from the PSP output to SSP
    - 408..415: Software interrupts from the TSP output to SSP
    - 426..553: 1:1 local peripheral interrupt output to TSP
    - 554..563: INTM20-INTM29 banked outputs to TSP
    - 570..577: Software interrupts from the PSP output to TSP
    - 578..585: Software interrupts from the SSP output to TSP

  Inputs and outputs for INTC1 instances are context-dependent. However, for the
  first instance of INTC1, the (inclusive) output ranges are:

    - 00..05: INTM0-INTM5
    - 10..15: INTM10-INTM15
    - 20..25: INTM20-INTM25
    - 30..35: INTM30-INTM35
    - 40..45: INTM40-INTM45
    - 50..50: BootMCU

maintainers:
  - Ryan Chen <ryan_chen@aspeedtech.com>
  - Andrew Jeffery <andrew@codeconstruct.com.au>

properties:
  compatible:
    enum:
      - aspeed,ast2700-intc0
      - aspeed,ast2700-intc1

  reg:
    maxItems: 1

  interrupt-controller: true

  '#interrupt-cells':
    const: 1
    description: Single cell encoding the INTC local interrupt number (hwirq).

  aspeed,interrupt-ranges:
    description: |
      Describes how ranges of controller output pins are routed to a parent
      interrupt controller.

      Each range entry is encoded as:

        <out count phandle parent-specifier...>

      where:
        - out:     First controller interrupt output index in the range.
        - count:   Number of consecutive controller interrupt outputs and parent
                   interrupt inputs in this range.
        - phandle: Phandle to the parent interrupt controller node.
        - parent-specifier: Interrupt specifier, as defined by the parent
                            interrupt controller binding.
    $ref: /schemas/types.yaml#/definitions/uint32-array
    minItems: 3
    items:
      description: Range descriptors with a parent interrupt specifier.

required:
  - compatible
  - reg
  - interrupt-controller
  - '#interrupt-cells'
  - aspeed,interrupt-ranges

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/arm-gic.h>

    interrupt-controller@12100000 {
        compatible = "aspeed,ast2700-intc0";
        reg = <0x12100000 0x3b00>;
        interrupt-parent = <&gic>;
        interrupt-controller;
        #interrupt-cells = <1>;

        aspeed,interrupt-ranges =
          <0 128 &gic GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>,
          <144 8 &gic GIC_SPI 144 IRQ_TYPE_LEVEL_HIGH>,
          <152 8 &gic GIC_SPI 152 IRQ_TYPE_LEVEL_HIGH>,
          <192 10 &gic GIC_SPI 192 IRQ_TYPE_LEVEL_HIGH>,
          <208 10 &gic GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>,
          <224 10 &gic GIC_SPI 224 IRQ_TYPE_LEVEL_HIGH>,
          <256 128 &ssp_nvic 0 0>,
          <384 10 &ssp_nvic 160 0>,
          <400 8 &ssp_nvic 144 0>,
          <408 8 &ssp_nvic 152 0>,
          <426 128 &tsp_nvic 0 0>,
          <554 10 &tsp_nvic 160 0>,
          <570 8 &tsp_nvic 144 0>,
          <578 8 &tsp_nvic 152 0>;
    };