From c04c964e5781ee8a34ec89b3eb72839f6852311f Mon Sep 17 00:00:00 2001
From: xieby1 <xieby1@outlook.com>
Date: Wed, 30 Oct 2024 18:02:03 +0800
Subject: [PATCH] =?UTF-8?q?doc:=20=E6=B7=BB=E5=8A=A0=E4=B8=AD=E6=96=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/aplic.md |  51 +++++++++++++++++----
 docs/imsic.md | 120 ++++++++++++++++++++++++++++++++++++++------------
 docs/index.md |  95 +++++++++++++++++++++++++++++++++------
 3 files changed, 216 insertions(+), 50 deletions(-)

diff --git a/docs/aplic.md b/docs/aplic.md
index 818043f..6ed57c2 100644
--- a/docs/aplic.md
+++ b/docs/aplic.md
@@ -2,15 +2,24 @@
 
 <!-- vim-markdown-toc GFM -->
 
-* [Domain](#domain)
-  * [Internal Registers](#internal-registers)
+* [域（Domain）](#域domain)
+  * [内部寄存器（Internal Registers）](#内部寄存器internal-registers)
 
 <!-- vim-markdown-toc -->
 
+在基于消息的中断模式下，APLIC将传统的线中断转换为MSI。
+为了提高效率，除非设备在物理上是分开的（例如在不同的芯片组上），单个APLIC实例即可服务所有处理器核心。
+
 In message-based interrupt mode, the APLIC converts traditional wired interrupts into MSIs.
 For efficiency, a single APLIC instance should serve all harts, unless devices are physically separated (e.g. on different chiplets).
 
-## Domain
+## 域（Domain）
+
+APLIC实现了分层的域结构来管理不同的特权态:
+
+* 根域（机器态）直接接收所线中断,
+* 子域从其父域接收委托的中断,
+* 监管态域可以处理监管态和虚拟化监管态中断。
 
 The APLIC implements a hierarchical domain structure to manage different privilege levels:
 
@@ -18,6 +27,11 @@ The APLIC implements a hierarchical domain structure to manage different privile
 * Child domains receive delegated interrupts from their parent domains,
 * A supervisor-level domain can handle both supervisor-level and virtualized supervisor-level interrupts.
 
+对于大型对称多处理系统，通常两个域的配置就足够了：
+
+* 一个机器态域,
+* 一个监管态域。
+
 For large symmetric multiprocessing systems, a two-domain configuration typically suffices:
 
 * One machine-level domain,
@@ -25,17 +39,34 @@ For large symmetric multiprocessing systems, a two-domain configuration typicall
 
 ![](./images/aplic.svg)
 
-### Internal Registers
+### 内部寄存器（Internal Registers）
+
+APLIC在内部寄存器中维护中断状态，包括两个关键寄存器：
+
+* `ip[intSrcNum位]`: 中断待处理状态寄存器,
+* `ie[intSrcNum位]`: 中断使能控制寄存器。
 
 APLIC maintains interrupt status in internal registers, including two critical registers:
 
 * `ip[intSrcNum bits]`: Interrupt pending status registers,
 * `ie[intSrcNum bits]`: Interrupt enable control registers.
 
+这些寄存器通过内存映射接口进行控制。
+有关详细的寄存器规范，请参阅AIA规范[^aplic_mem_regs]。
+
 These registers are controlled through memory-mapped interfaces.
 For detailed register specifications, refer to the AIA specification[^aplic_mem_regs].
 
-**Race Conditions**
+**竞争条件**（**Race Conditions**）
+
+`ip`寄存器可以被多个来源修改，从而产生潜在的竞争条件。
+AIA规范没有规定APLIC在这种竞争条件下的行为。
+OpenAIA实现了一个基于优先级的解决机制。
+优先级(从高到低):
+
+* APLIC内部操作：发送MSI后清除`ip`，
+* 线设备操作：通过`intSrc`设置`ip`，
+* 处理器核心操作：通过内存映射寄存器设置/清除`ip`。
 
 The `ip` registers can be modified by multiple sources, creating potential race conditions.
 The AIA specification does not specify the APLIC behaviors under this race condition.
@@ -46,10 +77,12 @@ Priority levels (highest to lowest):
 *  Wired device operations: Setting `ip` via `intSrc`,
 *  Hart operations: Setting/Clearing `ip` via memory mapped registers.
 
-Higher priority operations override the lower priority ones.
-However, best practices recommend:
+高优先级操作会覆盖低优先级操作。
+我们推荐通过编程的方式避免竞争条件：
+在通过内存映射寄存器修改相应的`ip`之前，断开线设备。
 
-* Avoid race conditions through programming,
-* Detaching the wired device before modifying corresponding `ip` through memory-mapped registers.
+Higher priority operations override the lower priority ones.
+We recommend to avoid race conditions through programming:
+detaching the wired device before modifying corresponding `ip` through memory-mapped registers.
 
 [^aplic_mem_regs]: The RISC-V Advanced Interrupt Architecture: 4.5. Memory-mapped control region for an interrupt domain
diff --git a/docs/imsic.md b/docs/imsic.md
index 62968bc..82c7439 100644
--- a/docs/imsic.md
+++ b/docs/imsic.md
@@ -2,41 +2,56 @@
 
 <!-- vim-markdown-toc GFM -->
 
-* [Individual IMSIC Functionality](#individual-imsic-functionality)
-  * [IMSIC IO](#imsic-io)
-  * [Interrupt File IO](#interrupt-file-io)
-  * [Interrupt File Memory-mapped Registers](#interrupt-file-memory-mapped-registers)
-  * [Interrupt File Internal Registers](#interrupt-file-internal-registers)
-* [Multiple IMSICs Arrangement](#multiple-imsics-arrangement)
-  * [IMSIC Address Fields](#imsic-address-fields)
-  * [IMSIC Memory Regions](#imsic-memory-regions)
+* [单个IMSIC的功能（Individual IMSIC Functionality）](#单个imsic的功能individual-imsic-functionality)
+  * [IMSIC的输入与输出（IMSIC IO）](#imsic的输入与输出imsic-io)
+  * [中断文件的输入与输出（Interrupt File IO）](#中断文件的输入与输出interrupt-file-io)
+  * [中断文件的内存映射寄存器（Interrupt File Memory-mapped Registers）](#中断文件的内存映射寄存器interrupt-file-memory-mapped-registers)
+  * [中断文件内部的寄存器（Interrupt File Internal Registers）](#中断文件内部的寄存器interrupt-file-internal-registers)
+* [多个IMSIC的组织形式（Multiple IMSICs Arrangement）](#多个imsic的组织形式multiple-imsics-arrangement)
+  * [IMSIC地址字段（IMSIC Address Fields）](#imsic地址字段imsic-address-fields)
+  * [IMSIC内存区域（IMSIC Memory Regions）](#imsic内存区域imsic-memory-regions)
 
 <!-- vim-markdown-toc -->
 
+在典型的RISC-V系统中，每个处理器核心都配有专用的IMSIC。
+IMSIC执行三个主要功能:
+
+* 通过内存映射寄存器接收MSI，
+* 为其关联的处理器核心生成中断，
+* 管理处理器核心所需的AIA控制寄存器。
+
 In a typical RISC-V system, each hart is paired with its dedicated IMSIC.
 The IMSIC performs three main functions:
 
 * Receives MSIs through memory-mapped registers,
 * Generates interrupts for its associated hart,
-* Manages CSRs under hart control.
+* Manages AIA CSRs under hart control.
+
+在对称多处理系统中，多个“核-IMSIC”对可以划分成组，
+每组包含相同数量的核-IMSIC对。
 
 In symmetric multiprocessing systems, multiple harts-IMSIC pairs can be organized into groups,
 with each group containing an equal number of pairs.
 
-This document covers:
+## 单个IMSIC的功能（Individual IMSIC Functionality）
 
-* The functionality of an individual IMSIC,
-* The logical arrangement of multiple IMSICs within a system.
+### IMSIC的输入与输出（IMSIC IO）
 
-## Individual IMSIC Functionality
+IMSIC与其处理器核心紧密耦合，
+直接使用线路连接而不是总线/网络进行信息传输。
+其关键信号包括:
 
-### IMSIC IO
+* `pendings`: 每个中断文件的待处理中断状态。
+* `{m,s,vs}topei`: 每个特权态中，优先级最高的外部中断号。
+* `{m.s,vs}iselect`: 每个特权态中，间接访问控制寄存器的地址。
+* `{m,s,vs}ireg`: 每个特权态中，间接访问控制寄存器所读写的数据。
+* `vgein`: 虚拟化监管态的选择信号。
 
 The IMSIC is tightly coupled with its hart,
 directly using wire connection rather than bus/network for information transfer.
 Key signals include:
 
-* `pendings`: Pending interrupt status for each interrupt file (introduced as below).
+* `pendings`: Pending interrupt status for each interrupt file.
 * `{m,s,vs}topei`: Top external interrupt ID for each privilege level.
 * `{m.s,vs}iselect`: CSR indirect access address for each privilege level.
 * `{m,s,vs}ireg`: Read and write data for indirect CSR access for each privilege level.
@@ -44,7 +59,17 @@ Key signals include:
 
 ![](./images/imsic_py.svg)
 
-### Interrupt File IO
+### 中断文件的输入与输出（Interrupt File IO）
+
+一个IMSIC负责管理其处理器核心中的所有特权态，
+包括：一个机器态、一个监管态和多个虚拟化监管态。
+由于每个态的行为在一般情况下是相同的，AIA规范将这些功能模块化成独立且可重用的组件，称为中断文件。
+每个中断文件与IMSIC交换与特权态无关的信息:
+
+* `pending`: 该中断文件的中断状态。
+* `topei`: 该中断文件中，优先级最高的外部中断号。
+* `iselect`: 该中断文件中，间接访问控制寄存器的地址。
+* `ireg`: 该中断文件中，间接访问控制寄存器所读写的数据。
 
 One IMSIC manages all privilege levels in its hart,
 including: one machine level, one supervisor level, and multiple virtualized supervisor levels.
@@ -56,28 +81,38 @@ Each interrupt file exchanges privilege-agnostic information with IMSIC:
 * `iselect`: CSR indirect access address for this interrupt file.
 * `ireg`: Read and write data for indirect CSR access for this interrupt file.
 
-### Interrupt File Memory-mapped Registers
+### 中断文件的内存映射寄存器（Interrupt File Memory-mapped Registers）
+
+每个中断文件包含一个4KB内存页，用于接收来自总线/网络的消息。
+内存页内仅包含一个4B内存映射寄存器:
 
-In addition, each interrupt file includes a 4KB memory page for receiving messages from bus/network.
+* `seteipnum`: 位于偏移量0x0处，接收传入的中断号。
+
+Each interrupt file includes a 4KB memory page for receiving messages from bus/network.
 The memory page including only one 4B memory-mapped register:
 
 * `seteipnum`: Located at offset of 0x0, receiving incoming interrupt IDs.
 
-Each interrupt file maintains internal registers that interact with the interfaces above.
-The key internal registers consist of:
 
-### Interrupt File Internal Registers
+### 中断文件内部的寄存器（Interrupt File Internal Registers）
 
-* `eip[intSrcNum bits]`: Interrupt pending register, indicating which interrupts are currently pending
-* `eie[intSrcNum bits]`: Interrupt enable register, controlling which interrupts are enabled
+所有上述接口都与中断文件的内部寄存器交互。
+关键的内部寄存器包括:
 
-All above interfaces operating with interrupt file's internal registers.
-The key internal registers including:
+* `eip[intSrcNum位]`: 表示该中断是否待处理。
+* `eie[intSrcNum位]`: 表示该中断是否使能。
+
+Each interrupt file maintains internal registers that interact with the interfaces above.
+The key internal registers consist of:
 
 * `eip[intSrcNum bits]`: Whether this interrupt is pending.
 * `eie[intSrcNum bits]`: Whether this interrupt is enabled.
 
-## Multiple IMSICs Arrangement
+## 多个IMSIC的组织形式（Multiple IMSICs Arrangement）
+
+在大型系统中，核-IMSIC对可以分成多组。
+下图显示了一个对称的4核-IMSIC系统。
+这4对被分为2**组**，每组包含2个**成员**(hart-IMSIC对)。
 
 In a large system, hart-IMSIC pairs can be divided into groups.
 The below figure shows a symmetric 4-hart-IMSIC system.
@@ -85,7 +120,15 @@ These 4 pairs are divided into 2 **groups**, and each group contains 2 **members
 
 ![](./images/imsics_arrangement_py.svg)
 
-### IMSIC Address Fields
+### IMSIC地址字段（IMSIC Address Fields）
+
+为了支持物理内存保护(physical memory protection, PMP)，相同特权态的中断文件位于同一内存区域:
+
+* 机器态内存区域:
+  * 每个处理器核心对应一个机器态中断文件
+* 监管态内存区域:
+  * 每个处理器核心对应一个监管态中断文件,
+  * 每个处理器核心对应多个虚拟化监管态中断文件。
 
 To support physical memory protection (PMP), interrupt files of the same privilege level are located in a same memory region:
 
@@ -95,6 +138,15 @@ To support physical memory protection (PMP), interrupt files of the same privile
   * One supervisor-level interrupt file per hart,
   * Multiple virtualized supervisor-level interrupt files per hart.
 
+因此，每个处理器核心在机器态内存区域只占一页，但在监管态内存区域占多页，
+由**客户号**（监管态为0，虚拟化监管态为1、2、3、...)索引。
+需要四个字段来确定一个IMSIC的内存页的地址：
+
+* 特权态：机器态或监管态。
+* 组号：该IMSIC所属的组。
+* 成员号：该IMSIC所属的成员。
+* 客户号：监管态或虚拟化监管态之一。
+
 Thus, each hart has only one page in machine-level memory region and multiple pages in supervisor-level memory region,
 indexed by a **guest ID** (0 for supervisor-level, 1,2,3,... for virtualized supervisor level).
 When determining the memory page address for a given IMSIC, four fields are needed:
@@ -106,6 +158,8 @@ When determining the memory page address for a given IMSIC, four fields are need
 
 ![](./images/imsic_addr.svg)
 
+机器态中断文件的地址表达式为：
+
 The formal expression for a machine-level interrupt file address:
 
 $$
@@ -118,6 +172,8 @@ mIntFileAddr =
 \end{align}
 $$
 
+虚拟化监管态中断文件的地址表达式为：
+
 The formal expression for a virtualized supervisor-level interrupt file address:
 
 $$
@@ -130,15 +186,23 @@ vsIntFileAddr =
 \end{align}
 $$
 
+按照AIA规范的要求，`vsGroupStrideWidth`与`mGroupStrideWidth`相同。
+更多详细信息，请参阅AIA规范[^imsic_memory_region]。
+
 As required by the AIA specification, the `vsGroupStrideWidth` is the same as the `mGroupStrideWidth`.
 For more details, please refer to the AIA specification[^imsic_memory_region].
 
-### IMSIC Memory Regions
+### IMSIC内存区域（IMSIC Memory Regions）
+
+机器和监管态的内存区域如下所示。
 
 The memory regions for machine and supervisor levels are shown as below.
 
 ![](./images/imsic_addr_space.svg)
 
+这里展示一个具体的例子。
+假设机器态和监管态的内存区域基地址分别为`0x6100_0000`和`0x8290_0000`，那么每个中断文件的地址为：
+
 Here is a concrete example.
 Assuming the base addresses for machine-level and supervisor-level memory regions are `0x6100_0000` and `0x8290_0000`, respectively,
 the addresses for each interrupt file are:
diff --git a/docs/index.md b/docs/index.md
index e5512fc..cb1fc5a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,18 +1,24 @@
-# OpenAIA.scala Overview
+# OpenAIA.scala
 
 <!-- vim-markdown-toc GFM -->
 
-* [Introduction](#introduction)
-* [Interrupt Paths](#interrupt-paths)
-* [Configuration Paths](#configuration-paths)
-* [References](#references)
+* [简介（Introduction）](#简介introduction)
+* [中断通路（Interrupt Paths）](#中断通路interrupt-paths)
+* [配置通路（Configuration Paths）](#配置通路configuration-paths)
+* [引用（References）](#引用references)
 
 <!-- vim-markdown-toc -->
 
+OpenAIA.scala的实现遵循RISC-V高级中断架构（Advanced Interrupt Architecture, AIA）规范。
+实现与规范之间的任何差异都应视为实现bug。
+
 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.
 
-## Introduction
+## 简介（Introduction）
+
+AIA旨在高效地将外部中断路由到对应的处理器核心（hart）和特权态。
+这种路由通过两个中断控制器来完成：
 
 AIA is designed to efficiently route external interrupts to the appropriate harts and privilege levels.
 This routing is accomplished by two interrupt controllers:
@@ -20,6 +26,17 @@ This routing is accomplished by two interrupt controllers:
 * Incoming Message-Signaled Interrupt Controller (**IMSIC**)
 * Advanced Platform-Level Interrupt Controller (**APLIC**)
 
+为什么需要两种控制器？
+因为存在两类外部设备：
+
+1. **线设备**：
+  通过专用的电信号（边沿或电平）传输中断。
+  它的特点是实现简单，可扩展性差。
+  因为每个中断都意味着一根连接到处理器核心的物理线。
+2. **消息信号中断(Message-signaled-interrupt, MSI)设备**：
+    中断被编码为消息，并通过总线/网络传输。
+    因为每个中断不需要专用的物理连线，因此MSI与线中断相比，有更好的可扩展性。
+
 Why two types of controllers?
 There are two types of external devices:
 
@@ -32,19 +49,36 @@ There are two types of external devices:
   which offers better scalability compared to wired interrupts,
   as no dedicated physical wires needed for each interrupt.
 
+在 RISC-V AIA 中：
+
+* **APLIC**负责处理线外部中断。
+  **注意**：APLIC可以在两种模式下运行(domaincfg.DM)：
+  * **直接递送模式**：APLIC直接将线中断路由到处理器核心，无需IMSIC参与。
+  * MSI递送模式：APLIC将线中断转换为MSI并转发给IMSIC。
+  * 由于MSI更具扩展性，后续讨论默认APLIC采用MSI递送模式。
+* **IMSIC**负责处理MSI。
+
 In RISC-V AIA:
 
 * **APLIC** handles wired external interrupts.
   **Note**: APLIC can operate in two modes (`domaincfg.DM`):
   * **Direct delivery mode**: APLIC directly routes wired interrupts to harts without IMSIC involvement.
   * **MSI delivery mode**: APLIC converts wired interrupts into MSIs and forwards them to IMSIC.
-  * Since MSIs represent the more scalable approach, our subsequent discussion will focus on APLIC's MSI delivery mode.
-* **IMSIC** handles message-signaled external interrupts.
+  * Since MSIs represent the more scalable approach, our subsequent discussion assumes the APLIC working in MSI delivery mode.
+* **IMSIC** handles MSIs.
+
+设备、中断控制器和处理器核心之间的交互主要涉及两种数据通路：
+**中断通路**和**配置通路**，如下面两张图所示。
 
 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
+## 中断通路（Interrupt Paths）
+
+外部中断主要源自外部设备，
+尽管在高级使用场景中，内部设备和处理器核心也可以生成“外部”中断
+（例如当监管态向虚拟化监管态注入外部中断时）。
+接下来的讨论重点关注外部设备生成中断并通过控制器路由到处理器核心的典型情况。
 
 External interrupts primarily originate from external devices,
 though in advanced scenarios, internal devices and harts can also generate "external" interrupts
@@ -53,13 +87,39 @@ The following discussion focuses on the typical case where external devices gene
 
 ![](./images/arch_interrupt_py.svg)
 
+详细的中断通路如下（注：在语言清晰前提下，我们将省略“外部”）：
+
+* 中断来源于线设备或MSI设备：
+  * 线设备通路：
+      * 中断被转发到APLIC的**中断域**。
+      * 每个域负责管理某一特权态的一组处理器核心的中断。
+      * 对于大型对称多处理系统，通常两个域就足够了[^two_interrupt_domains]：
+        * 一个**机器态域**，
+        * 一个**监管态域**。
+      * 域遵循层级结构：
+        * 所线中断首先到达机器态域。
+        * 根据APLIC的配置，每个中断可以：
+          * 转换为MSI并通过总线/网络转发给IMSIC，
+          * 委托给子域，然后遵循类似的处理流程。
+  * MSI设备通路：
+    * MSI通过总线/网络直接路由到IMSIC。
+* IMSIC处理流程：
+  * 每个处理器核心通常有其专用的IMSIC。
+  * 每个IMSIC包含多个中断文件，每个特权态对应一个**中断文件**[^one_imsic_per_hart]：
+    * 一个**机器态**，
+    * 一个**监管态**，
+    * 多个**虚拟化监管态**。
+  * 每个中断文件：
+    * 维护中断状态(待处理、使能等)，
+    * 根据配置通过线路向处理器核心发出中断信号。
+
 Here are the detailed interrupts paths (note: "external" is omitted where context is clear):
 
 * Interrupts originate from either wired devices or MSI devices:
   * Wired device paths:
     * Interrupts are directed to APLIC's **interrupt domains**.
     * Each domain manages interrupts for a specific set of harts at a given privilege level.
-    * For large symmetric multiprocessing systems, typically two domains suffice [^two_interrupt_domains]:
+    * For large symmetric multiprocessing systems, typically two domains suffice[^two_interrupt_domains]:
       * One **machine-level domain**,
       * One **supervisor-level domain**.
     * Domains follow a hierarchical structure:
@@ -71,7 +131,7 @@ Here are the detailed interrupts paths (note: "external" is omitted where contex
     * MSIs route directly to IMSIC via bus/network.
 * IMSIC processing:
   * Each hart typically has its dedicated IMSIC.
-  * Each IMSIC contains multiple **interrupt files**, one per privilege level [^one_imsic_per_hart]:
+  * Each IMSIC contains multiple **interrupt files**, one per privilege level[^one_imsic_per_hart]:
     * One **machine level**,
     * One **supervisor level**,
     * Multiple **virtualized supervisor levels**.
@@ -79,7 +139,16 @@ Here are the detailed interrupts paths (note: "external" is omitted where contex
     * Maintains interrup status (pending, enabled, ...),
     * Signals hart based on configuration via wire connection.
 
-## Configuration Paths
+## 配置通路（Configuration Paths）
+
+配置流程遵循两个不同的通路：
+
+* IMSIC配置：
+  * 每个处理器核心只配置其专用的IMSIC，
+  * 配置通过线路连接进行。
+* APLIC配置：
+  * 所有处理器核心都可以配置APLIC，
+  * 配置以消息形式通过总线传输。
 
 Configuration flow follows two distinct paths:
 
@@ -92,7 +161,7 @@ Configuration flow follows two distinct paths:
 
 ![](./images/arch_configure_py.svg)
 
-## References
+## 引用（References）
 
 * [^two_interrupt_domains]: *The RISC-V Advanced Interrupt Architecture*: 4.2 Interrupt domains: Figure 4.
 * [^one_imsic_per_hart]: *The RISC-V Advanced Interrupt Architecture*: 1.3.2. External interrupts with IMSICs.