进度概述

• 1: 目标验证单元
• 2: 准备验证环境
• 3: 运行测试
• 4: 添加测试
• 4.1: 添加编译脚本
• 4.2: 构建测试环境
• 4.3: 添加测试用例
• 4.4: 代码覆盖率
• 4.5: 功能覆盖率
• 5: 如何参与本项目
• 6: 模板-PR
• 7: 模板-ISSUE
• 8: 模板-UT-README
• 9: 常用API
• 10: 其他
• 11: 必要规范
• 12: 验证文档
• 12.1: 验证文档规范
• 12.1.1: 文档模板
• 12.1.2: FIFO文档案例
• 12.1.3: 果壳Cache文档案例
• 12.2: Frontend
• 12.2.1: FTQ概述
• 12.2.1.1: FTQ顶层
• 12.2.1.2: FTQ子队列
• 12.2.1.3: FTQ接收BPU分支预测结果
• 12.2.1.4: FTQ向IFU发送取指目标
• 12.2.1.5: IFU向FTQ写回预译码信息
• 12.2.1.6: FTQ接收后端重定向
• 12.2.1.7: FTQ接收IFU重定向
• 12.2.1.8: FTQ向后端发送取指目标
• 12.2.1.9: 执行单元修改FTQ状态队列
• 12.2.1.10: 冲刷指针和状态队列
• 12.2.1.11: FTQ向BPU发送更新与重定向信息
• 12.2.2: IFU
• 12.2.2.1: F3PreDecoder
• 12.2.2.2: FrontendTrigger
• 12.2.2.3: PredChecker
• 12.2.2.4: PreDecode
• 12.2.2.5: RVCExpander
• 12.2.3: ITLB
• 12.2.3.1: IO接口说明
• 12.2.3.2: 功能详述
• 12.2.3.3: 关键信号说明
• 12.2.3.4: 环境配置
• 12.3: Backend
• 12.4: Mem Block
• 12.5: Misc
• 13: 维护者

1 - 目标验证单元

上图共有-个模块，默认情况下模块为灰色，当模块中的测试用例数大于-时，该模块被完全点亮。目前已经完全点亮的模块为-个，待点亮的模块有-个。

通用处理器模块简介

高性能处理器是现代计算设备的核心，它们通常由三个主要部分组成：前端、后端和访存系统。这些部分协同工作，以确保处理器能够高效地执行复杂的计算任务。

• 前端：前端部分，也被称为指令获取和解码阶段，负责从内存中获取指令并将其解码成处理器可以理解的格式。这一阶段是处理器性能的关键，因为它直接影响到处理器可以多快地开始执行指令。前端通常包括指令缓存、分支预测单元和指令解码器。指令缓存用于存储最近访问过的指令，以减少对主内存的访问次数，从而提高处理速度。分支预测单元则尝试预测程序中的条件分支，以便提前获取和解码后续指令，这样可以减少等待分支结果的时间。

• 后端：后端部分，也称为执行阶段，是处理器中负责实际执行指令的地方。这一阶段包括了算术逻辑单元（ALU）、浮点单元（FPU）和各种执行单元。这些单元负责进行算术运算、逻辑运算、数据传输和其他处理器操作。后端的设计通常非常复杂，因为它需要支持多种指令集架构（ISA）并优化性能。为了提高效率，现代处理器通常采用超标量架构，这意味着它们可以同时执行多条指令。

• 访存：访存系统是处理器与内存之间交互的桥梁。它包括了数据缓存、内存控制器和高速缓存一致性协议。数据缓存用于存储处理器频繁访问的数据，以减少对主内存的访问次数。内存控制器负责管理处理器与内存之间的数据传输。高速缓存一致性协议确保在多处理器系统中，所有处理器看到的内存状态是一致的。

高性能处理器的设计需要在这三个部分之间找到平衡，以实现最佳的性能。这通常涉及到复杂的微架构设计，以及对处理器流水线的优化。

2 - 准备验证环境

基础环境需求

本项目基于Python编程语言进行UT验证，采用的工具和测试框架为picker和toffee，环境需求如下：

1. Linux操作系统。建议WSL2下安装Ubuntu22.04。
2. Python。建议Python3.11。
3. picker。按照快速开始中的提示安装最新版本。
4. lcov。用于后续test阶段报告生成。使用包管理器即可下载：sudo apt install lcov

环境配置完成后，clone仓库：

git clone https://github.com/XS-MLVP/UnityChipForXiangShan.git
cd UnityChipForXiangShan
pip3 install -r requirements.txt # 安装python依赖（例如 toffee）

下载RTL代码：

默认从仓库https://github.com/XS-MLVP/UnityChipXiangShanRTLs中下载。用户也可以自行按照XiangShan文档编译生成RTL。

make rtl    # 该命下载最新的rtl代码，并解压至rtl目录，并创建软连接

可以用以下命令指定下载的rtl版本：

make rtl args="rtl.version=\'openxiangshan-kmh-fad7803d-24120901\'"

所有RTL下载包请在UnityChipXiangShanRTLs中查看。

RTL压缩包的命名规范为：名称-微架构-Git标记-日期编号.tar.gz，例如openxiangshan-kmh-97e37a2237-24092701.tar.gz。在使用时，仓库代码会过滤掉git标记和后缀，例如通过 cfg.rtl.version 访问到的版本号为：openxiangshan-kmh-24092701。压缩包内的目录结构为：

