doc: 添加中文

docs/aplic.md

@@ -2,40 +2,71 @@
 
 <!-- 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:
 
 * The root domain (machine level) directly receives all wired interrupts,
 * 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,
 * One supervisor-level domain.
 
 ![](./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

docs/imsic.md

@@ -2,49 +2,74 @@
 
 <!-- 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.
 * `vgein`: Virtualized supervisor level selector.
 
 ![](./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,36 +81,54 @@ 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.
 These 4 pairs are divided into 2 **groups**, and each group contains 2 **members** (hart-IMSIC pairs).
 
 ![](./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: