# Phase 14 - Interrupt Controller

## Context

After the timer, the system needs a way to manage external interrupt sources such as UART
RX. A PLIC-like controller arbitrates and presents external interrupts to the CPU.

## Goals

- Build a minimal interrupt controller.
- Connect UART RX as an interrupt source.
- Learn interrupt priority, enable, pending, claim, and complete concepts.

## New Concepts

- PLIC: Platform-Level Interrupt Controller used by many RISC-V systems.
- Interrupt priority: ordering among pending interrupt sources.
- Claim: software reads which interrupt it should service.
- Complete: software tells the controller an interrupt has been handled.
- Edge/level interrupt: whether an event is a pulse or held condition.

## How To Think About It

An interrupt controller is hardware/software coordination. The device requests service,
the controller prioritizes it, the CPU traps, and software acknowledges the right places
in the right order.

## Learning Tasks

- Draw interrupt flow from UART RX byte to trap handler.
- Decide whether UART interrupt is level-sensitive or edge-sensitive.
- Understand claim/complete even if your first controller is simplified.

## Pitfalls

- Losing an interrupt event because it is only a one-cycle pulse.
- Clearing the device before software can observe why it interrupted.
- Taking an interrupt repeatedly because pending state is never cleared.

## Tooling And Testing

- Start with one interrupt source before adding priority.
- Test masked, unmasked, pending, claim, and complete behavior.
- Use ILA on interrupt request, pending, CPU external interrupt, and trap entry.

## References

- RISC-V PLIC specification: https://github.com/riscv/riscv-plic-spec
- RISC-V privileged architecture spec: https://riscv.org/technical/specifications/
- Linux interrupt concepts: https://docs.kernel.org/core-api/genericirq.html