openxiangshan-kmh-97e37a2237-24092701.tar.gz
└── rtl           # 目录
    |-- *.sv      # 所有sv文件
    `-- *.v       # 所有v文件

编译DUT

该过程的目的是将RTL通过picker工具打包为Python模块。可以通过make命令指定被打包DUT，也可以一次性打包所有DUT。

如果想要自行打包某个dut，需要创建编写scripts目录中的build_ut_<name>.py脚本。这一脚本必须实现一个build方法，在打包时会被自动调用。此外还有一个line_coverage_files方法，用于指定行覆盖率参考的文件。

picker的打包支持内部信号的加入，详见picker的--internal参数，传递给其一个自定义的yaml即可。

# 调用scripts目录中的build_ut_<name>.py中的build方法，创建待验证的Python版DUT
make dut DUTS=<name>  # DUTS的值如果有多个，需要用逗号隔开，支持通配符。DUTS默认值为 "*"，编译所有DUT
# 例如：
make dut DUTS=backend_ctrl_block_decode

以make dut DUTS=backend_ctrl_block_decode为例，命令执行完成后，会在dut目录下生成对应的Python包：

dut/
├── __init__.py
├── DecodeStage
├── Predecode
└── RVCExpander

完成转换后，在测试用例代码中可以import对应的DUT，例如：

from dut.PreDecode import DUTPreDecode
dut = DUTPreDecode()

编辑配置

运行rtl、dut、test等命令时，默认使用configs/_default.yaml中的配置项。

当然，也可以使用自定义配置，方法如下：

# 指定自定义CFG文件
make CFG=path/to/your_cfg.yaml

类似地，可以在命令行直接指定键值对传入。目前仅有test相关阶段支持命令行配置键值对：

# 指定KV，传递命令行参数，键值对之间用空格隔开
make test KV="log.term-level=\'debug\' test.skip-tags=[\'RARELY_USED\']"

3 - 运行测试

本项目基于PyTest测试框架进行验证。运行测试时，PyTest框架自动搜索所有test_*.py文件，并自动执行其中所有以test_开头的测试用例（Test Case）。

# 执行所有ut_*目录中的test case
make test_all
# 执行指定目录下的test case
make test target=<dir>
# 例如执行ut_backend/ctrl_block/decode目录中所有的test case
make test target=ut_backend/ctrl_block/decode

可通过args参数传递Pytest的运行参数，例如启动x-dist插件的多核功能：

make test args="-n 4"     # 启用 4 个进程
make test args="-n auto"  # 让框架自动选择启用多少个进程

*注：x-dist可以在多节点上并发运行测试，可参考其文档

运行完成后，默认在out/report目录会生成html版本的测试报告，其 html 文件可通过浏览器直接打开查看（VS Code IDE建议安装Open In Default Browser插件）。

运行测试主要完成以下三部分内容：

1. 按要求运行Test Case，可通过cfg.tests中的选项进行配置
2. 统计测试结果，输出测试报告。有toffee-report自动生成 (总测试报告，所有Test的结果合并在一起)
3. 根据需要（cfg.doc_result.disable = True）在测试报告上进行进一步数据统计

4 - 添加测试

添加一个全新的 DUT 测试用例，需要完成以下三部分内容(本节以前端的ifu下的rvc_expander为例)：

1. 添加编译脚本： 在scripts目录下使用python编写对应rtl的编译文件（例如build_ut_frontend_ifu_rvc_expander.py）。
2. 构建测试环境： 在目录中创建目标测试 UT 目录（例如ut_frontend/ifu/rvc_expander）。如果有需要的话，可以在tools、comm等模块中添加该 DUT 测试需要的基础工具。
3. 添加测试用例： 在测试 UT 目录，按PyTest 规范添加测试用例。

如果是在已有的 DUT 测试中增加内容，按原有目录结构添加即可。

如何通过 picker 和 toffee 库进行 Python 芯片验证，请参考：https://open-verify.cc/mlvp/docs

在测试时还需要关心以下内容：

1. UT 模块说明: 在添加的模块顶层文件夹中，添加README.md说明，具体格式和要求请参考模板。
2. 代码覆盖率：代码覆盖率是芯片验证的重要指标，一般需需要覆盖目标 DUT 的所有代码。
3. 功能覆盖率：功能覆盖率即目标功能验证完成了多少，一般需要达到 100%。

在后续的文档中，我们将继续以rvc_expander模块为例，详细说明上述过程。

*注：目录或文件名称需要合理，以便于能通过命名知晓其具体含义。

4.1 - 添加编译脚本

脚本目标

在scripts目录下使用python编写对应rtl的编译文件（例如build_ut_frontend_ifu_rvc_expander.py）。
该脚本的目标是提供 RTL 到 Python DUT 的编译、目标覆盖文件，以及自定义功能等内容。

创建过程

确定文件名称

在香山昆明湖 DUT 验证进展中选择需要验证的 UT，如果没有或者进一步细化，可通过编辑configs/dutree/xiangshan-kmh.yaml自行添加。
比如，我们要验证的是前端部分的ifu模块下的rvc_expander模块，那么需要在configs/dutree/xiangshan-kmh.yaml中添加对应的部分（目前yaml中已经有该模块了，此处为举例）：

name: "kmh_dut"
desc: "所有昆明湖DUT"
children:
  - name: "frontend"
    desc: "前端模块"
    children:
      - name: "ifu"
        desc: "指令单元 (Instruction Fetch Unit)"
        children:
          - name: "rvc_expander"
            desc: "RVC指令扩充器"

脚本文件的命名格式如下：

scripts/build_<顶层模块>_<下层模块名>_..._<目标模块名>.py

目前本项目内置了 4 个顶层模块：

1. ut_frontend 前端
2. ut_backend 后端
3. ut_mem_block 访存
4. ut_misc 其他

其中的子模块没有ut_前缀（顶层目录有该前缀是为了和其他目录区分开）。

例如验证目标 DUT 为rvc_expander模块：
该模块是属于前端的，所以顶级模块为ut_frontend，它的下层模块为ifu，目标模块为rvc_expander。
通过刚才我们打开的yaml文件也可以知道，frontend的children 为ifu，ifu的children 为rvc_expander。
所以，需要创建的脚本名称为build_ut_frontend_ifu_rvc_expander.py。

编写 build(cfg) -> bool 函数

build 函数定义如下：

def build(cfg) -> bool:
    """编译DUT
    Args:
        cfg: 运行时配置，可通过它访问配置项，例如 cfg.rtl.version
    Return:
        返回 True 或者 False，表明该函数是否完成预期目标
    """

build 在 make dut 时会被调用，其主要是将目标 RTL 转换为 Python 模块。在该过程中也可以加入其他必要过程，例如编译依赖项等。以build_ut_frontend_ifu_rvc_expander.py为例，主要完成了 RTL 检查、DUT 检查、RTL 编译、disasm 依赖编译等工作：

import os
from comm import warning, info


def build(cfg):
    # import 相关依赖
    from toffee_test.markers import match_version
    from comm import is_all_file_exist, get_rtl_dir, exe_cmd, get_root_dir
    # 检查RTL版本（version参数为空，表示所有版本都支持）
    if not match_version(cfg.rtl.version, "openxiangshan-kmh-*"):
        warning("ifu frontend rvc expander: %s" % f"Unsupported RTL version {cfg.rtl.version}")
        return False
    # 检查在当前RTL中，目标文件是否存在
    f = is_all_file_exist(["rtl/RVCExpander.sv"], get_rtl_dir(cfg=cfg))
    assert f is True, f"File {f} not found"
    # 如果dut中不存在RVCExpander，则调用picker进行Python打包
    if not os.path.exists(get_root_dir("dut/RVCExpander")):
        info("Exporting RVCExpander.sv")
        s, out, err = exe_cmd(f'picker export --cp_lib false {get_rtl_dir("rtl/RVCExpander.sv", cfg=cfg)} --lang python --tdir {get_root_dir("dut")}/ -w rvc.fst -c')
        assert s, "Failed to export RVCExpander.sv: %s\n%s" % (out, err)
    # 如果tools中不存在disasm/build，则需要编译disasm
    if not os.path.exists(get_root_dir("tools/disasm/build")):
        info("Building disasm")
        s, _, _ = exe_cmd("make -C %s" % get_root_dir("tools/disasm"))
        assert s, "Failed to build disasm"
    # 编译成功
    return True

def line_coverage_files(cfg):
    return ["RVCExpander.v"]

picker 的使用方式请参考其文档和使用

在scripts目录中可以创建子目录保存 UT 验证需要的文件，例如 rvc_expander 模块创建了scripts/frontend_ifu_rvc_expander目录，其中的rtl_file.f用来指定输入的 RTL 文件，line_coverage.ignore用来保存需要忽略的代码行统计。自定义目录的命名需要合理，且能通过名字判断其所属模块和文件。

编写 line_coverage_files(cfg) -> list[str] 函数

line_coverage_files 函数的定义如下：

def line_coverage_files(cfg)-> list[str]:
    """指定需要覆盖的文件
    Args:
        cfg: 运行时配置，可通过它访问配置项，例如 cfg.rtl.version
    Return:
        返回统计代码行覆盖率的目标RTL文件名
    """

在build_ut_frontend_ifu_rvc_expander.py文件中，line_coverage_files函数的定义如下：

def line_coverage_files(cfg):
    return ["RVCExpander.v"]

标识该模块关注的是对RVCExpander.v文件的覆盖。如果要开启测试结果处理，还需要在configs/_default.yaml中的doc-result下disable=False（默认参数是False，也就是开启状态）;如果不开启测试结果处理则(disable = True)。注意，如果不开启测试结果处理，那么上述函数就不会被调用。

4.2 - 构建测试环境

确定目录结构

UT(Unit Test, 单元测试)所在的目录位置的层级结构应该与名称一致，例如frontend.ifu.rvc_expander应当位于ut_frontend/ifu/rvc_expander目录，且每层目录都需要有__init__.py，便于通过 python 进行import。

本章节的文件为your_module_wrapper.py（如果你的模块是rvc_expander，那么文件就是rvc_expander_wrapper.py）。

wrapper 是包装的意思，也就是我们测试中需要用到的方法封装成和dut解耦合的API提供给测试用例使用。

*注：解耦合是为了测试用例和 DUT 解耦，使得测试用例可以独立于 DUT 进行编写和调试，也就是在测试用例中，不需要知道 DUT 的具体实现细节，只需要知道如何使用 API 即可。可以参照将验证代码与DUT进行解耦

该文件应该放于ut_frontend_or_backend/top_module/your_module/env（这里依然以rvc_expander举例：rvc_expander属于前端，其顶层目录则应该是ut_frontend；rvc_expander的顶层模块是ifu，那么次级目录就是ifu;之后的就是rvc_expander自己了；最后，由于我们是在构建测试环境，再建一级env目录。将它们连起来就是：ut_frontend_or_backend/top_module/your_module/env）目录下。

ut_frontend/ifu/rvc_expander
├── classical_version
│   ├── env
│   │   ├── __init__.py
│   │   └── rvc_expander_wrapper.py
│   ├── __init__.py
│   └── test_rvc_expander.py
├── __init__.py
├── README.md
└── toffee_version
    ├── agent
    │   └── __init__.py
    ├── bundle
    │   └── __init__.py
    ├── env
    │   ├── __init__.py
    │   └── ref_rvc_expand.py
    ├── __init__.py
    └── test
        ├── __init__.py
        ├── rvc_expander_fixture.py
        └── test_rvc.py

这里rvc_expander目录下有classical_version传统版本和toffee_version使用toffee的版本。 传统版本就是使用pytest框架来进行测试，toffee只使用了其Bundle;而在toffee版本中，我们会使用更多toffee的特性。
一般来说，使用传统版本就已经可以覆盖绝大多数情况了，只有在传统版本不能满足需求时，才需要使用toffee版本。
编写测试环境的时候，两个版本选择一个就行。
模块（例如rvc_expander）中的代码目录结构由贡献者自行决定（我们写的时候并不需要再建一级classical_version或toffee_version目录），但需要满足 python 规范，且逻辑和命名合理。

Env 编写要求

• 需要进行 RTL 版本检查
• Env 提供的 API 需要和引脚、时序无关
• Env 提供的 API 需要稳定，不能随意进行接口/返回值修改
• 需要定义必要的 fixture
• 需要初始化功能检查点（功能检查点可以独立成一个模块）
• 需要进行覆盖率统计
• 需要有说明文档

编写测试环境：传统版本

在 UT 验证模块的测试环境中，目标是完成以下工作：

1. 对 DUT 进行功能封装，为测试提供稳定 API
2. 定义功能覆盖率
3. 定义必要 fixture 提供给测试用例
4. 在合理时刻统计覆盖率

以 IFU 环境中的 RVCExpander 为例（ut_frontend/ifu/rvc_expander/classical_version/env/rvc_expander_wrapper.py）：

1. DUT 封装

以下内容位于ut_frontend/ifu/rvc_expander/classical_version/env/rvc_expander_wrapper.py。

class RVCExpander(toffee.Bundle):
    def __init__(self, cover_group, **kwargs):
        super().__init__()
        self.cover_group = cover_group
        self.dut = DUTRVCExpander(**kwargs) # 创建DUT
        self.io = toffee.Bundle.from_prefix("io_", self.dut) # 通过 Bundle 使用前缀关联引脚
        self.bind(self.dut)                 # 把 Bundle 与 DUT 进行绑定

    def expand(self, instr, fsIsOff):
        self.io["in"].value = instr         # 给DUT引脚赋值
        self.io["fsIsOff"].value = fsIsOff  # 给DUT引脚赋值
        self.dut.RefreshComb()              # 推动组合电路
        self.cover_group.sample()           # 调用sample对功能覆盖率进行统计
        return self.io["out_bits"].value, self.io["ill"].value  # 返回结果 和 是否是非法指令

    def stat(self):                         # 获取当前状态
        return {
            "instr": self.io["in"].value,         # 输入指令
            "decode": self.io["out_bits"].value,  # 返回展开结果
            "ilegal": self.io["ill"].value != 0,  # 输入是否非法
        }

在上述例子中，class RVCExpander对DUTRVCExpander进行了封装，对外提供了两个 API：

• expand(instr: int, fsIsOff: bool) -> (int, int) ：该函数用于接受输入指令 instr 进行解码，返回（结果，非法指令标记）。如果非法指令标记不为 0，者说明输入指令非法。
• stat() -> dict(instr, decode, ilegal)：该函数用于返回当前的状态，其中包含当前的输入指令，解码结果以及非法指令标记。

上述 API 屏蔽了 DUT 的引脚，对外程序通用功能。

2. 定义功能覆盖率

尽可能的在 Env 中定义好功能覆盖率，如果有必要也可以在测试用例中定义覆盖率。toffee 功能覆盖率的定义请参考什么是功能覆盖率。为了完善功能检查点和测试用例之间的对应关系，功能覆盖率定义完成后，需要在适合的位置进行检查点和测试用例的对应（测试点反标）。

以下内容位于ut_frontend/ifu/rvc_expander/classical_version/env/rvc_expander_wrapper.py。

import toffee.funcov as fc
# 创建功能覆盖率组
g = fc.CovGroup(UT_FCOV("../../../CLASSIC"))

def init_rvc_expander_funcov(expander, g: fc.CovGroup):
    """Add watch points to the RVCExpander module to collect function coverage information"""

    # 1. Add point RVC_EXPAND_RET to check expander return value:
    #    - bin ERROR. The instruction is not illegal
    #    - bin SUCCE. The instruction is not expanded
    g.add_watch_point(expander, {
                                "ERROR": lambda x: x.stat()["ilegal"] == False,
                                "SUCCE": lambda x: x.stat()["ilegal"] != False,
                          }, name = "RVC_EXPAND_RET")
    ...
    # 5. Reverse mark function coverage to the check point
    def _M(name):
        # get the module name
        return module_name_with(name, "../../test_rv_decode")

    #  - mark RVC_EXPAND_RET
    g.mark_function("RVC_EXPAND_RET",     _M(["test_rvc_expand_16bit_full",
                                              "test_rvc_expand_32bit_full",
                                              "test_rvc_expand_32bit_randomN"]), bin_name=["ERROR", "SUCCE"])
    ...

在上述代码中添加了名为RVC_EXPAND_RET的功能检查点来检查RVCExpander模块是否具有返回非法指令的能力。需要满足ERROR和SUCCE两个条件，即stat()中的ileage需要有True也需要有False值。在定义完检查点后，通过mark_function方法，对会覆盖到该检查的测试用例进行了标记。

3. 定义必要fixture

以下内容位于ut_frontend/ifu/rvc_expander/classical_version/env/rvc_expander_wrapper.py。

version_check = get_version_checker("openxiangshan-kmh-*")             # 指定满足要的RTL版本
@pytest.fixture()
def rvc_expander(request):
    version_check()                                                    # 进行版本检查
    fname = request.node.name                                          # 获取调用该fixture的测试用例
    wave_file = get_out_dir("decoder/rvc_expander_%s.fst" % fname)     # 设置波形文件路径
    coverage_file = get_out_dir("decoder/rvc_expander_%s.dat" % fname) # 设置代码覆盖率文件路径
    coverage_dir = os.path.dirname(coverage_file)
    os.makedirs(coverage_dir, exist_ok=True)                           # 目标目录不存在则创建目录
    expander = RVCExpander(g, coverage_filename=coverage_file, waveform_filename=wave_file)
                                                                       # 创建RVCExpander
    expander.dut.io_in.AsImmWrite()                                    # 设置io_in引脚的写入时机为立即写入             
    expander.dut.io_fsIsOff.AsImmWrite()                               # 设置io_fsIsOff引脚的写入时机为立即写入  
    init_rvc_expander_funcov(expander, g)                              # 初始化功能检查点
    yield expander                                                     # 返回创建好的 RVCExpander 给 Test Case
    expander.dut.Finish()                                              # Tests Case运行完成后，结束DUT
    set_line_coverage(request, coverage_file)                          # 把生成的代码覆盖率文件告诉 toffee-report
    set_func_coverage(request, g)                                      # 把生成的功能覆盖率数据告诉 toffee-report
    g.clear()                                                          # 清空功能覆盖统计

上述 fixture 完成了以下功能：

1. 进行 RTL 版本检查，如果不满足"openxiangshan-kmh-*"要求，则跳过调用改 fixture 的测试用例
2. 创建 DUT，并指定了波形，代码行覆盖率文件路径（路径中含有调用该 fixure 的用例名称：fname）
3. 调用init_rvc_expander_funcov添加功能覆盖点
4. 结束 DUT，处理代码行覆盖率和功能覆盖率（发往 toffee-report 进行处理）
5. 清空功能覆盖率

*注：在 PyTest 中，执行测试用例test_A(rvc_expander, ....)前（rvc_expander是我们在使用fixure装饰器时定义的方法名），会自动调用并执行rvc_expander(request)中yield关键字前的部分（相当于初始化），然后通过yield返回rvc_expander调用test_A用例（yield返回的对象，在测试用例里就是我们fixture下定义的方法名），用例执行完成后，再继续执行fixture中yield关键字之后的部分。比如：参照下面统计覆盖率的代码，倒数第四行的 rvc_expand(rvc_expander, generate_rvc_instructions(start, end))，其中的rvc_expander就是我们在fixture中定义的方法名，也就是yield返回的对象。

4. 统计覆盖率

以下内容位于ut_frontend/ifu/rvc_expander/classical_version/test_rvc_expander.py

N = 10
T = 1<<16
@pytest.mark.toffee_tags(TAG_LONG_TIME_RUN)
@pytest.mark.parametrize("start,end",
                         [(r*(T//N), (r+1)*(T//N) if r < N-1 else T) for r in range(N)])
def test_rvc_expand_16bit_full(rvc_expander, start, end):
    """Test the RVC expand function with a full compressed instruction set

    Description:
        Perform an expand check on 16-bit compressed instructions within the range from 'start' to 'end'.
    """
    # Add check point: RVC_EXPAND_RANGE to check expander input range.
    #   When run to here, the range[start, end] is covered
    covered = -1
    g.add_watch_point(rvc_expander, {
                                "RANGE[%d-%d]"%(start, end): lambda _: covered == end
                          }, name = "RVC_EXPAND_ALL_16B", dynamic_bin=True)
    # Reverse mark function to the check point
    g.mark_function("RVC_EXPAND_ALL_16B", test_rvc_expand_16bit_full, bin_name="RANGE[%d-%d]"%(start, end))
    # Drive the expander and check the result
    rvc_expand(rvc_expander, generate_rvc_instructions(start, end))
    # When go to here, the range[start, end] is covered
    covered = end
    g.sample()                                                              # 覆盖率采样

在定义了覆盖率之后，还需要在测试用例中进行覆盖率统计。上述代码中，在测试用例中使用add_watch_point添加了一个功能检查点rvc_expander，并在后面进行了标记和采样,而且在最后一样对覆盖率进行了采样。 覆盖率采样，实际上是通过回调函数触发了一次add_watch_point中bins的判断，当其中bins的判断结果为True时，就会统计一次Pass。

编写测试环境：toffee版本

使用python语言进行的测试可以通过引入我们的开源测试框架toffee来得到更好的支持。

toffee的官方教程可以参考这里。

bundle：快捷DUT封装

toffee通过Bundle实现了对DUT的绑定。toffee提供了多种建立Bundle与DUT绑定的方法。相关代码

手动绑定

toffee框架下，用于支持绑定引脚的最底层类是Signal，其通过命名匹配的方式和DUT中的各个引脚进行绑定。相关代码参照ut_frontend/ifu/rvc_expander/toffee_version。

以最简单的RVCExpander为例，其io引脚形如：

module RVCExpander(
  input  [31:0] io_in,
  input         io_fsIsOff,
  output [31:0] io_out_bits,
  output        io_ill
);

一共四个信号，io_in, io_fsIsOff, io_out_bits, io_ill。我们可以抽取共同的前缀，比如"io_"（不过由于in在python中有其他含义，其不能直接作为变量名，虽然可以使用setattr 和getattr方法来规避这个问题，但是出于代码简洁的考虑，我们只选取"io"作为前缀），将后续部分作为引脚名定义在对应的Bundle类中：

class RVCExpanderIOBundle(Bundle):
	_in, _fsIsOff ,_out_bits,_ill = Signals(4)

然后在更高一级的Env或者Bundle中，采取from_prefix的方式完成前缀的绑定：

self.agent = RVCExpanderAgent(RVCExpanderIOBundle.from_prefix("io").bind(dut))

自动定义Bundle

实际上，Bundle类的定义也不一定需要写明，可以仅仅通过前缀绑定：

self.io = toffee.Bundle.from_prefix("io_", self.dut) # 通过 Bundle 使用前缀关联引脚
self.bind(self.dut)   

如果Bundle的from_prefix方法传入dut，其将根据前缀和DUT的引脚名自动生成引脚的定义，而在访问的时候，使用dict访问的思路即可：

self.io["in"].value = instr
self.io["fsIsOff"].value = False

Bundle代码生成

toffee框架的scripts提供了两个脚本。

bundle_code_gen.py脚本主要提供了三个方法：

def gen_bundle_code_from_dict(bundle_name: str, dut, dict: dict, max_width: int = 120)
def gen_bundle_code_from_prefix(bundle_name: str, dut, prefix: str = "", max_width: int = 120):
def gen_bundle_code_from_regex(bundle_name: str, dut, regex: str, max_width: int = 120):

通过传入dut和生成规则（包括dict、prefix、regex三种），自动生成对应的bundle代码。

而bundle_code_intel_gen.py则解析picker生成的signals.json文件，自动生成层次化的bundle代码。可以直接在命令行调用：

python bundle_code_intel_gen.py [signal] [target]

如发现自动生成脚本存在bug，欢迎提issue以便我们修正。

Agent：驱动方法

如果说Bundle是将DUT的数据职责进行抽象的话，那么Agent则是将DUT的行为职责封装为一个个接口。简单地说，Agent通过封装多个对外开放的方法，将多组IO操作抽象为一个具体的行为：

class RVCExpanderAgent(Agent):
    def __init__(self, bundle:RVCExpanderIOBundle):
        super().__init__(bundle)
        self.bundle = bundle
    
    @driver_method()
    async def expand(self, instr, fsIsOff):             # 传入参数：RVC指令和fs.status使能情况
        self.bundle._in.value = instr                   # 引脚赋值
        self.bundle._fsIsOff.value = fsIsOff            # 引脚赋值
        
        await self.bundle.step()                        # 推动时钟
        return self.bundle._out_bits.value,             # 返回值：扩展后指令
                self.bundle._ill.value                  # 返回值：指令合法校验

譬如，RVCExpander的指令扩展功能接收输入的指令（可能为RVI指令，也可能为RVC指令）和CSR对fs.status的使能情况。我们将这个功能抽象为expand方法，提供除self以外的两个参数。同时，指令扩展最终将会返回传入指令对应的RVI指令和该指令是否合法的判断，对应地，该方法也返回这两个值。

Env：测试环境

class RVCExpanderEnv(Env):
    def __init__(self, dut:DUTRVCExpander):
        super().__init__()
        dut.io_in.xdata.AsImmWrite()        
        dut.io_fsIsOff.xdata.AsImmWrite()   # 设置引脚写入时机
        self.agent = RVCExpanderAgent(RVCExpanderIOBundle.from_prefix("io").bind(dut)) # 补全前缀，绑定DUT

覆盖率定义

定义覆盖率组的方式和前述方式类似，这里就不再赘述了。

测试套件定义

测试套件的定义略有不同：

@toffee_test.fixture
async def rvc_expander(toffee_request: toffee_test.ToffeeRequest):
    import asyncio
    version_check()
    dut = toffee_request.create_dut(DUTRVCExpander)
    start_clock(dut)
    init_rvc_expander_funcov(dut, gr)
    
    toffee_request.add_cov_groups([gr])
    expander = RVCExpanderEnv(dut)
    yield expander

    cur_loop = asyncio.get_event_loop()
    for task in asyncio.all_tasks(cur_loop):
        if task.get_name() == "__clock_loop":
            task.cancel()
            try:
                await task
            except asyncio.CancelledError:
                break

由于toffee提供了更强大的测试覆盖率管理功能，因此不需要手动设置行覆盖率。同时，由于toffee的时钟机制，建议在套件代码最后额外检查任务是否全部结束。

4.3 - 添加测试用例

命名要求

所有测试用例文件请以test_*.py的方式进行命名，*用测试目标替换（例如test_rvc_expander.py）。所有测试用例也需要以test_前缀开头。用例名称需要具有明确意义。

命名举例如下：

def test_a(): # 不合理，无法通过a判断测试目标
    pass

def test_rvc_expand_16bit_full(): # 合理，可以通过用例名称大体知道测试内容
    pass

使用 Assert

在每个测试用例中，都需要通过assert来判断本测试是否通过。 pytest统计的是assert语句的结果，因此assert语句需要保证能够通过。

以下内容位于ut_frontend/ifu/rvc_expander/classical_version/test_rvc_expander.py中：

def rvc_expand(rvc_expander, ref_insts, is_32bit=False, fsIsOff=False):
    """compare the RVC expand result with the reference

    Args:
        rvc_expander (warpper): the fixture of the RVC expander
        ref_insts (list[int]]): the reference instruction list
    """
    find_error = 0
    for insn in ref_insts:
        insn_disasm = disasmbly(insn)
        value, instr_ex = rvc_expander.expand(insn, fsIsOff)
        if is_32bit:
            assert value == insn, "RVC expand error, 32bit instruction need to be the same"
        if (insn_disasm == "unknown") and  (instr_ex == 0):
            debug(f"find bad inst:{insn}, ref: 1, dut: 0")
            find_error +=1
        elif (insn_disasm != "unknown") and  (instr_ex == 1):
            if (instr_filter(insn_disasm) != 1): 
                debug(f"find bad inst:{insn},disasm:{insn_disasm}, ref: 0, dut: 1")
                find_error +=1
    assert 0 == find_error, "RVC expand error (%d errros)" % find_error

编写注释

每个测试用例都需要添加必要的说明和注释，需要满足Python 注释规范。

测试用例说明参考格式：

def test_<name>(a: type_a, b: type_b):
    """Test abstract

    Args:
        a (type_a): description of arg a.
        b (type_b): description of arg b.

    Detailed test description here (if need).
    """
    ...

用例管理

为了方便测试用例管理，可通过 toffee-test 提供的@pytest.mark.toffee_tags标签功能，请参考 本网站的其他部分和toffee-test。

参考用例

如果很多测试用例（Test）具有相同的操作，该公共操作部分可以提炼成一个通用函数。以 RVCExpander 验证为例，可以把压缩指令的展开与参考模型（disasm）的对比封装成以下函数：

以下内容位于ut_frontend/ifu/rvc_expander/classical_version/test_rvc_expander.py中：

def rvc_expand(rvc_expander, ref_insts, is_32bit=False, fsIsOff=False):
    """compare the RVC expand result with the reference

    Args:
        rvc_expander (warpper): the fixture of the RVC expander
        ref_insts (list[int]]): the reference instruction list
    """
    find_error = 0
    for insn in ref_insts:
        insn_disasm = disasmbly(insn)
        value, instr_ex = rvc_expander.expand(insn, fsIsOff)
        if is_32bit:
            assert value == insn, "RVC expand error, 32bit instruction need to be the same"
        if (insn_disasm == "unknown") and  (instr_ex == 0):
            debug(f"find bad inst:{insn}, ref: 1, dut: 0")
            find_error +=1
        elif (insn_disasm != "unknown") and  (instr_ex == 1):
            if (instr_filter(insn_disasm) != 1): 
                debug(f"find bad inst:{insn},disasm:{insn_disasm}, ref: 0, dut: 1")
                find_error +=1
    assert 0 == find_error, "RVC expand error (%d errros)" % find_error

在上述公共部分中有 assert，因此调用该函数的 Test 也能提过该 assert 判断运行结果是否提过。

在测试用例的开发过程中，通常存在大量的调试工作，为了让验证环境快速就位，需要编写一些“冒烟测试”进行调试。RVCExpander 展开 16 位压缩指令的冒烟测试如下：

@pytest.mark.toffee_tags(TAG_SMOKE)
def test_rvc_expand_16bit_smoke(rvc_expander):
    """Test the RVC expand function with 1 compressed instruction"""
    rvc_expand(rvc_expander, generate_rvc_instructions(start=100, end=101))

为了方便进行管理，上述测试用例通过toffee_tags标记上了 SMOKE 标签。它的输入参数为rvc_expander，则在在运行时，会自动调用对应同名的fixture进行该参数的填充。

RVCExpander 展开 16 位压缩指令的测试目标是对 2^16 所有压缩指令进行遍历，检测所有情况是否都与参考模型 disasm 一致。在实现上，如果仅仅用一个 Test 进行遍历，则需要耗费大量时间，为此我们可以利用 PyTest 提供的parametrize对 test 进行参数化配置，然后通过pytest-xdist插件并行执行：

以下内容位于ut_frontend/ifu/rvc_expander/classical_version/test_rvc_expander.py中：

N = 10
T = 1<<16
@pytest.mark.toffee_tags(TAG_LONG_TIME_RUN)
@pytest.mark.parametrize("start,end",
                         [(r*(T//N), (r+1)*(T//N) if r < N-1 else T) for r in range(N)])
def test_rvc_expand_16bit_full(rvc_expander, start, end):
    """Test the RVC expand function with a full compressed instruction set

    Description:
        Perform an expand check on 16-bit compressed instructions within the range from 'start' to 'end'.
    """
    # Add check point: RVC_EXPAND_RANGE to check expander input range.
    #   When run to here, the range[start, end] is covered
    g.add_watch_point(rvc_expander, {
                                "RANGE[%d-%d]"%(start, end): lambda _: True
                          }, name = "RVC_EXPAND_ALL_16B").sample()

    # Reverse mark function to the check point
    g.mark_function("RVC_EXPAND_ALL_16B", test_rvc_expand_16bit_full, bin_name="RANGE[%d-%d]"%(start, end))

    # Drive the expander and check the result
    rvc_expand(rvc_expander, generate_rvc_instructions(start, end))

在上述用例中定义了参数化参数start, end，用来指定压缩指令的开始值和结束值，然后通过装饰器@pytest.mark.parametrize对他们进行分组赋值。变量 N 可以指定将目标数据进行分组的组数，默认设置为 10 组。在运行时用例test_rvc_expand_16bit_full会展开为test_rvc_expand_16bit_full[0-6553]至test_rvc_expand_16bit_full[58977-65536]10 个测试用例运行。

4.4 - 代码覆盖率

代码覆盖率是一项评价指标，它衡量了被测代码中哪些部分被执行了，哪些部分没有被执行。通过统计代码覆盖率，可以评估测试的有效性和覆盖程度。

代码覆盖率包括：

• 行覆盖率(line coverage): 被测代码中被执行的行数，最简单的指标，一般期望达到 100%。
• 条件覆盖率(branch coverage): 每一个控制结构的每个分支是否均被执行。例如，给定一个 if 语句，其 true 和 false 分支是否均被执行？
• 有限状态机覆盖率(fsm coverage): 状态机所有状态是否都达到过。
• 翻转覆盖率(toggle coverage): 统计被测代码中被执行的翻转语句，检查电路的每个节点是否都有 0 -> 1 和 1 -> 0 的跳变。
• 路径覆盖率(path coverage): 检查路径的覆盖情况。在 always 语句块和 initial 语句块中，有时会使用 if … else 和 case 语句，在电路结构上便会产生一系列的数据路径。。

*我们主要使用的模拟器是 Verilator,优先考虑行覆盖率。Verilator 支持覆盖率统计，因此我们在构建 DUT 时，如果要开启覆盖率统计，需要在编译选项中添加-c参数。

本项目中相关涉及位置

开启覆盖率需要在编译时（使用 picker 命令时）加上“-c”参数（参考 picker 的参数解释），同时在文件中设置启用行覆盖率，这样在使用 toffee 测试时，才能够生成覆盖率统计文件。

结合上面的描述，在本项目中也就是编译，编写和启用行覆盖率函数和测试的时候会涉及到代码覆盖率：

添加编译脚本部分

编写编译脚本

# 省略前面
    if not os.path.exists(get_root_dir("dut/RVCExpander")):
        info("Exporting RVCExpander.sv")
        s, out, err = exe_cmd(f'picker export --cp_lib false {get_rtl_dir("rtl/RVCExpander.sv", cfg=cfg)
                                                              } --lang python --tdir {get_root_dir("dut")}/ -w rvc.fst -c')
        assert s, "Failed to export RVCExpander.sv: %s\n%s" % (out, err)
# 省略后面

在s, out, err=...这一行，我们使用 picker 命令，并且开启代码了覆盖率(命令最后的"-c"参数)。

设置目标覆盖文件(line_coverage_files 函数)

按照需求编写line_coverage_files(cfg) -> list[str]函数，并且开启测试结果处理(doc_result.disable = False)让其被调用。

构建测试环境部分

定义必要 fixture

set_line_coverage(request, coverage_file)                          # 把生成的代码覆盖率文件告诉 toffee-report

通过函数toffee-test.set_line_coverage把覆盖率文件传递给 toffe-test，这样其才能够收集数据，以便于后面生成的报告带有行覆盖率。

忽略指定统计

有时候，我们可能需要手动指定某些内容不参与覆盖率统计。例如有些是不需要被统计的，有些统计不到是正常的。这时候我们就可以忽略这些内容，这对优化覆盖率报告或调试非常有帮助。 目前我们的框架可以使用两种方式来实现忽略统计的功能：

1.通过 verilator 指定忽略统计的内容

使用 verilator_coverage_off/on 指令

Verilator 支持通过注释指令来忽略特定代码段的覆盖率统计。例如，使用如下的指令：

// *verilator coverage_off*
// 忽略统计的代码段
...
// *verilator coverage_on*

举个例子

module example;
    always @(posedge clk) begin
        // *verilator coverage_off*
        if (debug_signal) begin
            $display("This is for debugging only");
        end
        // *verilator coverage_on*
        if (enable) begin
            do_something();
        end
    end
endmodule

在上述示例中，debug_signal 部分的代码将不会计入覆盖率统计，而 enable 部分仍然会被统计。

更多 verilator 的忽略统计方式请参照verilator 官方文档

2.通过 toffee 指定需要过滤掉的内存

def set_line_coverage(request, datfile, ignore=[]):
    """Pass

    Args:
        request (pytest.Request): Pytest的默认fixture，
        datfile (string): DUT生成的
        ignore (list[str]): 覆盖率过滤文件/或者文件夹
    """

ignore 参数可以指定在覆盖率文件中需要过滤掉的内容，例如：

...
set_line_coverage(request, coverage_file,
                  get_root_dir("scripts/frontend_ifu_rvc_expander"))

在统计覆盖率时，会在"scripts/frontend_ifu_rvc_expander"目录中搜索到line_coverage.ignore文件，然后按其中每行的通配符进行过滤。

# Line covarge ignore file
# ignore Top file
*/RVCExpander_top*%

上述文件表示，在统计覆盖率时，会忽略掉包含"RVCExpander_top"关键字的文件（实际上是收集了对应的数据，但是最后统计的时候忽略了）。

查看统计结果

在经过前面所有步骤之后，包括准备测试环境中的下载 RTL 代码、编译 DUT、编辑配置 ；添加测试中的添加编译脚本,构建测试环境、添加测试用例。

现在运行测试,之后就默认在out/report目录会生成 html 版本的测试报告。

也可以在进度概述图形下方的“当前版本”选择对应的测试报告(按照测试时间命名)，然后点击右侧链接即可查看统计结果。

4.5 - 功能覆盖率

功能覆盖率（Functional Coverage）是一种用户定义的度量标准，用于度量验证中已执行的设计规范的比例。功能覆盖率关注的是设计的功能和特性是否被测试用例覆盖到了。

反标是指将功能点与测试用例对应起来。这样，在统计时，就能看到每个功能点对应了哪些测试用例，从而方便查看哪些功能点用的测试用例多，哪些功能点用的测试用例少，有利于后期的测试用例优化。

本项目中相关涉及位置

功能覆盖率需要我们先定义了才能统计，主要是在构建测试环境的时候涉及。

在构建测试环境中：

• 定义功能覆盖率： 创建了功能覆盖率组,添加观察点和反标
• 定义必要 fixture： 把统计结果传递给 toffee-report
• 统计覆盖率： 添加观察点和反标

其他：

• 在 Test case 中使用，可以在每个测试用例里也编写一个功能点。

功能覆盖率使用流程

指定 Group 名称

测试报告通过 Group 名字和 DUT 名字进行匹配，利用 comm.UT_FCOV 获取 DUT 前缀，例如在 Python 模块ut_frontend/ifu/rvc_expander/classical_version/env/rvc_expander_wrapper.py中进行如下调用：

from comm import UT_FCOV
# 本模块名为：ut_frontend.ifu.rvc_expander.classical_version.env.rvc_expander_wrapper
# 通过../../../去掉了classical_version和上级模块env，rvc_expander_wrapper
# UT_FCOV会默认去掉前缀 ut_
g = fc.CovGroup(UT_FCOV("../../../CLASSIC"))
# name = UT_FCOV("../../../CLASSIC")

name 的值为frontend.ifu.rvc_expander.CLASSIC，在最后统计结果时，会按照最长前缀匹配到目标 UT（即匹配到：frontend.ifu.rvc_expander 模块）

创建覆盖率组

使用toffee的funcov可以创建覆盖率组。

import toffee.funcov as fc
# 使用上面指定的GROUP名字
g = fc.CovGroup(name)

这两步也可以合成一句g = fc.CovGroup(UT_FCOV("../../../CLASSIC"))。 创建的g对象就表示了一个功能覆盖率组，可以使用其来提供观察点和反标。

添加观察点和反标

在每个测试用例内部，可以使用add_watch_point（add_cover_point是其别名，二者完全一致）来添加观察点和mark_function来添加反标。 观察点是，当对应的信号触发了我们在观察点内部定义的要求后，这个观察点的名字（也就是功能点）就会被统计到功能覆盖率中。 反标是，将功能点和测试用例进行关联，这样在统计时，就能看到每个功能点对应了哪些测试用例。

对于观察点的位置，需要根据实际情况来定，一般来说，在测试用例外直接添加观察点是没有问题的。 不过有时候我们可以更加的灵活。

1. 在测试用例之外（decode_wrapper.py中）

def init_rvc_expander_funcov(expander, g: fc.CovGroup):
    """Add watch points to the RVCExpander module to collect function coverage information"""
    # 1. Add point RVC_EXPAND_RET to check expander return value:
    #    - bin ERROR. The instruction is not illegal
    #    - bin SUCCE. The instruction is not expanded
    g.add_watch_point(expander, {
                                "ERROR": lambda x: x.stat()["ilegal"] == False,
                                "SUCCE": lambda x: x.stat()["ilegal"] != False,
                          }, name = "RVC_EXPAND_RET")
    # 5. Reverse mark function coverage to the check point
    def _M(name):
        # get the module name
        return module_name_with(name, "../../test_rv_decode")

    #  - mark RVC_EXPAND_RET
    g.mark_function("RVC_EXPAND_RET",_M(["test_rvc_expand_16bit_full",
                                              "test_rvc_expand_32bit_full",
                                              "test_rvc_expand_32bit_randomN"]), bin_name=["ERROR", "SUCCE"])

    # The End                                                                              
    return None 

这个例子的第一个g.add_watch_point是放在测试用例之外的，因为它和现有的测试用例没有直接关系，放在测试用例之外反而更加方便。添加观察点之后，只要add_watch_point方法中的bins条件触发了，我们的toffee-test框架就能够收集到对应的功能点。

2. 在测试用例之中（test_rvc_expander.py中）

N=10
T=1<<32
@pytest.mark.toffee_tags([TAG_LONG_TIME_RUN, TAG_RARELY_USED])
@pytest.mark.parametrize("start,end",
                         [(r*(T//N), (r+1)*(T//N) if r < N-1 else T) for r in range(N)])
def test_rvc_expand_32bit_full(rvc_expander, start, end):
    """Test the RVC expand function with a full 32 bit instruction set

    Description:
        Randomly generate N 32-bit instructions for each check, and repeat the process K times.
    """
    # Add check point: RVC_EXPAND_ALL_32B to check instr bits.
    covered = -1
    g.add_watch_point(rvc_expander, {"RANGE[%d-%d]"%(start, end): lambda _: covered == end},
                      name = "RVC_EXPAND_ALL_32B", dynamic_bin=True)
    # Reverse mark function to the check point
    g.mark_function("RVC_EXPAND_ALL_32B", test_rvc_expand_32bit_full)
    # Drive the expander and check the result
    rvc_expand(rvc_expander, list([_ for _ in range(start, end)]))
    # When go to here, the range[start, end] is covered
    covered = end
    g.sample()

这个例子的观察点在测试用例里面，因为这里的start和end是由pytest.mark.parametrize来决定的，数值不是固定的，所以我们需要在测试用例里面添加观察点。

采样

在上一个例子的最后，我们调用了g.sample()，这个函数的作用是告诉toffee-test，add_watch_point里的bins已经执行过了，判断一下是不是True，是的话就为这个观察点记录一次Pass。

有手动就有自动。我们可以在构建测试环境时，在定义fixture中加入StepRis(lambda x: g.sample()),这样就会在每个时钟周期的上升沿自动采样。

以下内容来自ut_backend/ctrl_block/decode/env/decode_wrapper.py 。

@pytest.fixture()
def decoder(request):
    # before test
    init_rv_decoder_funcov(g)
    func_name = request.node.name
    # If the output directory does not exist, create it
    output_dir_path = get_out_dir("decoder/log")
    os.makedirs(output_dir_path, exist_ok=True)
    decoder = Decode(DUTDecodeStage(
        waveform_filename=get_out_dir("decoder/decode_%s.fst"%func_name),
        coverage_filename=get_out_dir("decoder/decode_%s.dat"%func_name),
    ))
    decoder.dut.InitClock("clock")
    decoder.dut.StepRis(lambda x: g.sample())
    yield decoder
    # after test
    decoder.dut.Finish()
    coverage_file = get_out_dir("decoder/decode_%s.dat"%func_name)
    if not os.path.exists(coverage_file):
        raise FileNotFoundError(f"File not found: {coverage_file}")
    set_line_coverage(request, coverage_file, get_root_dir("scripts/backend_ctrlblock_decode"))
    set_func_coverage(request, g)
    g.clear()

如上面所示，我们在yield之前调用了g.sample()，这样就会在每个时钟周期的上升沿自动采样。

StepRis函数的作用是在每个时钟周期的上升沿执行传入的函数，详情可参照picker使用介绍

5 - 如何参与本项目

如何提交Bug

按 ISSUE 模板进行提交，标记上对应的标签（bug，bug等级等）

对应模块的维护者进行检查，并修改他给出的标记和香山分支

如何提交文档

本仓库文档以PR的形式在本仓库提交，DUT文档在仓库UnityChipForXiangShan/documents/content/zh-cn/docs/98_UT中进行提交。

本项目欢迎任何人以ISSUE、DISCUSS、Fork、PR的方式参与。

万众一芯QQ交流群：

6 - 模板-PR

# Description

Please include a summary of the changes and the related issue. 
Please also include relevant motivation and context. 
List any dependencies that are required for this change.

Fixes # (issue)

## Type of change

Please delete options that are not relevant.

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

# How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. 
Please also list any relevant details for your test configuration

- [ ] Test A
- [x] Test B

**Test Configuration**:
* Firmware version:
* Hardware:
* Toolchain:
* SDK:

# Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream modules

展示效果如下：

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context. List any dependencies that are required for this change.

Fixes # (issue)

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

• Test A
• Test B

Test Configuration:

• Firmware version:
• Hardware:
• Toolchain:
• SDK:

Checklist:

• My code follows the style guidelines of this project
• I have added the appropriate labels
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

7 - 模板-ISSUE

## Description

A brief description of the issue.

## Steps to Reproduce

1. Describe the first step
2. Describe the second step
3. Describe the third step
4. ...

## Expected Result

Describe what you expected to happen.

## Actual Result

Describe what actually happened.

## Screenshots

If applicable, add screenshots to help explain your problem.

## Environment

- OS: [e.g. Windows 10, macOS 10.15, Ubuntu 20.04]
- Browser: [e.g. Chrome 86, Firefox 82, Safari 14]
- Version: [e.g. 1.0.0]

## Additional Information

Add any other context about the problem here.

展示效果如下：

Description

A brief description of the issue.

Steps to Reproduce

1. Describe the first step
2. Describe the second step
3. Describe the third step
4. …

Expected Result

Describe what you expected to happen.

Actual Result

Describe what actually happened.

Screenshots

If applicable, add screenshots to help explain your problem.

Environment

• OS: [e.g. Windows 10, macOS 10.15, Ubuntu 20.04]
• Browser: [e.g. Chrome 86, Firefox 82, Safari 14]
• Version: [e.g. 1.0.0]

Additional Information

Add any other context about the problem here.

Checklist

• I have searched the existing issues
• I have added the appropriate labels
• I have reproduced the issue with the latest version
• I have provided a detailed description of the bug
• I have provided steps to reproduce the issue
• I have included screenshots (if applicable)
• I have provided the environment details (OS, version, etc.)

8 - 模板-UT-README

# 模块名称

## 测试目标

<测试目标、测试方法描述>


## 测试环境

<测试环境描述，依赖描述>

## 功能检测

<给出目标待测功能与对应的检测方法>

|序号|所属模块|功能描述|检查点描述|检查标识|检查项|
|-|-|-|-|-|-|
|-|-|-|-|-|-|


## 验证接口

<接口的描述>


## 用例说明

#### 测试用例1

|步骤|操作内容|预期结果|覆盖功能点|
|-|-|-|-|
|-|-|-|-|

#### 测试用例2

|步骤|操作内容|预期结果|覆盖功能点|
|-|-|-|-|
|-|-|-|-|


## 目录结构

<对本模块的目录结构进行描述>


## 检测列表


- [ ] 本文档符合指定[模板]()要求
- [ ] Env提供的API不包含任何DUT引脚和时序信息
- [ ] Env的API保持稳定（共有[ X ]个）
- [ ] Env中对所支持的RTL版本（支持版本[ X ]）进行了检查
- [ ] 功能点（共有[ X ]个）与[设计文档]()一致
- [ ] 检查点（共有[ X ]个）覆盖所有功能点
- [ ] 检查点的输入不依赖任何DUT引脚，仅依赖Env的标准API
- [ ] 所有测试用例（共有[ X ]个）都对功能检查点进行了反标
- [ ] 所有测试用例都是通过 assert 进行的结果判断
- [ ] 所有DUT或对应wrapper都是通过fixture创建
- [ ] 在上述fixture中对RTL版本进行了检查
- [ ] 创建DUT或对应wrapper的fixture进行了功能和代码行覆盖率统计
- [ ] 设置代码行覆盖率时对过滤需求进行了检查

展示效果如下：

模块名称

测试目标

<测试目标、测试方法描述>

测试环境

<测试环境描述，依赖描述>

功能检测

<给出目标待测功能与对应的检测方法>

验证接口

<接口的描述>

用例说明

测试用例1

测试用例2

目录结构

<对本模块的目录结构进行描述>

检测列表

• 本文档符合指定模板要求
• Env提供的API不包含任何DUT引脚和时序信息
• Env的API保持稳定（共有[ X ]个）
• Env中对所支持的RTL版本（支持版本[ X ]）进行了检查
• 功能点（共有[ X ]个）与设计文档一致
• 检查点（共有[ X ]个）覆盖所有功能点
• 检查点的输入不依赖任何DUT引脚，仅依赖Env的标准API
• 所有测试用例（共有[ X ]个）都对功能检查点进行了反标
• 所有测试用例都是通过 assert 进行的结果判断
• 所有DUT或对应wrapper都是通过fixture创建
• 在上述fixture中对RTL版本进行了检查
• 创建DUT或对应wrapper的fixture进行了功能和代码行覆盖率统计
• 设置代码行覆盖率时对过滤需求进行了检查

9 - 常用API

comm 模块

在comm中提供了部分可公用的API，可通过以下方式进行调用：

# import all
from comm import *
# or direct import functions you need
from com import function_you_need
# or access from module
import comm
comm.function_you_need()

cfg 子模块

get_config(cfg=None)

获取当前的Config配置

• 输入：如果cfg不为空，则返回cfg。否则则自动通过toffee获取全局Config。
• 返回：Config对象

import comm
cfg = comm.get_config()
print(cfg.rtl.version)

cfg_as_str(cfg: CfgObject):

把config对象转换为字符类型

• 输入：Config对象
• 返回：编码后的Config对象

import comm
cfg_str = comm.cfg_as_str(comm.get_config())

cfg_from_str(cfg_str)

把字符类型的Config对象还原

• 输入：编码后的Config对象
• 返回：Config对象

import comm
cfg = comm.cfg_from_str(cfg_str)

dump_cfg(cfg: CfgObject = None, cfg_file=None)

把config对象保持到文件

• 输入：
  • cfg 需要保存的config
  • cfg_file 目标文件

import comm
cfg = comm.get_config()
comm.dump_cfg(cfg, "config.yaml")

functions 子模块

get_log_dir(subdir="", cfg=None)

获取日志目录

• 输入：
  • subdir： 子目录
  • cfg：配置文件
• 输出：日志目录

import comm
my_log = comm.get_log_dir("my_log")
print(my_log) # /workspace/UnityChipForXiangShan/out/log/my_log

get_out_dir(subdir="", cfg=None)

获取输出目录

• 输入：
  • subdir： 子目录
  • cfg：配置文件
• 输出：输出目录

get_rtl_dir(subdir="", cfg=None)

获取RTL目录

• 输入：
  • subdir： 子目录
  • cfg：配置文件
• 输出：RTL目录

get_root_dir(subdir="")

获取根目录：

• 输入：根目录下的子目录
• 输出：当前仓库的根目录

is_all_file_exist(files_to_check, dir)

判断文件是否在指定目录中都存在

• 输入：
  • files_to_check: 需要检查的文件列表
  • dir：目标目录
• 输出：是否都存在，只要有一个文件不存在都返回False

time_format(seconds=None, fmt="%Y%m%d-%H%M%S")

格式化时间

• 输入：
  • seconds：需要格式化的时间，为None表示当前时间
  • fmt：时间格式
• 返回：格式化之后的时间字符串

import comm
import time
print(time_format(time.time())) # 20241202-083726

base64_encode(input_str)

base64编码：

• 输入：需要编码的字符串
• 输出：编码之后的字符串

import comm
print(comm.base64_encode("test")) # dGVzdA==

base64_decode(base64_str)

base64解码：

• 输入：bas64编码
• 输出：解码之后的原始字符串

import comm
print(comm.base64_decode("dGVzdA==")) # test

exe_cmd(cmd, no_log=False)

执行操作系统命令：

• 输入：
  • cmd：需要执行的os命令
  • 是否需要返回命令行输出
• 输出：success，stdout、sterr
  • sucess：命令是否执行成功
  • 命令标准输出字符串（no_log=True时，强制为空）
  • 命令标准错误字符串（no_log=True时，强制为空）

import comm
su, st, er = exe_cmd("pwd")
print(st)

get_git_commit()

获取当前仓库git commit号

get_git_branch()

获取当前仓库git 分支名称

UT_FCOV(group, ignore_prefix=“ut_”)

获取功能覆盖率分组

• 输入：
  • group 分组名称
  • ignore_prefix需要去掉的前缀
• 输出：带模块前缀的覆盖率分组名

例如，在ut_backend/ctrl_block/decode/env/decode_wrapper.py中调用：

print(UT_FCOV("../../INT"))
# out
backend.ctrl_block.decode.INT

get_version_checker(target_version)

获取版本检测函数

• 输入：目标版本字符串
• 输出：检测函数

返回的检测函数，一般在fixture中进行版本判断。

import comm
import pytest

checker = comm.get_version_checker("openxiangshan-kmh-24092701+")

@pytest.fixture
def fixture():
  checker()
  ...

module_name_with(names, prefix=None)

给names统一加上模块前缀

• 输入：
  • nanmes 需要添加前缀的字符列表
  • prefix 模块前缀
• 返回：添加完成后的字符串列表

例如在a/b/c/d/e.py文件中调用该方法：

import comm
print(comm.module_name_with(["X", "Y"], ,"../../x"))
# out
["a.b.c.x.X", "a.b.c.x.Y"]

get_all_rtl_files(top_module, cfg)

获取名称为 top_module 的模块所依赖的所有 RTL 文件（.v 或 .sv）的列表，并确保列表的第一个元素是 top_module 所在文件的绝对路径。所有 RTL 文件均位于 UnityChipForXiangShan/rtl/rtl 目录下。

• 输入：

  • top_module：模块名称，类型为 str。
  • cfg：配置信息，类型为 CfgObject。

• 输出：

  • 返回一个包含字符串的列表，列表中的每个字符串为模块依赖的 RTL 文件的绝对路径。列表的第一个元素为 top_module 所在文件的路径。

假设 top_module 为 "ALU"，且其依赖的 RTL 文件包括 ALU.sv、adder.v 和 multiplier.v：

paths = get_all_rtl_files("ALU", cfg)

"""
paths可能的内容：
[
    "/path/to/UnityChipForXiangShan/rtl/rtl/ALU.sv",
    "/path/to/UnityChipForXiangShan/rtl/rtl/adder.v",
    "/path/to/UnityChipForXiangShan/rtl/rtl/multiplier.v"
]
"""

10 - 其他

测试用例管理

如果测试用例和目标RTL版本紧密相关，RTL发生变化，之前的测试用例不一定适用。此外，不同场景下有不同需求，例如验证测试环境时，不运行耗时太长的用例等。因此需要对用例进行管理，让用户能在在特定场景下跳过某些用例。为了实现该目标，我们需要通过pytest.mark.toffee_tags对于每个用例进行tag和version标记。然后在配置文件中设置需要跳过哪些tag或者只运行哪些tag的测试。

@pytest.mark.toffee_tags("my_tag", "version1 < version13")
def test_case_1():
    ...

例如上述test_case_1被标记上了标签my_tag，支持版本设置为version1到version13。因此可以在配置文件中指定test.skip-tags=["my_tag"]，来表示运行过程中跳过该用例。

pytest.mark.toffee_tags的参数说明如下：

@pytest.mark.toffee_tags(
    tag: Optional[list, str]     = []    # 用例标签
    version: Optional[list, str] = [],   # 用例rtl版本需求
    skip: callable               = None, # 自定义是否调过该用例，skip(tag, version, item): (skip, reason)
)

toffee_tags函数的参数tag支持str和list[str]类型。version参数也可以是str和list[str]类型，当为list类型时，进行精确匹配，如果为str则匹配规则如下：

1. name-number1 < namer-number2: 表示版本需要在number1和number2之间（包含边界，number表示数字，也可以为小数，eg 1.11）
2. name-number1+：表示number1版本以及以后的版本
3. name-number1-：表示number1版本以及以前的版本

如果不存在上述情况，且有*或者?表示通配符类型。其他情况为精确匹配。

预定义标签，可以在comm/constants.py中查看，例如：

# Predefined tags for test cases
TAG_LONG_TIME_RUN = "LONG_TIME_RUN"  # 运行时间长
TAG_SMOKE         = "SMOKE"          # 冒烟测试
TAG_RARELY_USED   = "RARELY_USED"    # 非常少用
TAG_REGRESSION    = "REGRESSION"     # 回归测试
TAG_PERFORMANCE   = "PERFORMANCE"    # 性能测试
TAG_STABILITY     = "STABILITY"      # 稳定测试
TAG_SECURITY      = "SECURITY"       # 安全测试
TAG_COMPATIBILITY = "COMPATIBILITY"  # 兼容测试
TAG_OTHER         = "OTHER"          # 其他
TAG_CI            = "CI"             # 集成测试
TAG_DEBUG         = "DEBUG"          # 测试
TAG_DEMO          = "DEMO"           # demo

在默认配置中(config/_default.yaml)，会过滤掉：LONG_TIME_RUN、REGRESSION、RARELY_USED、CI 标记的测试。

可以通过@pytest.mark.toffee_tags可以为每个用例添加标签，也可以在模块中定义如下变量，实现对整个模块的所有测试用例添加标签。

toffee_tags_default_tag     = []   # 对应 tag 参数
toffee_tags_default_version = []   # 对应 version 参数
toffee_tags_default_skip    = None # 对应 skip 参数

*注：本环境中的版本号会自动过滤掉git标记，例如下载的RTL名称为openxiangshan-kmh-97e37a2237-24092701.tar.gz，则其版本号在本项目中为：openxiangshan-kmh-24092701, 可通过cfg.rtl.version或者comm.get_config().rtl.version获得。

版本检查

除了可以用标签toffee_tags自动检查版本外，还可以通过get_version_checker主动进行检查。一个单元测试通常由测试环境（Test Env）和测试用例组成（Test Case），Env对RTL引脚和功能进行封装，然后向Case提供稳定API，因此在Env中需要进行RTL版本判断，判断是否需要跳过使用本环境的所有测试用例。例如在Env中：

...
from comm import get_version_checker

version_check = get_version_checker("openxiangshan-kmh-*") # 获取RTL版本检查器，同toffee_tags中的veriosn参数

@pytest.fixture()
def my_fixture(request):
    version_check()                                        # 在 fixture 中主动检查
    ....
    yield dut
    ...

在上述例子中，Env在名称为my_fixture的fixture中主动进行了版本检查。因此，在测试用例每次调用它时都会进行版本检查，如果检查不满足要求，则会跳过该用例的执行。

仓库目录说明

UnityChipForXiangShan
├── LICENSE            # 开源协议
├── Makefile           # Makefile主文件
├── README.en.md       # 英文readme
├── README.zh.md       # 中文readme
├── __init__.py        # Python模块文件，可以把整个UnityChipForXiangShan当成一个模块进行import
├── pytest.ini         # PyTest 配置文件
├── comm               # 公用组件：日志，函数，配置等
├── configs            # 配置文件目录
├── documents          # 文档
├── dut                # dut生成目录
├── out                # log，report等生成目录
├── requirements.txt   # python依赖
├── rtl                # rtl缓存
├── run.py             # 主python入口文件
├── scripts            # dut编译脚本
├── tools              # 公共工具模块
├── ut_backend         # 后端测试用例
├── ut_frontend        # 前端测试用例
├── ut_mem_block       # 访存测试用例
└── ut_misc            # 其他测试用例

配置文件说明

默认配置与说明如下：

# 默认配置文件
# 配置加载顺序: _default.yaml -> 用户指定的 *.yaml -> 命令行参数 eg: log.term-level='debug'
# RTL 配置
rtl:
  # RLT下载地址，从该地址获取所有*.gz.tar文件当成目标RTL
  base-url: https://<your_rtl_download_address>
  # 需要下载的RTL版本 eg: openxiangshan-kmh-97e37a2237-24092701
  version: latest
  # 需要存储RTL的目录，相对于当前配置文件的路径
  cache-dir: "../rtl"
# 测试用例配置（tag和case支持通配符）
test:
  # 跳过标签，所有带有该标签的测试用例都会被跳过
  skip-tags: ["LONG_TIME_RUN", "RARELY_USED", "REGRESSION", "CI"]
  # 目标标签，只有带有该标签的测试用例才会被执行（skip-tags会覆盖run-tags）
  run-tags: []
  # 跳过的测试用例，所有带有该名字（或者模块名）的测试用例都会被跳过。
  skip-cases: []
  # 目标测试用例，只有带有该名字（或者模块名）的测试用例才会被执行（skip-cases会覆盖run-cases）。
  run-cases: []
  # 跳过异常，所有抛出该异常的测试用例都会被跳过
  skip-exceptions: []
# 输出配置
output:
  # 输出目录，相对于当前配置文件的路径
  out-dir: "../out"
# 测试报告配置
report:
  # 报告生成目录，相对于output.out-dir
  report-dir: "report"
  # 报告名称，支持变量替换：%{host} 主机名，%{pid} 进程ID，%{time} 当前时间
  report-name: "%{host}-%{pid}-%{time}/index.html"
  # 报告内容
  information:
    # 报告标题
    title: "XiangShan KMH Test Report"
    # 报告用户信息
    user:
      name: "User"
      email: "User@example.email.com"
    # 目标行覆盖率 eg: 90 表示 90%
    line_grate: 99
    # 其他需要展示的信息，key为标题，value为内容
    meta:
      Version: "1.0"
# 日志配置
log:
  # 根输出级别
  root-level: "debug"
  # 终端输出级别
  term-level: "info"
  # 文件日志输出级别
  file-dir: "log"
  # 文件日志名称，支持变量替换：%{host} 主机名，%{pid} 进程ID，%{time} 当前时间
  file-name: "%{host}-%{pid}-%{time}.log"
  # 文件日志输出级别
  file-level: "info"
# 测试结果配置（该数据用于填充documents中的统计图等，原始数据来源于toffee-test生成的report）
#  运行完测试后，可通过 `make doc` 查看结果
doc-result:
  # 是否开测试结果后处理
  disable: False
  # 目标DUT的组织结构配置
  dutree: "%{root}/configs/dutree/xiangshan-kmh.yaml"
  # 结果名称，将会保存到输出的report目录
  result-name: "ut_data_progress.json"
  # 创建的测试报告的软连接到 hugo
  report-link: "%{root}/documents/static/data/reports"

可在上述配置文件中添加自定义参数，通过cfg = comm.get_config()获取全局配置信息，然后通过cfg.your_key进行访问。cfg信息为只读信息，默认情况下不能进行修改。

11 - 必要规范

为了方便将所有人的贡献集合在一起，需要在编码、环境、文档编写等方面采用相同的“规范”。

环境要求

• python： 在python编码过程中，尽可能的采用标准库，采用兼容Python3大部分版本的通用语法（尽可能的在Python3.6 - Python3.12中通用），不要使用过旧或者过新的语法。
• 操作系统： 建议Ubuntu 22.04，windows下，建议使用WSL2环境。
• hugo 建议版本 0.124.1（版本过旧不支持软连接）
• 少依赖 尽可能少的使用第三方C++/C库
• picker 建议使用wheel安装picker工具和xspcomm库

测试用例

• 代码风格 建议采用 PEP 8 规范
• build脚本 需要按DUT的命名结构进行规范命名，不然无法正确收集验证结果。例如backend.ctrl_block.decodeUT在scripts目录中对应的build文件名称应该为build_ut_backend_ctrl_block_decode.py(以固定前缀build_ut_开始，点.用下划线_进行替换)。在脚本中实现 build(cfg) -> bool 和 line_coverage_files(cfg) -> list[str] 方法。build用于编译DUT为python模块，line_coverage_files方法用于返回需要统计的代码行覆盖率文件。
• 用例标签 如果用例无法做到版本通用，需要用pytest.mark.toffee_tags标记支持的版本。
• 用例抽象 编写的测试用例输入不能出现DUT的具体引脚等强耦合内容，只能调用基于DUT之上的函数封装。例如对于加法器 adder，需要把dut的目标功能封装为 dut_wrapper.add(a: int, b: int) -> int, bool，在test_case中仅仅调用 sum, c = add(a, b)进行测试。
• 覆盖抽象 在编写功能覆盖率时，其检查点函数的输入也不能有DUT引脚。
• 环境抽象 对于一个验证，通常分为2部分：Test Case 和 Env （用例以外的都统一称为Env，它包含DUT、驱动、监控等），其中Env需要提供对外的功能抽象接口，不能对外呈现出太多细节。
• 测试说明 在每个DUT的验证环境中，需要通过README.md对该环境进行说明，例如需要对Env提供给Case的接口进行说明，目录结构说明等。

PR编写

• 标题 简洁明了，能概括PR的主要内容。
• 详细描述 详细说明PR的目的，修改的内容以及相关背景信息。入解决已有的问题需要给出链接（例如Issue）。
• 关联问题 在描述中关联相关问题，例如 Fixes #123，以便在合并PR时关闭关联问题。
• 测试 需要进行测试，并对测试结果进行描述
• 文档 PR涉及到的文档需要同步修改
• 分解 当PR涉及到的修改很多时，需要判断是否拆分成多个PR
• 检查清单 检查编译是否通过、代码风格是否合理、是否测试通过、是否有必要的注释等
• 模板 以及提供的PR模块请参考链接。

ISSUE编写

要求同上

12 - 验证文档

12.1 - 验证文档规范

万众一芯验证文档格式规范

验证文档标题请用一号标题格式（一个#），以加法器验证文档为例，其标题可以为：进位加法器设计与验证。

文档概述

文档概述标题请用二号标题格式（两个#）。

【必填项】 在该部分对整个文档进行简约描述，例如内容概述，待验证模块的基本功能、特殊需求、特定规格、目标读者、知识前置等。目的是通过对该部分，读者便了解是否具有其感兴趣的内容。例如本文档是对验证文档的编写要求进行描述，便于多文档协作，规范验证的数据输入，特定数据标签等。

术语说明

术语说明标题请用二号标题格式（两个#）。

【必填项】 该部分需要列出术语和关键概念解释，方便读者参考。

1. 优先解释模块专有缩写（如TLB， FIFO等），且用缩写（全名）的格式填写在“名称”一栏中。
2. 对容易混淆的概念请务必明确（如虚拟地址和物理地址等）
3. 示例格式如下：

如果有其他补充情况请在此说明，例如：上述命名描述仅针对香山处理器，不代表RISC-V标准或者其他处理器。

前置知识

前置知识标题请用二号标题格式（两个#）。

【可选项】 在阅读文档或进行验证之前，建议掌握一些关键前置知识，以便更深入理解相关内容。例如，在撰写LoadStoreQueue（LSQ）文档时，讲述RAW（Read After Write）违例有助于理解操作之间的依赖关系。在撰写Icache或L2Cache文档时，介绍缓存层级、替换策略和一致性模型等基本概念也有助于读者理解。如果涉及复杂算法，也应对其进行简要描述。

基本要求：

1. 该部分内容应简洁，易于理解。如篇幅较长，可将内容移至附录。
2. 针对较为复杂的内容，可以通过图像、伪代码和案例进行解释，以降低理解难度。

下面是一个举例：

st-ld违例

在现代处理器中，Load 和 Store 指令通常采用乱序执行的方式进行处理。这种执行策略旨在提高处理器的并行性和整体性能。然而，由于 Load 和 Store 指令在流水线中的乱序执行，常常会出现 Load 指令越过更早的相同地址的 Store 指令的情况。这意味着，Load 指令本应通过前递（forwarding）机制从 Store 指令获取数据，但由于 Store 指令的地址或数据尚未准备好，导致 Load 指令未能成功前递到 Store 的数据，而 Store 指令已被提交。由此，后续依赖于该 Load 指令结果的指令可能会出现错误，这就是 st-ld 违例。

考虑以下伪代码示例：

ST R1, 0(R2)  ; 将 R1 的值存储到 R2 指向的内存地址
LD R3, 0(R2)  ; 从 R2 指向的内存地址加载值到 R3
ADD R4, R3, R5 ; 使用 R3 的值进行计算

假设在这个过程中，Store 指令由于某种原因（如缓存未命中）未能及时完成，而 Load 指令已经执行并读取了旧的数据（例如，从内存中读取到的值为 0）。此时，Load 指令并未获得 Store 指令更新后的值，导致后续计算的数据错误。

通过上述例子，可以清楚地看到 Store-to-Load 违例如何在乱序执行的环境中导致数据一致性问题。这种问题强调了在指令调度和执行过程中，确保正确的数据流动的重要性。现代处理器通过多种机制来检测和解决这种违例，以维护程序的正确性和稳定性。

整体框图

整体框图标题请用二号标题格式（两个#）。

【可选项】 该部分为可选章节，若模块含多个子模块或复杂数据流，需提供框图辅助说明，便于读者理解。

基本要求：

1. 图必须清晰，最好为矢量图，可使用Visio/Draw.io等工具绘制，导出为PNG/SVG格式；
2. 图中需标注关键信号流向；
3. 框图中子模块命名需与“子模块列表”章节严格一致；
4. 图像和图表标题的位置需要居中；
5. 如果有多个图表，图表题目需要添加相应标号，如图1、图2等；

示例：

示例图1：IFU 整体框图

流水级示意图

流水级示意图标题请用二号标题格式（两个#）。

【可选项】 若为流水线型模块，需说明各级流水功能与时序关系。

编写要求：

1. 图必须清晰，最好为矢量图，可使用Visio/Draw.io等工具绘制，导出为PNG/SVG格式；
2. 涉及到的模块名称需要与上下文保持一致；
3. 重要信号除了列出信号名称以外，还需要标明位宽等信息；
4. 图像和图表标题的位置需要居中；
5. 如果有多个图表，图表题目需要添加相应标号，如图1、图2等。

示例：

示例图2：LSU-LoadUnit 流水线架构图

子模块列表

子模块列表标题请用二号标题格式（两个#）。

【可选项】 如果一个模块由多个子模块组成，则需要在此处列出所有相关的子模块，并进行简要说明。这有助于清晰地展示模块的结构和功能，便于读者理解各个子模块之间的关系及其在整体系统中的作用。

以下是IFU top文档中的一个示例：

模块功能说明

模块功能说明标题请用二号标题格式（两个#）。

【必填项】 需采用功能树形式逐级分解DUT的各项功能，并对所有功能进行描述，确保每个功能点都对应相应的测试点。这种结构化的方法不仅有助于全面覆盖所有功能，还便于后续文档的维护和更新。

编写规则：

1. 请使用 <mrs-functions>``</mrs-functions> 标签包裹整个“模块功能说明”部分；
2. 采用 X.Y.Z 多级编号（如 1.2.3 表示主功能 1 → 子功能 2 → 测试点 3，且可进一步细分）；
3. 多级编号的标题格式按照级别增加，例如：“1. 读FIFO操作”应为三号标题格式 “1.1. 常规读取”应为四号标题格式；
4. 功能描述应清晰列出输入条件、处理过程和输出结果。
5. 针对每个功能进行测试点分解，应详细列出每个测试点，明确其目的和预期结果。
6. 如果测试点较多可以先列一个小表格。

具体来说，可以按照如下的格式写作（示例内容仅供参考，并不代表实际逻辑或内容）：

常量说明

常量说明标题请用二号标题格式（两个#）。

【可选项】 需要列出模块中所有可配置参数及其物理意义，以便于用户理解各参数的作用和影响。

示例：

接口说明

接口说明标题请用二号标题格式（两个#）。

【必填项】 详细解释各种接口的含义和来源，包括接口的功能、用途。这有助于用户理解各接口的工作原理和应用场景，从而更有效地使用这些接口。

编写规则

1. 信号按功能（如时钟复位、数据输入、控制信号等）或来源（其他模块）分组；
2. 可以将一些同质的信号一起解释；
3. 特殊协议信号需注明时序要求（如AXI的VALID/READY握手）。

接口时序

接口时序标题请用二号标题格式（两个#）。

【可选项】 针对复杂接口，可以提供波形图案例，以直观展示信号变化和时间关系。

以下是节选自IFU top文档的一个例子：

接口时序

FTQ 请求接口时序示例

上图示意了三个 FTQ 请求的示例，req1 只请求缓存行 line0，紧接着 req2 请求 line1 和 line2，当到 req3 时，由于指令缓存 SRAM 写优先，此时指令缓存的读请求 ready 被指低，req3 请求的 valid 和地址保持直到请求被接收。

ICache 返回接口以及到 Ibuffer 和写回 FTQ 接口时序示例

上图展示了指令缓存返回数据到 IFU 发现误预测直到 FTQ 发送正确地址的时序，group0 对应的请求在 f2 阶段了两个缓存行 line0 和 line1，下一拍 IFU 做误预测检查并同时把指令给 Ibuffer，但此时后端流水线阻塞导致 Ibuffer 满，Ibuffer 接收端的 ready 置低，goup0 相关信号保持直到请求被 Ibuffer 接收。但是 IFU 到 FTQ 的写回在 tio_toIbuffer_valid 有效的下一拍就拉高，因为此时请求已经无阻塞地进入 wb 阶段，这个阶段锁存的了 PredChecker 的检查结果，报告 group0 第 4（从 0 开始）个 2 字节位置对应的指令发生了错误预测，应该重定向到 vaddrA，之后经过 4 拍（冲刷和重新走预测器流水线），FTQ 重新发送给 IFU 以 vaddrA 为起始地址的预测块。

测试点总表

测试点总表标题请用二号标题格式（两个#）。

【必填项】 对模块功能说明中细分的测试点进行综合整理，采用表格形式列出，便于用户快速查阅和理解。

表格规范：

1. 请用<mrs-testpoints></mrs-testpoints>标签包裹测试点总表，方便我们后续使用脚本提取测试点
2. 表格共列四项，序号，功能名称，测试点名称和解释
   1. 序号：测试点的序号格式和功能点类似。即，即测试点1.2.3.4 可能是功能点1.2.3的第4个测试点
   2. 功能名称：用英文大写命名，可用下划线分割单词，可以使用markdown语法为功能名称添加到具体功能点解释的链接，即形如[文本](跳转目标)
   3. 测试点名称：用英文大写命名，可用下划线分割单词
   4. 解释：简单描述测试点所需的输入和输出需求，明确判断条件

表格示例：

以下是节选自IFU top文档的一个例子:

附录

附录标题请用二号标题格式（两个#）。

【可选项】 此部分用于存放正文的补充内容，以便进行扩展和详细说明，旨在使文档格式更加清晰，排版更加合理。

以下是节选自IFU RVCExpander文档的一个例子:

RVC扩展辅助阅读材料

为方便参考模型的书写，在这里根据20240411版本的手册内容整理了部分指令扩展的思路。

对于RVC指令来说，op = instr(1, 0)；funct = instr(15, 13)

在开始阅读各指令的扩展规则时，需要了解一些RVC扩展的前置知识，比如：

rd’, rs1’和rs2’寄存器：受限于16位指令的位宽限制，这几个寄存器只有3位来表示，他们对应到x8~x15寄存器。

op = b'00'

funct = b'000’: ADDI4SPN

该指令将一个0扩展的非0立即数加到栈指针寄存器x2上，并将结果写入rd'

其中，nzuimm[5:4|9:6|2|3]的含义是： ···

下方展示了模板和两个验证案例：

12.1.1 - 文档模板

以下是一份验证文档的完整模板（请一定同提交的验证报告区分开来）

# 验证文档各部分说明

## 文档概述【必填项】 

在该部分对整个文档进行简约描述，例如内容概述，待验证模块的基本功能、特殊需求、特定规格、目标读者、知识前置等。目的是通过对该部分，读者便了解是否具有其感兴趣的内容。例如本文档是对验证文档的编写要求进行描述，便于多文档协作，规范验证的数据输入，特定数据标签等。

## 术语说明 【必填项】 列出术语和关键概念解释，方便读者参考

优先解释模块专有缩写（如TLB， FIFO等），如果有缩写，请用`缩写（全称）的方式填在表格的“名称”栏目中`

对容易混淆的概念请务必明确（如虚拟地址和物理地址等）

| 名称 | 定义 |
| ------- | ---|
| 缩写1（FULL_NAME_1）	| 描述1 |
| 缩写2（FULL_NAME_2）	| 描述2 |
| 概念名1	| 描述3 |

## 前置知识【可选项】

在阅读文档或进行验证之前，建议掌握一些关键前置知识，以便更深入理解相关内容。例如，在撰写LoadStoreQueue（LSQ）文档时，讲述RAW（Read After Write）违例有助于理解操作之间的依赖关系。在撰写Icache或L2Cache文档时，介绍缓存层级、替换策略和一致性模型等基本概念也有助于读者理解。如果涉及复杂算法，也应对其进行简要描述。

基本要求：
1. 该部分内容应简洁，易于理解。如篇幅较长，可将内容移至附录。
2. 针对较为复杂的内容，可以通过图像、伪代码和案例进行解释，以降低理解难度。


## 整体框图 【可选项】 若模块含多个子模块或复杂数据流，需提供框图辅助说明

可使用Visio/Draw.io等工具绘制，导出为PNG/SVG格式；
需标注关键信号流向；
框图中子模块命名需与“子模块列表”章节严格一致。

## 流水级示意图 【可选项】 若为复杂流水线型模块，需说明各级流水功能与时序关系

可使用Visio/Draw.io等工具绘制，导出为PNG/SVG格式；
涉及到的模块名称需要保持一致性
重要数据除了列出名称以外，还需要标明位宽等信息

## 子模块列表 【可选项】 若模块由多个子模块组成，需在此列出

以下是IFU top文档中的一个示例：

| 子模块                 | 描述                |
| ---------------------- | ------------------- |
| [子模块1](子模块1文档位置) | 子模块1描述       |
| [子模块2](子模块2文档位置) | 子模块2描述       |
| [子模块3](子模块3文档位置) | 子模块3描述       |


<mrs-functions>

## 模块功能说明 【必填项】 需按功能树形式逐级分解，每个功能点需对应后续测试点。

请用<mrs-functions></functions>包裹整个“模块功能说明”部分。

采用X.Y.Z多级编号（如1.2.3表示主功能1→子功能2→测试点3，也可以继续细分）

功能描述需明确输入条件、处理过程、输出结果

### 1. 功能A说明
针对功能A分解测试点

如果测试点较多可以先列一个小表格

### 2. 功能B说明

针对功能B分解测试点

如果测试点较多可以先列一个小表格

### 3. 功能C说明

针对功能C分解测试点

如果测试点较多可以先列一个小表格；针对每个测试点，给出设置cov_group的建议

</mrs-functions>


## 常量说明 【可选项】 需列出模块中所有可配置参数及其物理意义


| 常量名 | 常量值 | 解释 |
| ---- | ---- | ---- |
| 常量1 | 64 | 常量1解释 |
| 常量2 | 8 | 常量2解释 |
| 常量3 | 16 | 常量3解释 |


## 接口说明 【必填项】 详细解释各种接口的含义、来源

信号按功能（如时钟复位、数据输入、控制信号等）或来源（其他模块）分组；

可以将一些同质的信号一起解释；

特殊协议信号需注明时序要求（如AXI的VALID/READY握手）。

使用时，请将下面的接口组名称和说明替换为符合您模块实际意义的内容

### 接口组1说明

请在这里填充接口组1的说明

#### 接口组1_1说明

请在这里填充接口组1_1的说明

如果不能细分，请进一步说明该组中所有接口

### 接口组2说明

请在这里填充接口组2的说明

如果不能细分，请进一步说明该组中所有接口

...

## 接口时序 【可选项】 对复杂接口，提供波形图的案例

### 案例1

请在这里填充时序案例1

### 案例2

请在这里填充时序案例2

## 测试点总表 (【必填项】针对细分的测试点，列出表格)

实际使用下面的表格时，请用有意义的英文大写的功能名称和测试点名称替换下面表格中的名称

<mrs-testpoints>

| 序号 |  功能名称 | 测试点名称      | 描述                  |
| ----- |-----------------|---------------------|------------------------------------|
| 1\.1\.1 | FUNCTION_1_1 | TESTPOINT_A | 功能1\.1的测试点A，使用时请替换为您的测试点的输入输出和判断方法 | 
| 1\.1\.2 | FUNCTION_1_1 | TESTPOINT_B | 功能1\.1的测试点B，使用时请替换为您的测试点的输入输出和判断方法 | 
| 1\.1\.3 | FUNCTION_1_1 | TESTPOINT_C | 功能1\.1的测试点C，使用时请替换为您的测试点的输入输出和判断方法 | 
| 1\.2\.1 | FUNCTION_1_2 | TESTPOINT_X | 功能1\.2的测试点X，使用时请替换为您的测试点的输入输出和判断方法 | 
| 1\.2\.2 | FUNCTION_1_2 | TESTPOINT_Y | 功能1\.2的测试点Y，使用时请替换为您的测试点的输入输出和判断方法 | 
| 2\.1 | FUNCTION_2 | TESTPOINT_2A | 功能2的测试点2A，使用时请替换为您的测试点的输入输出和判断方法 | 
| 2\.2 | FUNCTION_2 | TESTPOINT_2B | 功能2的测试点2B，使用时请替换为您的测试点的输入输出和判断方法 | 

</mrs-testpoints>

## 附录【可选项】 

此部分用于存放正文的补充内容，以便进行扩展和详细说明，旨在使文档格式更加清晰，排版更加合理。

12.1.2 - FIFO文档案例

以下以FIFO为例，展示了一个简单的文档案例

`timescale 1ns / 1ps
module FIFO ( //data_width = 8  data depth =8
  input clk,
  input rst_n,
  input wr_en,          //写使能
  input rd_en,          //读使能
  input [7:0]wdata,     //写入数据输入
  output [7:0]rdata,    //读取数据输出
  output empty,         //读空标志信号
  output full           //写满标志信号
);
  reg [7:0] rdata_reg = 8'd0;
  assign rdata = rdata_reg;

  reg  [7:0] data [7:0];     //数据存储单元(8bit数据8个)
  reg  [3:0] wr_ptr = 4'd0;  //写指针
  reg  [3:0] rd_ptr = 4'd0;  //读指针
  wire [2:0] wr_addr;        //写地址(写指针的低3位)
  wire [2:0] rd_addr;        //读地址(读指针的低3位)

