UnityChip For XiangShan Processor

English | 中文

This project aims to perform unit testing (Unit Test, UT) on the Kunminghu architecture of the XiangShan Processor through open-source crowdsourcing. Python is chosen as the primary verification language for this project. By participating in the verification, you will learn the following:

1. Circuit Characteristics: Observe the characteristics of circuits from a software perspective and gain an in-depth understanding of circuit design principles.
2. High-Performance CPU Design: Learn the Chisel hardware description language, study related code and papers, and master the latest CPU architectural design concepts.
3. Chip Verification: Familiarize yourself with specification documents (Spec documents), learn how to perform UT verification, and evaluate the rationality of verification results.
4. Python Verification: Master advanced programming patterns such as asynchronous programming and callbacks, and use Python for chip verification.
5. Linux Experience: Learn basic Linux commands and set up the verification environment.

This project welcomes contributions in various aspects and will provide rewards (such as bonuses, certificates, internship opportunities, etc.) within a certain period. Specific types of contributions include:

• # 1: Create test cases, including functional point-specific test code with annotations, as well as accompanying documentation.
• # 2: Identify and report bugs in the Xiangshan Processor (additional rewards may be granted for root cause analysis and repair suggestions).
• # 3: Develop verification documentation, including specification documents, user manuals, functional description documents for the Design Under Test (DUT), and related materials.
• # 4: Miscellaneous contributions, such as implementing new features or enhancements for tools used in this project.

UnityChip project website: https://open-verify.cc

We look forward to your participation!

Quick Start

Refer to the Environment Preparation to set up the basic environment, and then run the following commands:

git clone git@github.com:XS-MLVP/UnityChipForXiangShan.git
cd UnityChipForXiangShan
pip3 install -r requirements.txt
make all

The above commands will automatically perform the following operations:

1. Download the RTL code;
2. Compile all available modules to be verified;
3. Search for all Python files starting with test_ in the ut_* directories and run the test cases starting with test_ in them;
4. Generate test reports (the test reports are located in the out directory);
5. Update statistical data.

*By default, tests that are too time-consuming will be skipped. You can run all test cases by setting CFG=configs/noskip.yaml， eg:

make all CFG=configs/noskip.yaml

Display Docs and Data Locally

Follow the Documentation Deployment Instructions to set up the hugo environment, and then execute:

cd UnityChipForXiangShan
make doc

After executing the above commands, you will see output similar to:

Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop

At this point, you can access the provided address (http://127.0.0.1:1313) through your browser.

Test In Docker

To quickly run tests using Docker, you can execute the following commands:

sudo docker pull ghcr.io/xs-mlvp/uc4xs:latest # Pull the image
sudo docker run -p 1313:1313 -it --rm ghcr.io/xs-mlvp/uc4xs:latest /home/run_ci.sh # Run the tests

The run_ci.sh script in the container will perform the following actions:

1. Update picker to the latest version
2. Download this repository and install Python dependencies
3. Run make CFG=configs/ci.yaml args="-n auto" to execute tests
4. Run make doc to generate documentation (test report)

Maintenance

When submitting an Issue, Pull Request, or Discussion, specifying the corresponding module's maintainer can help get a quicker response. For the current list of maintainers, please refer to this link.

If you are interested in this project, you are welcome to become a maintainer.

Additional Information

• Code of Conduct: CODE_OF_CONDUCT.md
• How to Contribute: CONTRIBUTING.md
• Security Issues: SECURITY.md

For more information, please visit: https://open-verify.cc/UnityChipForXiangShan

UnityChip QQ Group: