Prepare Verification Environment
Basic Environment Requirements
This project uses the Python
programming language for UT verification, with picker and toffee as the main tools and test frameworks. Environment requirements are as follows:
- Linux operating system. It is recommended to install Ubuntu 22.04 under WSL2.
- Python. Python 3.11 is recommended.
- picker. Install the latest version as instructed in the Quick Start.
- toffee. It will be installed automatically later. You can also manually install the latest version as instructed in the Quick Start.
- lcov. Used for report generation in the test stage. Install via package manager:
sudo apt install lcov
After environment setup, clone the repository:
git clone https://github.com/XS-MLVP/UnityChipForXiangShan.git
cd UnityChipForXiangShan
pip3 install -r requirements.txt # Install python dependencies (e.g., toffee)
Download RTL Code
By default, download from the repository https://github.com/XS-MLVP/UnityChipXiangShanRTLs. Users can also generate RTL by compiling according to the XiangShan documentation.
make rtl # This command downloads the latest rtl code, unpacks it to the rtl directory, and creates a symlink
You can specify the rtl version to download with the following command:
make rtl args="rtl.version='openxiangshan-kmh-fad7803d-24120901'"
All RTL download packages can be found at UnityChipXiangShanRTLs.
The naming convention for RTL archives is: name-microarchitecture-GitTag-date.tar.gz
, for example, openxiangshan-kmh-97e37a2237-24092701.tar.gz
. When used, the repository code will filter out the git tag and suffix, so the version accessed via cfg.rtl.version is: openxiangshan-kmh-24092701
. The directory structure inside the archive is:
openxiangshan-kmh-97e37a2237-24092701.tar.gz
└── rtl # directory
|-- *.sv # all sv files
`-- *.v # all v files
Compile DUT
The purpose of this process is to package the RTL into a Python module using the picker tool. You can specify the DUT to be packaged via the make command, or package all DUTs at once.
If you want to package a specific dut yourself, you need to create a script named build_ut_
Picker’s packaging supports adding internal signals; See the –internal parameter of picker and pass a custom yaml.
# Calls the build method in scripts/build_ut_<name>.py to create the Python DUT to be verified
make dut DUTS=<name> # If there are multiple DUTS, separate them with commas. Wildcards are supported. The default value is "*", which compiles all DUTs.
# Example:
make dut DUTS=backend_ctrl_block_decode
For example, after running make dut DUTS=backend_ctrl_block_decode
, the corresponding Python package will be generated in the dut directory:
dut/
├── __init__.py
├── DecodeStage
├── Predecode
└── RVCExpander
After conversion, you can import the corresponding DUT in your test case code, for example:
from dut.PreDecode import DUTPreDecode
dut = DUTPreDecode()
Edit Configuration
When running rtl, dut, test, and other commands, the default configuration is used from configs/_default.yaml.
Of course, you can also use a custom configuration as follows:
# Specify a custom CFG file
make CFG=path/to/your_cfg.yaml
Similarly, you can specify key-value pairs directly on the command line. Currently, only the test-related stage supports command-line configuration key-value pairs:
# Specify KV, pass command-line arguments, separate key-value pairs with spaces
make test KV="log.term-level='debug' test.skip-tags=['RARELY_USED']"