assign wr_addr = wr_ptr[2:0];
assign rd_addr = rd_ptr[2:0];

always@(posedge clk or negedge rst_n)begin //写数据
  if(!rst_n) 
    wr_ptr <= 4'd0;
  else if(wr_en && !full)begin
    data[wr_addr]  <= wdata;
    wr_ptr <= wr_ptr + 4'd1;
  end
end

always@(posedge clk or negedge rst_n)begin //读数据
  if(!rst_n)
    rd_ptr <= 'd0;
  else if(rd_en && !empty)begin
    rdata_reg  <= data[rd_addr];
    rd_ptr <= rd_ptr + 4'd1;
  end
end

assign empty = (wr_ptr == rd_ptr); //读空
assign full  = (wr_ptr == {~rd_ptr[3],rd_ptr[2:0]}); //写满

endmodule

FIFO 模块验证文档

文档概述

本文档描述FIFO的功能，并根据功能给出测试点参考，方便测试的参与者理解测试需求，编写相关测试用例。

术语说明

功能说明

本次需要验证的是FIFO，一种常见的硬件缓冲模块，在硬件电路中临时存储数据，并按照数据到达的顺序进行处理。

本次需要验证的FIFO每次可写可读8位数据，容量为8。

1. 读FIFO操作

1.1. 常规读取

