🧭集成指南（Integration Guide）

本指南介绍如何将ChiselAIA集成到RISC-V系统中。

This guide introduces the integration process of ChiselAIA into a RISC-V system.

概览（Overview）

集成涉及2个Scala文件，共4个Scala类：

  • APLIC.scala：
    • APLICParams：用于配置APLIC实例的参数类
    • APLIC：APLIC模块的核心逻辑
    • 每个系统需要一个实例：
      • TLAPLIC：对APLIC模块的Tilelink协议包装
      • AXI4APLIC：对APLIC模块的AXI4协议包装
  • IMSIC.scala：
    • IMSICParams：用于配置IMSIC实例的参数类
    • IMSIC：IMSIC模块的核心逻辑
    • 每个处理器核心需要一个实例：
      • TLIMSIC：对IMSIC模块的Tilelink协议包装
      • AXI4IMSIC：对IMSIC模块的AXI4协议包装

Integration involves 2 scala files, including 4 scala classes:

  • APLIC.scala:
    • APLICParams: Parameter classes for configuring APLIC instance.
    • APLIC: The main logic of APLIC module.
    • Requiring one instance per system:
      • TLAPLIC: The APLIC module wrapped by Tilelink protocol,
      • AXI4APLIC: The APLIC module wrapped by AXI4 protocol.
  • IMSIC.scala:
    • IMSICParams: Parameter classes for configuring IMSIC instances.
    • IMSIC: The main logic of IMSIC module.
    • Requiring one instance per hart:
      • TLIMSIC: The IMSIC module wrapped by Tilelink protocol,
      • AXI4IMSIC: The IMSIC module wrapped by AXI4 protocol.

参数（Parameters）

本节概述了APLIC和IMSIC的可配置参数。 虽然提供了默认值，但我们强烈建议根据具体的集成需求，自定义带有👉标记的参数。 其他参数要么是派生的，要么是硬编码的（详情参见Params.scala）。

This section outlines the configurable parameters for APLIC and IMSIC. While defaul values are provided, we strongly recommend customizing parameters marked with 👉 to suit your specific integration needs. Other parameters are either derived or hard-coded, (see Params.scala for details).

命名约定：

  • Num后缀：某实体的数量，
  • Width后缀：某实体的位宽（通常是log2(实体数量)），
  • Addr后缀：某实体的地址。

Naming conventions:

  • Num suffix: Number of the items.
  • Width suffix: Bit width of an item (typically log2(number of the item)).
  • Addr suffix: Address of an item.

IMSICParams

IMSIC中断源数量的对数，默认值8表示IMSIC支持最多256（2^8）个中断源 （Logarithm of number of interrupt sources to IMSIC. The default 8 means IMSIC support at most 256 (2^8) interrupt sources）:

  imsicIntSrcWidth     : Int  = 8          ,

👉 本IMSIC的机器态中断文件的地址（Address of machine-level interrupt files for this IMSIC）：

  mAddr           : Long = 0x00000L ,

👉 本IMSIC的监管态和客户态中断文件的地址（Addr for supervisor-level and guest-level interrupt files for this IMSIC）:

  sgAddr          : Long = 0x10000L ,

👉 客户中断文件的数量（Number of guest interrupt files）:

  geilen          : Int  = 4           ,

vgein信号的位宽（The width of the vgein signal）:

  vgeinWidth      : Int  = 6           ,

iselect信号的位宽(The width of iselect signal):

  iselectWidth    : Int  = 12          ,

APLICParams

APLIC接收的中断源数量的对数。 默认值7表示APLIC支持最多128（2^7）个中断源。 注意：aplicIntSrcWidth必须小于imsicIntSrcWidth， 因为APLIC的中断源将被转换为MSI， 而APLIC转换成的MSI是IMSIC中断源的子集。 （Logarithm of number of interrupt sources to APLIC: The default 7 means APLIC support at most 128 (2^7) interrupt sources. Note: aplicIntSrcWidth must be less than imsicIntSrcWidth, as APLIC interrupt sources are converted to MSIs, which are a subset of IMSIC's interrupt sources）：

  aplicIntSrcWidth: Int = 7,
  imsicIntSrcWidth: Int = 8,

