Add phase-by-phase tutorial notes

Add a Tutorial tree that mirrors the roadmap from Phase 0 through Linux bring-up.
Each phase and subphase gets a short learning note with consistent sections for
context, goals, new concepts, mental model, learning tasks, pitfalls, tooling,
testing, and references.

The tutorial material is intentionally explanatory rather than implementation
code. It gives a systems-oriented learner enough FPGA, SystemVerilog, RISC-V,
firmware, and Linux bring-up context to approach each roadmap phase without
turning the notes into copy-paste RTL.
This commit is contained in:
2026-04-28 12:11:23 +02:00
parent 8edfc86027
commit b008b37d49
43 changed files with 2110 additions and 0 deletions
@@ -0,0 +1,51 @@
# Phase 11 - 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