功能描述：当rd_en=1且empty=0时，在时钟上升沿输出rdata

建议观测点：

• 读指针递增逻辑
• rdata与预期数据匹配

1.2. 读空栈

功能描述：当empty=1且rd_en=1时，rdata保持无效值

建议观测点：

• empty信号持续为高
• 读指针无变化

1.3. 无读使能不读

功能描述：当rd_en=0时，无论FIFO状态如何均不更新rdata

建议观测点：

• 连续写入后关闭读使能，验证读指针冻结

2. 写FIFO操作

2.1. 常规写入

功能描述：当wr_en=1且full=0时，在时钟上升沿存储wdata

观测点：

• 写指针递增逻辑
• 存储阵列数据更新

2.2. FIFO已满无法写入

功能描述：当full=1且wr_en=1时，wdata被丢弃

观测点：

• full信号持续为高
• 存储阵列内容不变

2.3. 无写使能不写

功能描述：当wr_en=0时，无论FIFO状态如何均不写入数据

观测点：

• 写指针冻结
• 存储阵列内容保持不变

3. 复位操作

3.1. 复位控制

功能描述：当rst_n=0时，清空FIFO并重置指针

观测点：

• 复位后empty=1且full=0
• 读写指针归零

常量说明

接口说明

输入接口

输出接口

测试点总表

建议各个测试点的覆盖组使用下表描述的功能和测试点名称进行命名。

比如FIFO_READ的测试点NORMAL，其覆盖点建议命名为FIFO_READ_NORMAL

12.1.3 - 果壳Cache文档案例

本文档将以果壳L1Cache作为案例，展示一个具有相当复杂度的模块的验证说明文档例子（请一定同提交的验证报告区分开来）。

果壳L1Cache验证文档

文档概述

本文档针对NutShell L1Cache的验证需求撰写，通过对其功能进行描述并依据功能给出参考测试点，从而帮助验证人员编制测试用例。

果壳（NutShell）是一款由5位中国科学院大学本科生设计的基于RISC-V RV64开放指令集的顺序单发射处理器(NutShell·Github), 隶属于国科大与计算所“一生一芯”项目。而果壳Cache（NutShell Cache）是其缓存模块，采用可定制化设计（L1 Cache和L2 Cache采用相同的模板生成，只需要调整参数），具体来说，L1 Cache（指令Cache和数据Cache）大小为32KB，L2 Cache大小为128KB, 在整体结构上，果壳Cache采用三级流水的结构。

本次验证的目标是L1 Cache，即一级缓存。

术语说明

前置知识

Cache的层次结构

Cache有三种主要的组织方式：直接映射（Direct-Mapped）Cache、组相连（Set-Associative）Cache和全相连（Fully-Associative）Cache。对于物理内存中的一个数据，如果在Cache中只有一个位置可以存放它，这就是直接映射Cache；如果有多个位置可以存放这个数据，这就是组相连Cache；如果Cache中的任何位置都可以存放这个数据，这就是全相连Cache。

