doc: add overview

docs/index.md

@@ -1,3 +1,53 @@
+# OpenAIA.scala
+
+<!-- vim-markdown-toc GFM -->
+
+* [Overview](#overview)
+  * [Interrupt Paths](#interrupt-paths)
+  * [Configuration Paths](#configuration-paths)
+
+<!-- vim-markdown-toc -->
+
+The implementation of OpenAIA.scala adheres to the [RISC-V Advanced Interrupt Architecture (AIA) Specification](https://github.com/riscv/riscv-aia).
+Any discrepancies between the implementation and specification should be treated as implementation bugs.
+
+## Overview
+
+AIA is designed to efficiently route external interrupts to the appropriate harts and privilege levels.
+This routing is accomplished by two interrupt controllers:
+
+* Incoming Message-Signaled Interrupt Controller (**IMSIC**)
+* Advanced Platform-Level Interrupt Controller (**APLIC**)
+
+Why two types of controllers?
+There are two types of external devices:
+
+1. **Wired devices**:
+  Interrupts are transmitted via dedicated electronic signals (edge or level),
+  which is simple to implement but faces scalability challenges,
+  as each interrupt requires an physical wire connected to the hart.
+2. **Message-signaled-interrupt (MSI) devices**:
+  Interrupts are encoded as messages and transmitted over bus/network,
+  which offers better scalability compared to wired interrupts,
+  as no dedicated physical wires needed for each interrupt.
+
+In RISC-V AIA:
+
+* **APLIC** handles wired external interrupts
+* **IMSIC** handles message-signaled external interrupts
+
+<!-- The external interrupts are mainly generated by external devices, -->
+<!-- however, for some advanced usage, the internal devices and hart can also generate, -->
+<!-- e.g. supervisor level injects external interrupts into virtualized supervisor level. -->
+<!-- In this document, we focus on the situation where external devices generate interrupts routed by interrupt controllers to harts. -->
+
+The interaction between devices, interrupt controllers, and harts involves two main types of data paths:
+**interrupt paths** and **configuration paths**, shown as the following two figures.
+
+### Interrupt Paths
+
 ![](./images/arch_interrupt_py.svg)
 
+### Configuration Paths
+
 ![](./images/arch_configure_py.svg)