Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml

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

title: RISC-V Advanced Platform Level Interrupt Controller (APLIC)

maintainers:
  - Anup Patel <anup@brainfault.org>

description:
  The RISC-V advanced interrupt architecture (AIA) defines an advanced
  platform level interrupt controller (APLIC) for handling wired interrupts
  in a RISC-V platform. The RISC-V AIA specification can be found at
  https://github.com/riscv/riscv-aia.

  The RISC-V APLIC is implemented as hierarchical APLIC domains where all
  interrupt sources connect to the root APLIC domain and a parent APLIC
  domain can delegate interrupt sources to it's child APLIC domains. There
  is one device tree node for each APLIC domain.

allOf:
  - $ref: /schemas/interrupt-controller.yaml#

properties:
  compatible:
    items:
      - enum:
          - qemu,aplic
          - spacemit,k3-aplic
      - const: riscv,aplic

  reg:
    maxItems: 1

  interrupt-controller: true

  "#interrupt-cells":
    const: 2

  interrupts-extended:
    minItems: 1
    maxItems: 16384
    description:
      Given APLIC domain directly injects external interrupts to a set of
      RISC-V HARTS (or CPUs). Each node pointed to should be a riscv,cpu-intc
      node, which has a CPU node (i.e. RISC-V HART) as parent.

  msi-parent:
    description:
      Given APLIC domain forwards wired interrupts as MSIs to a AIA incoming
      message signaled interrupt controller (IMSIC). If both "msi-parent" and
      "interrupts-extended" properties are present then it means the APLIC
      domain supports both MSI mode and Direct mode in HW. In this case, the
      APLIC driver has to choose between MSI mode or Direct mode.

  riscv,num-sources:
    $ref: /schemas/types.yaml#/definitions/uint32
    minimum: 1
    maximum: 1023
    description:
      Specifies the number of wired interrupt sources supported by this
      APLIC domain.

  riscv,children:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    minItems: 1
    maxItems: 1024
    items:
      maxItems: 1
    description:
      A list of child APLIC domains for the given APLIC domain. Each child
      APLIC domain is assigned a child index in increasing order, with the
      first child APLIC domain assigned child index 0. The APLIC domain child
      index is used by firmware to delegate interrupts from the given APLIC
      domain to a particular child APLIC domain.

  riscv,delegation:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    minItems: 1
    maxItems: 1024
    items:
      items:
        - description: child APLIC domain phandle
        - description: first interrupt number of the parent APLIC domain (inclusive)
        - description: last interrupt number of the parent APLIC domain (inclusive)
    description:
      A interrupt delegation list where each entry is a triple consisting
      of child APLIC domain phandle, first interrupt number of the parent
      APLIC domain, and last interrupt number of the parent APLIC domain.
      Firmware must configure interrupt delegation registers based on
      interrupt delegation list.

  riscv,hart-indexes:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    minItems: 1
    maxItems: 16384
    description:
      A list of hart indexes that APLIC should use to address each hart
      that is mentioned in the "interrupts-extended"

dependencies:
  riscv,delegation: [ "riscv,children" ]

required:
  - compatible
  - reg
  - interrupt-controller
  - "#interrupt-cells"
  - riscv,num-sources

anyOf:
  - required:
      - interrupts-extended
  - required:
      - msi-parent

unevaluatedProperties: false

examples:
  - |
    // Example 1 (APLIC domains directly injecting interrupt to HARTs):

    interrupt-controller@c000000 {
      compatible = "qemu,aplic", "riscv,aplic";
      interrupts-extended = <&cpu1_intc 11>,
                            <&cpu2_intc 11>,
                            <&cpu3_intc 11>,
                            <&cpu4_intc 11>;
      reg = <0xc000000 0x4080>;
      interrupt-controller;
      #interrupt-cells = <2>;
      riscv,num-sources = <63>;
      riscv,children = <&aplic1>, <&aplic2>;
      riscv,delegation = <&aplic1 1 63>;
    };

    aplic1: interrupt-controller@d000000 {
      compatible = "qemu,aplic", "riscv,aplic";
      interrupts-extended = <&cpu1_intc 9>,
                            <&cpu2_intc 9>;
      reg = <0xd000000 0x4080>;
      interrupt-controller;
      #interrupt-cells = <2>;
      riscv,num-sources = <63>;
    };

    aplic2: interrupt-controller@e000000 {
      compatible = "qemu,aplic", "riscv,aplic";
      interrupts-extended = <&cpu3_intc 9>,
                            <&cpu4_intc 9>;
      reg = <0xe000000 0x4080>;
      interrupt-controller;
      #interrupt-cells = <2>;
      riscv,num-sources = <63>;
    };

  - |
    // Example 2 (APLIC domains forwarding interrupts as MSIs):

    interrupt-controller@c000000 {
      compatible = "qemu,aplic", "riscv,aplic";
      msi-parent = <&imsic_mlevel>;
      reg = <0xc000000 0x4000>;
      interrupt-controller;
      #interrupt-cells = <2>;
      riscv,num-sources = <63>;
      riscv,children = <&aplic3>;
      riscv,delegation = <&aplic3 1 63>;
    };

    aplic3: interrupt-controller@d000000 {
      compatible = "qemu,aplic", "riscv,aplic";
      msi-parent = <&imsic_slevel>;
      reg = <0xd000000 0x4000>;
      interrupt-controller;
      #interrupt-cells = <2>;
      riscv,num-sources = <63>;
    };
...