直接映射Cache和全相连Cache实际上是组相连Cache的两种特殊情况。现代处理器中的Cache通常属于这三种方式中的一种。例如，翻译后备缓冲区（TLB）和Victim Cache多采用全相连结构，而普通的指令缓存（I-Cache）和数据缓存（D-Cache）则采用组相连结构。当处理器需要执行一个指令时，它会首先查找该指令是否在I-Cache中。如果在，则直接从I-Cache中读取指令并执行；如果不在，则需要从内存中读取指令到I-Cache中，再执行。与I-Cache类似，当处理器需要读取或写入数据时，会首先查找D-Cache。如果数据在D-Cache中，则直接读取或写入；如果不在，则需要从内存中加载数据到D-Cache中。与I-Cache不同的是，D-Cache需要考虑数据的一致性和写回策略。为了保证数据的一致性，当数据在D-Cache中被修改后，需要同步更新到内存中。

Cache的写入

在执行写数据时，如果只是向D-Cache中写入数据而不改变其下级存储器中的数据，就会导致D-Cache和下级存储器对于同一地址的数据不一致（non-consistent）。为了保持一致性，一般Cache在写命中状态下采用两种写入方式： （1）写通（Write Through）：数据写入D-Cache的同时也写入其下级存储器。然而，由于下级存储器的访问时间较长，而存储指令的频率较高，频繁地向这种较慢的存储器中写入数据会降低处理器的执行效率。 （2）写回（Write Back）：数据写入D-Cache后，只是在Cache line上做一个标记，并不立即将数据写入更下级的存储器。只有当Cache中这个被标记的line要被替换时，才将其写入下级存储器。这种方式能够减少向较慢存储器写入数据的频率，从而获得更好的性能。然而，这种方式会导致D-Cache和下级存储器中许多地址的数据不一致，给存储器的一致性管理带来一定的负担。

