====== SoC interrupt controller ======

On the [[rtl838x|RTL8380]], [[rtl83xx|RTL8390]], and [[rtl93xx|RTL9300]] families, interrupts from SoC peripherals are handled by the SoC interrupt controller.
This controller can connect interrupt outputs from up to 32 peripherals to the six MIPS CPU hardware interrupts. The way these interrupts are routed is runtime configurable, allowing for some flexibility between different SoC families and board designs.

The [[rtl93xx|RTL9310]] family of SoCs is based on MIPS InterAptiv, and uses a GIC to manage SoC interrupts.

===== Hardware overview =====

Each interrupt controller block has 32 SoC interrupt input lines, and each of these inputs can be routed to //one// of the connected parent interrupts by configuring the routing registers. On all SoCs, these parent interrupts are the MIPS CPU hardware interrupts (IRQ2-IRQ7).

  SoC IRQ  +------+  Parent IRQs
  source   |     -|-----> CPU IRQ2
           |  /---|-----> CPU IRQ3
    >------|-/   -|-----> CPU IRQ4
           |     -|-----> CPU IRQ5
           |     -|-----> CPU IRQ6
           |     -|-----> CPU IRQ7 (timer)
           +------+

An independent interrupt controller block is present in the SoCs for each VPE (one on RTL8380, two on RTL8390 and RTL9300). In the diagram below, Peripheral A has two interrupt sources that are used to perform IRQ balancing between both VPEs. Peripheral B on the other hand, has only one interrupt output that is connected to both IRQ controllers, leaving CPU balancing to the interrupt controller. For consistency, a single peripheral is always connected to the same interrupt input on each interrupt controller.

  SOC IRQ LINES                        MIPS
                         +-----------+ HW IRQ   +--------+
  Peripheral A[CPU0]---->| SOC IRQ   | LINES    | IRQ    |
  Peripheral B ------o-->| VPE0 CTRL |=========>| VPE0   |
          .          |   +-----------+          +--------+
          .          |
          .          |
                     |   +-----------+          +--------+
                     \-->| SOC IRQ   |          | IRQ    |  (Not available ont RTL8380)
  Peripheral A[CPU1]---->| VPE1 CTRL |=========>| VPE1   |
                         +-----------+          +--------+

In theory, this architecture allows for peripheral interrupts to be routed to any one of that VPE's HW IRQs. For example, the GPIO interrupt line could be routed to IRQ4 on VPE0, and IRQ2 on VPE1. In order to perform sensible IRQ balancing, the same routing should be used in both IRQ controllers blocks.

While each MIPS processor has 5 interrupts internally, they should really be thought of as 'priority queues'. E.g. if UART0 is connected to VPE0 IRQ2, and UART1 is connected to VPE0 IRQ5, UART0 would have a higher priority due to it being routed to the higher priority IRQ on the VPE.

===== Register description =====

Each interrupt controller block has six registers, used to read interrupt status, and to route and enable interrupts.

^ Offset ^ Register ^ Mode ^ Description ^
| 0x00 | GIMR | R/W | Interrupt enable (mask) register with one bit per input line. Set the bit to enable interrupts, and clear to disable. |
| 0x04 | GISR | R | Interrupt status register with one bit per input line. Set when an input line is signalling an interrupt. |
| 0x08 | IRR0 | R/W | Interrupt routing register for input lines 31-24.\\ Four bits per input line to select the desired output line.\\ A value of '0' or '8-15' disconnects this input from the output line, independent of the line's setting in GIMR.\\ Values 1-6 select one of the CPU IRQs (resp. 2-7, where 7 is the NMI interrupt). |
| 0x0C | IRR1 | R/W | Interrupt routing register for input lines 23-16. |
| 0x10 | IRR2 | R/W | Interrupt routing register for input lines 15-8. |
| 0x14 | IRR3 | R/W | Interrupt routing register for input lines 7-0. |

Base addresses:
  * RTL8380: 0x18003000
  * RTL8390: 0x18003000 (VPE0), 0x18003018 (VPE1)
  * RTL9300: 0x18003000 (VPE0), 0x18003018 (VPE1)
===== Peripheral interrupt connections =====

^  Interrupt source  ^  RTL8380/RTL8390  ^^^  RTL9300  ^^^  RTL9310  ^^^
|:::|  SoC IRQ  |  VPE0 IRQ (SDK)  |  VPE1 IRQ (SDK)  |  SoC IRQ  |  VPE0 IRQ (SDK)  |  VPE1 IRQ (SDK)  |  SoC IRQ  |  VPE0 IRQ (SDK)  |  VPE1 IRQ (SDK)  |
| UART0  |  31  |  3  | |  30  |  3  | |  22  |  3  | |
| UART1  |  30  |  2  | |  31  |  2  | |  23  |  2  | |
| TIMER0 |  29  |  6  | |  7  |  6  | |  
| TIMER1 |  28  |  2  | |  8  |  2  | |
| TIMER2 |  17  |  2  |  2  |   9  |
| TIMER3 |  16  |  2  |  2  |  10  |
| TIMER4 |  15  |  2  |  2  |  11  |
| TIMER5 |  n/a  |  2  | |  n/a  | | |  
| TIMER6 |  n/a  |  2  | |  n/a  | | |  
| DELAY0 |  n/a  | | | | | | | | |
| DELAY1 |  n/a  | | | | | | | | |
| DELAY2 |  14  | | | | | | | | |
| DELAY3 |  13  | | | | | | | | |
| DELAY4 |  12  | | | | | | | | |
| DELAY5 |  n/a  | | | | | | | | |
| DELAY6 |  n/a  | | | | | | | | |
| OCPTO  |  27  |  2  | |  17  | 2  | |  n/a  | | |
| HLXTO/LXMTO  |  26  |  2  | |  n/a  | | |  n/a  | | |
| SLXTO/LXSTO  |  25  |  2  | |  n/a  | | |  n/a  | | |
| NIC    |  24  |  5  | |  24  |  5  | |  16  |  5  | |
| SWCORE |  20  |  4  | |  23  |  4  | |  15  |  4  | |
| GPIO_ABCD |  23  |  5  | |  13  |  5  | |  20  |  5  | |
| GPIO_EFGH |  n/a  |  5  | |  n/a  | | |  n/a  | | |
| RTC    |  21  |  5  | |  n/a  | | |  n/a  | | |
| WDT_IP1 |  19  |  5  | |  5  |  5  | |  8  |  5  | |
| WDT_IP2 |  18  |  5  | |  n/a  | | |  9  |   5  | |
| USB_H2  |  22  |  2  | |  28  |  2  | |  36  |  2  | |
| SPI_NAND | | | | | | | | | |
| ECC | |  20  | | | | | | | | |
| SECURITY | | | | | | | | | |