👉 APLIC域的基地址（Base address of APLIC domains）:

  baseAddr: Long = 0x19960000L,

注意：下述中括号内的变量与AIA规范中的一致（第3.6节：用于多个中断文件的内存区域排列）。

Note: The following variables in bracket align with the AIA specification (Section 3.6: Memory Region Arrangement for Multiple Interrupt Files).

👉 每个组的成员数量（Number of members per group）[\(h_{max}\)]：

  membersNum      : Int  = 2           ,

👉 所有IMSIC的机器态中断文件的基地址（Base address of machine-level interrupt files for all IMSICs）[\(A\)]：

  mBaseAddr       : Long = 0x61000000L ,

👉 所有IMSIC的监管态和客户态中断文件的基地址（Base addr for supervisor-level and guest-level interrupt files for all IMSICs）[\(B\)]:

  sgBaseAddr      : Long = 0x82900000L ,

👉 组的数量（Number of groups ）[\(g_{max}\)]:

  groupsNum       : Int  = 1           ,

👉 客户中断文件的数量（Number of guest interrupt files）:

  geilen          : Int  = 4           ,

实例化（Instantiation）

  • APLICParams和IMSICParams：

    • 每个类一个实例，
    • 根据参数部分的说明，实例化参数。

  • TLAPLIC/AXI4APLIC：

    • 单个实例，
    • 参数params：接收APLICParams的实例，

  • TLIMSIC/AXI4IMSIC：

    • 每个核心一个实例，
    • 参数params：接收IMSICParams的实例，

  • APLICParams and IMSICParams:

    • Single instance each,
    • Instantiation parameters according to Parameters section.

  • TLAPLIC/AXI4APLIC:

    • Single instance,
    • Parameter params: receiving the APLICParams's instance,

  • TLIMSIC/AXI4IMSIC:

    • One instance per hart,
    • Parameter params: receiving the IMSICParams's instance,

关于hartIndex（About hartIndex）

根据AIA规范： AIA的hart编号 可能与RISC-V特权架构分配给hart的唯一 hart标识符（“hart ID”）无关。 在ChiselAIA中，hartIndex编码为groupID拼接上memberID。

According to the AIA specification: The AIA's hart index may or may not have any relationship to the unique hart identifier ("hart ID") that the RISC-V Privileged Architecture assigns to the hart. In ChiselAIA, the hartIndex is encoded as a concatenation of groupID and memberID:

示例（Examples）

简单的4核系统（A Simple 4-Hart System）

对于一个简单的未分组系统，设置groupsNum=1，则可以将hart ID复用作为AIA的`hartIndex：

For a simple ungrouped system, set groupsNum=1 to allow reuse of hart ID as AIA's hartIndex:

val imsic_params = IMSICParams()
val aplic_params = APLICParams(groupsNum=1, membersNum=4)
val imsics = (0 until 4).map( i => {
  val imsic = LazyModule(new TLIMSIC(imsic_params)(Parameters.empty))
val aplic = LazyModule(new TLAPLIC(aplic_params)(Parameters.empty))

分组的4核系统（A Grouped 4-Hart System）

在src/main/scala/Example.AIA和src/main/scala/Example-axi.scala中，我们提供了一个如何实例化APLIC核IMSIC的示例 （我们的单元测试也是基于该示例）。 以Tilelink为例，我们接下来展示一些关键的代码：

We provide an example of instantiating the APLIC and IMSIC, in src/main/scala/Example.AIA and src/main/scala/Example-axi.scala (Furthermore, we will use this example to conduct unit tests.). Take Tilelink as an example, we provide key lines of code below:

val imsic_params = IMSICParams()
val aplic_params = APLICParams(groupsNum=2, membersNum=2)
val imsics = (0 until 4).map( i => {
  val imsic = LazyModule(new TLIMSIC(imsic_params)(Parameters.empty))
val aplic = LazyModule(new TLAPLIC(aplic_params)(Parameters.empty))

此配置创建了一个2位的hartIndex，高位表示 groupID，低位表示 memberID。 有关详细的IO连接，请参考下图和src/main/scala/Example.AIA。

This configuration creates a 2-bit hartIndex where the higher bit represents groupID and the lower bit represents memberID. For detailed IO connections, refer to the following figure and src/main/scala/Example.AIA.