D-Cache处理写缺失一般有两种策略：

（1）非写分配（Non-Write Allocate）：直接将数据写入下级存储器，而不将其写入D-Cache。这意味着当发生写缺失时，数据会直接写入到下级存储器，而不会经过D-Cache。

（2）写分配（Write Allocate）：在发生写缺失时，会先将相应地址的整个数据块从下级存储器中读取到D-Cache中，然后再将要写入的数据合并到这个数据块中，最终将整个数据块写回到D-Cache中。这样做的好处是可以在D-Cache中进行更多的操作，但同时也增加了对内存的访问次数和延迟。 写通（Write Through）和非写分配（Non-Write Allocate）将数据直接写入下级存储器，而写回（Write Back）和写分配（Write Allocate）则会将数据写入到D-Cache中。通常情况下，D-Cache的写策略搭配为写通+非写分配或写回+写分配。

写通示意图

写通示意图

写回示意图

替换策略

读写D-Cache发生缺失时，需要从对应的Cache Set中找到一个cache行，来存放从下级存储器中读出的数据，如果此时这个Cache Set内的所有Cache行都已经被占用了，那么就需要替换掉其中一个，如何从这些有效的Cache行找到一个并替换它，这就是替换策略，本节介绍几种最常用的替换策略。

近期最少使用法会选择最近被使用次数最少的Cache行，因此这个算法需要追踪每个Cache行的使用情况，这需要为每个Cache行都设置一个年龄（age）部分，每当一个Cache行被访问时，它对应的年龄部分就会增加，或者减少其他Cache行的年龄值，这样当进行替换时，年龄值最小的那个Cache行就是被使用次数最少的了，会选择它进行替换。

随机替换算法硬件实现简单，这种方法发生缺失的频率会更高一些，但是随着Cache容量的增大，这个差距是越来越小的。在实际的设计中，很难实现严格的随机，一般采用一种称为时钟算法（clock algorithm）的方法实现近似的随机，它的工作原理本质上是一个时钟计数器，计数器的宽度由Cache的路的个数决定，当要替换时，就根据这个计数器选择相应的行进行替换。这种方法硬件复杂度较低，也不会损失较多的性能，因此是一种折中的方法。

整体框图和流水级

以下是L1Cache的整体框图和流水级示意：

子模块列表

以下是NutShell L1Cache的一些子模块：

上下游通信总线采用SimpleBus总线，包含了req和resp两个通路，其中req通路的cmd信号表明请求的操作类型，可以通过检查该信号获得访问类型。SimpleBus总线共有七种操作类型，由于NutShell文档未涉及probe和prefetch操作，在验证中只出现五种操作：read、write、readBurst、writeBurst、writeLast，前两种为字读写，后三种为Burst读写，即一次可以操作多个字。

常量说明

接口说明

测试点总表

实际使用下面的表格时，请用有意义的英文大写的功能名称和测试点名称替换下面表格中的名称

12.2 - Frontend

前端模块验证文档

12.2.1 - FTQ概述

下文（包括所有的FTQ文档）中会提到一些关于BPU和IFU的相关知识，详情需要去查看对应的文档:

• BPU文档链接
• IFU文档链接

hint：建议先从BPU基础设计中着重理解以下概念：

1. 什么是分支预测？
2. 什么是分支预测块？一个有帮助的链接：预测块
3. (可选)什么是重定向，什么是预测结果重定向？
4. (可选)分支预测的流水级

简介

FTQ 是分支预测和取指单元之间的缓冲队列，它的主要职能是暂存 BPU 预测的取指目标，并根据这些取指目标给 IFU 发送取指请求。它的另一重要职能是暂存 BPU 各个预测器的预测信息，在指令提交后把这些信息送回 BPU 用作预测器的训练，因此它需要维护指令从预测到提交的完整的生命周期。另外，后端将存储来自FTQ的取指目标PC，便于自身读取。

![[Pasted image 20250222103931.png]]

模块之间的中转站

从上图，FTQ很大程度上相当于一个中转站，中间人的角色，一方面，它承担着BPU和IFU之间的交互，这通常是因为BPU预测的速度快于IFU取值执行，所以使用FTQ作为缓冲。另一方面，它承担着后端与前端的交互，比如把前端将要执行的pc交给后端去执行。

显然，FTQ的 中转远不止这么多，下面更具体地讨论一下FTQ怎么中转各个前端或后端模块的信息的。

BPU和FTQ

BPUtoFTQ：BPU会将分支预测结果和meta数据发给FTQ。

• 从分支预测结果中，我们可以提取出分支预测块对应的取值目标，比如，一个不跨缓存行且所有指令均为RVC指令的分支预测块对应的取值目标，是从分支预测块起始地址开始的以2B为间隔的连续16条指令。
• meta信息则存储了各个预测器相关的预测信息，由于BPU预测有三个流水级，每个流水级都有相应的预测器，所以只有到s3阶段才有可能收集到所有预测器的预测信息，直到此时FTQ才接受到完整的meta，这些信息会在该分支预测块的全部指令被后端提交时交给BPU进行训练
• FTBEntry：严格来说，它其实也是meta的一部分，但是因为更新的时候ftb_entry需要在原来的基础上继续修改，为了不重新读一遍ftb，另外给它存储一个副本。

