Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml

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

title: Texas Instruments K3 Interrupt Aggregator

maintainers:
  - Lokesh Vutla <lokeshvutla@ti.com>

allOf:
  - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml#

description: |
  The Interrupt Aggregator (INTA) provides a centralized machine
  which handles the termination of system events to that they can
  be coherently processed by the host(s) in the system. A maximum
  of 64 events can be mapped to a single interrupt.

                                Interrupt Aggregator
                       +-----------------------------------------+
                       |      Intmap            VINT             |
                       | +--------------+  +------------+        |
              m ------>| | vint  | bit  |  | 0 |.....|63| vint0  |
                 .     | +--------------+  +------------+        |      +------+
                 .     |         .               .               |      | HOST |
  Globalevents  ------>|         .               .               |----->| IRQ  |
                 .     |         .               .               |      | CTRL |
                 .     |         .               .               |      +------+
              n ------>| +--------------+  +------------+        |
                       | | vint  | bit  |  | 0 |.....|63| vintx  |
                       | +--------------+  +------------+        |
                       |                                         |
                       |      Unmap                              |
                       | +--------------+                        |
  Unmapped events ---->| |   umapidx    |-------------------------> Globalevents
                       | +--------------+                        |
                       |                                         |
                       +-----------------------------------------+

  Configuration of these Intmap registers that maps global events to vint is
  done by a system controller (like the Device Memory and Security Controller
  on AM654 SoC). Driver should request the system controller to get the range
  of global events and vints assigned to the requesting host. Management
  of these requested resources should be handled by driver and requests
  system controller to map specific global event to vint, bit pair.

  Communication between the host processor running an OS and the system
  controller happens through a protocol called TI System Control Interface
  (TISCI protocol).

properties:
  compatible:
    const: ti,sci-inta

  reg:
    maxItems: 1

  interrupt-controller: true

  msi-controller: true

  ti,interrupt-ranges:
    $ref: /schemas/types.yaml#/definitions/uint32-matrix
    description: |
      Interrupt ranges that converts the INTA output hw irq numbers
      to parents's input interrupt numbers.
    items:
      items:
        - description: |
            "output_irq" specifies the base for inta output irq
        - description: |
            "parent's input irq" specifies the base for parent irq
        - description: |
            "limit" specifies the limit for translation

  ti,unmapped-event-sources:
    $ref: /schemas/types.yaml#definitions/phandle-array
    description:
      Array of phandles to DMA controllers where the unmapped events originate.

required:
  - compatible
  - reg
  - interrupt-controller
  - msi-controller
  - ti,sci
  - ti,sci-dev-id
  - ti,interrupt-ranges

unevaluatedProperties: false

examples:
  - |
    bus {
        #address-cells = <2>;
        #size-cells = <2>;

        main_udmass_inta: msi-controller@33d00000 {
            compatible = "ti,sci-inta";
            reg = <0x0 0x33d00000 0x0 0x100000>;
            interrupt-controller;
            msi-controller;
            interrupt-parent = <&main_navss_intr>;
            ti,sci = <&dmsc>;
            ti,sci-dev-id = <179>;
            ti,interrupt-ranges = <0 0 256>;
        };
    };