FTQtoBPU：FTQ会将带元数据的训练信息和重定向信息发回给BPU

• 请参照BPU文档链接 BPU 模块整体对外接口 (PredirectIO)

FTQ和IFU

FTQtoIFU：FTQ会将存储的取值目标发往IFU进行取值译码和把后端的重定向信息也移交给IFU

• 取值目标同时也发给：
  • toICache：同样的取值目标会被发给指令缓存单元，看对应的指令是否在缓存单元内存在，如果有会被直接发送给IFU加速取值效率
  • toPrefetch: prefetch是ICache的一个组件，负责预取功能
• 转发后端重定向：
  • 后端重定向不仅需要转发给BPU帮助其回到正确状态，也同时需要转发给IFU帮助其回到正确状态

IFUtoFTQ：IFU将预译码信息和重定向信息写回FTQ

• 预译码信息：包含分支预测块对应的预测宽度内所有指令的预译码信息 预测宽度：一个指令块预测块覆盖的指令范围，香山中是16条rvc指令
• 重定向信息其实也是根据预译码信息得到的：当预译码信息中指出预测块内某一条指令预测出错时，写回IFU重定向信息

后端和FTQ

FTQ到后端：FTQ会将存储的取值目标发往后端，后端存储 PC后，在本地即可进行读取取指目标。

• 除了IFU，预测块的取值目标也会发给后端，但这里有一点区别：IFU空闲时才能从FTQ中获取取值目标，但是后端会一直取得最新的预测块的取指目标

后端到FTQ：后端重定向和指令commit

• 后端重定向与更新：后端是实际执行指令的单元，通过后端的执行结果，才能确认一条指令是否执行错误，产生重定向，同时，在发生重定向时，根据后端实际执行结果生成更新信息。
• 指令commit：当一个分支预测块内的所有指令都被执行，在后端提交，这标志着FTQ队列中这个分支预测块对应的FTQ项已经结束了它的生命周期，可以从队列中移除了，这时候，我们就可以把它的更新信息发给FTQ了。

FTQ指针

FTQ的全名叫取值目标队列，队列中的一个项叫做FTQ项，BPU写入预测结果时是写入队列中哪个位置，IFU又是从哪个队列取FTQ项？这时候，我们需要一个FTQ指针去索引FTQ项，而由于和不同模块的交互需要索引不同的FTQ项，因此，有以下类型的FTQ指针，下面，由指令生命周期为例，大致介绍这些指针：

指令在 FTQ 中的生存周期

指令以预测块为单位，从 BPU 预测后便送进 FTQ，直到指令所在的预测块中的所有指令全部在后端提交完成，FTQ 才会在存储结构中完全释放该预测块所对应的项。这个过程中发生的事如下：

1. 预测块从 BPU 发出，进入 FTQ，bpuPtr 指针加一，初始化对应 FTQ 项的各种状态，把各种预测信息写入存储结构；如果预测块来自 BPU 覆盖预测逻辑，则恢复 bpuPtr 和 ifuPtr
2. FTQ 向 IFU 发出取指请求，ifuPtr 指针加一，等待预译码信息写回
3. IFU 写回预译码信息，ifuWbPtr 指针加一，如果预译码检测出了预测错误，则给 BPU 发送相应的重定向请求，恢复 bpuPtr 和 ifuPtr
4. 指令进入后端执行，如果后端检测出了误预测，则通知 FTQ，给 IFU 和 BPU 发送重定向请求，恢复 bpuPtr、ifuPtr 和 ifuWbPtr
5. 指令在后端提交，通知 FTQ，等 FTQ 项中所有的有效指令都已提交，commPtr 指针加一，从存储结构中读出相应的信息，送给 BPU 进行训练

预测块 n 内指令的生存周期会涉及到 FTQ 中的 bpuPtr、ifuPtr、ifuWbPtr 和 commPtr 四个指针，当 bpuPtr 开始指向 n+1 时，预测块内的指令进入生存周期，当 commPtr 指向 n+1 后，预测块内的指令完成生存周期。

循环队列

FTQ队列实际上是一个循环队列，所有类型的FTQ指针都是同一类型，ftqPtr的value字段用来表示索引，flag字段则用来表示循环轮数，flag只有一位，进入新的循环时flag位翻转。 这样，我们就可以在一个有限的队列空间内不断更新新的项，以及正确进行比较，判断哪个项在队列中更靠前或者更靠后。

12.2.1.1 - FTQ顶层

简述

在FTQ概述中，我们已经知道了，FTQ的作用就是多个模块交互的中转站，大致了解了它接受其他模块的哪些信息，它如何接受并存储这些信息在FTQ中，并如何把这些存储信息传递给需要的模块。 下面我们来具体了解一下FTQ与其他模块的交互接口，我们会对这种交互有一个更具体的认识。

IO一览

模块间IO

• fromBpu：接受BPU预测结果的接口（BpuToFtqIO）
• fromIfu：接受IFU预译码写回的接口（IfuToFtqIO）
• fromBackend：接受后端执行结果和commit信号的接口（CtrlToFtqIO）
• toBpu：向BPU发送训练信息和重定向信息的接口（FtqToBpuIO）
• toIfu：向IFU发送取值目标和重定向信息的接口（FtqToIfuIO）
• toICache：向ICache发送取值目标的接口（FtqToICacheIO）
• toBackend：向后端发送取值目标的接口（FtqToCtrlIO）
• toPrefetch：向Prefetch发送取值目标的接口（FtqToPrefetchIO）
• mmio

其他

上述是主要的IO接口，此外，还有一些用于性能统计的IO接口，比如对BPU预测正确和错误结果次数进行统计，并进行转发的IO, 还有转发BPU各预测器预测信息的IO。

BpuToFtqIO

IfuToFtqIO

我们知道从IFU，我们会得到预译码信息和重定向信息，而后者其实也是从预译码信息中生成。所以从IFU到FTQ的接口主要就是用来传递预译码信息的

• pdWb：IFU向FTQ写回某个FTQ项的预译码信息
  • 接口类型：PredecodeWritebackBundle
  • 信号列表：
    • pc：一个分支预测块覆盖的预测范围内的所有pc
      • 接口类型：Vec(PredictWidth, UInt(VAddrBits.W))
    • pd：预测范围内所有指令的预译码信息
      • 接口类型：Vec(PredictWidth, new PreDecodeInfo)
      • PreDecodeInfo：每条指令的预译码信息
        • 接口类型：PreDecodeInfo
        • 信号列表：
          • valid：预译码有效信号
            • 接口类型：Bool
          • isRVC：是RVC指令
            • 接口类型：Bool
          • brType：跳转指令类型
            • 接口类型：UInt(2.W)
            • 说明：根据brType的值判断跳转指令类型
              • b01：对应分支指令
              • b10：对应jal
              • b11：对应jalr
              • b00：对应非控制流指令
          • isCall：是Call指令
            • 接口类型：Bool
          • isRet：是Ret指令
            • 接口类型：Bool
    • ftqIdx：FTQ项的索引，标记写回到哪个FTQ项
      • 接口类型：FtqPtr
    • ftqOffset：由BPU预测结果得到的，在该指令块中指令控制流指令的位置（指令控制流指令就是实际发生跳转的指令）
      • 接口类型：UInt(log2Ceil(PredictWidth).W)
    • misOffset：预译码发现发生预测错误的指令在指令块中的位置
      • 接口类型：ValidUndirectioned(UInt(log2Ceil(PredictWidth).W))
      • 说明：它的valid信号拉高表示该信号有效，也就说明存在预测错误，会引发重定向
    • cfiOffset：由预译码结果得到的，在该指令块中指令控制流指令的位置（指令控制流指令就是实际发生跳转的指令）
      • 接口类型：ValidUndirectioned(UInt(log2Ceil(PredictWidth).W))
    • target：该指令块的目标地址
      • 接口类型：UInt(VAddrBits.W)
      • 说明：所谓目标地址，即在指令块中有控制流指令时，控制流指令的地址，在没有控制流指令时，指令块顺序执行，该指令块最后一条指令的下一条指令
    • jalTarget：jal指令的跳转地址
      • 接口类型：UInt(VAddrBits.W)
    • instrRange：有效指令范围
      • 接口类型：Vec(PredictWidth, Bool())
      • 说明：表示该条指令是不是在这个预测块的有效指令范围内（第一条有效跳转指令之前的指令）

CtrlToFtqIO

后端控制块向FTQ发送指令提交信息，后端执行结果的接口。

• rob_commits：一个提交宽度内的RobCommitInfo信息。
  • 接口类型：Vec(CommitWidth, Valid(new RobCommitInfo))
  • 详情链接：RobCommitInfo
• redirect：后端提供重定向信息的接口。
  • 接口类型：Valid(new Redirect)
  • 详情链接：Redirect
• ftqIdxAhead：提前重定向的FTQ指针，将要重定向的FTQ项的指针提前发送
  • 接口类型： Vec(BackendRedirectNum, Valid(new FtqPtr))
  • 说明：虽然有三个接口，但实际上只用到了第一个接口，后面两个弃用了
• ftqIdxSelOH：独热码，本来是依靠该信号从提前重定向ftqIdxAhead中选择一个，但现在只有一个接口了，独热码也只有一位了。
  • 接口类型：Valid(UInt((BackendRedirectNum).W))
  • 说明：为了实现提前一拍读出在ftq中存储的重定向数据，减少redirect损失，后端会向ftq提前一拍（相对正式的后端redirect信号）传送ftqIdxAhead信号和ftqIdxSelOH信号。

FtqToBpuIO

FtqToICacheIO

FTQ向IFU发送取值目标，ICache是指令缓存，如果取值目标在ICache中命中，由ICache将指令发给IFU

• req：FTQ向ICache发送取值目标的请求
  • 接口类型：Decoupled(new FtqToICacheRequestBundle)
  • 信号列表：
    • pcMemRead：FTQ针对ICache发送的取值目标，ICache通过5个端口同时读取取指目标
      • 接口类型：Vec(5, new FtqICacheInfo)
      • FtqICacheInfo: FTQ针对ICache发送的取值目标
        • 信号列表：
          • ftqIdx：指令块在FTQ中的位置索引
            • 接口类型：FtqPtr
          • startAddr：预测块起始地址
            • 接口类型：UInt(VAddrBits.W)
          • nextlineStart：起始地址所在cacheline的下一个cacheline的开始地址
            • 接口类型：UInt(VAddrBits.W)
          • 说明：通过startAddr(blockOffBits - 1)这一位（也就是块内偏移地址的最高位）可以判断该预读取pc地址是位于cacheline的前半块还是后半块，若是前半块，由于取值块大小为cacheline大小的一半，不会发生跨cacheline行
    • readValid: 对应5个pcMemRead是否有效
    • backendException：是否有后端异常

FtqToCtrlIO

FTQ向后端控制模块转发PC，后端将这些pc存储在本地，之后直接在本地读取这些pc 写入后端pc mem

• pc_mem_wen：FTQ向后端pc存储单元pc_mem写使能信号
  • 接口类型：Output(Bool())
• pc_mem_waddr：写入地址
  • 接口类型：Output(UInt(log2Ceil(FtqSize).W))
• pc_mem_wdata：写入数据，是一个指令块的取值目标
  • 接口类型：Output(new Ftq_RF_Components)，详见FTQ子队列相关介绍 写入最新目标
• newest_entry_en：是否启用
  • 接口类型：Output(Bool())
• newest_entry_target：最新指令块的跳转目标
  • 接口类型：Output(UInt(VAddrBits.W))
• newest_entry_ptr：最新指令块的索引值
  • 接口类型： Output(new FtqPtr)

FtqToPrefetchIO

• req：FTQ向Prefetch发送取值目标的请求
  • 接口类型：FtqICacheInfo
• flushFromBPU: 来自BPU的冲刷信息
  • 接口类型：BpuFlushInfo
  • 信号列表：
    • s2 ：BPU预测结果重定向（注意这种重定向是BPU自己产生的，与其他类型要做区分）发生在s2阶段时，此阶段的分支预测块的索引
      • 接口类型：Valid(new FtqPtr)
      • 说明：valid信号有效时，说明此时s2流水级分支预测结果与其s1阶段预测结果不一致，产生s2阶段重定向
    • s3：BPU预测结果重定向（注意这种重定向是BPU自己产生的，与其他类型要做区分）发生在s3阶段时，此阶段的分支预测块的索引
      • 接口类型：Valid(new FtqPtr)
      • 说明：与s2类似
    • 说明：发生预测结果重定向的时候，预取单元和IFU都可能会被冲刷，比如，如果发生s2阶段重定向，FTQ会比较发给IFU req接口中的ftqIdx和s2阶段预测结果的ftqIdx，如果s2阶段的ftqIdx不在req的ftqIdx之后，这意味着，s2阶段产生的预测结果重定向之前的错误预测结果s1阶段预测结果被发给IFU进行取指了，为了消除这种错误，需要向IFU发送s2阶段flush信号。
• backendException：后端执行发生的异常
  • 接口类型：UInt(ExceptionType.width.W)
  • 说明：表示后端执行时发生异常的类型，有这样几种类型的异常：

def none:  UInt = "b00".U(width.W)
def pf:    UInt = "b01".U(width.W) // instruction page fault
def gpf:   UInt = "b10".U(width.W) // instruction guest page fault
def af:    UInt = "b11".U(width.W) // instruction access fault

12.2.1.2 - FTQ子队列

文档概述

请注意：从本篇开始，就涉及待验证的功能点和测试点了

在之前的介绍中，我们采用FTQ项这个术语描述描述FTQ队列中的每一个元素，实际上，这只是一种便于抽象的说法。

实际上的FTQ队列，是由好多个子队列共同构成的，一些子队列维护一类信息，另一些子队列维护另一类信息，相同ftqIdx索引的子队列信息共同构成一个完整的FTQ项。

为什么要把它们分开成多个子队列呢？因为某些模块只需要FTQ项中的某一些信息，比如IFU想要取值目标，它只需要专门存储取值目标的子队列提供的信息就行了。另外，在我们更改FTQ项的内容时，也只需要写入需要更新的子队列，比如IFU预译码写回时，只需要写回专门存储预译码信息的队列了。

下面来介绍一些FTQ的主要子队列，以及它们内部存储的数据结构。此外，FTQ还有一些存储中间状态的更小的队列

术语说明

子模块列表