How to Install and Use XiangShan: The Future of Open-Source High-Performance RISC-V Processors 🚀

Saturday, Jan 11, 2025 | 6 minute read

GitHub Trend

Unleash the future of open-source processors with cutting-edge design and impressive performance! 🌟 This innovative RISC-V architecture emphasizes flexibility, community involvement, and seamless integration of research and application. Join the movement for advancing computing power! 🚀

Discovering the Allure of XiangShan 🔍

“Open-source is not just a technical choice; it’s the direction of the future.” 🌟

Recently, with the ever-increasing demand for computing power 🚀, the openness and flexibility of the RISC-V instruction set architecture have become hot topics of discussion. As an emerging architectural design philosophy, RISC-V has garnered attention from numerous developers and companies. In this wave of innovation, the XiangShan project (香山) is rapidly rising to prominence as a leader in open-source high-performance processors with its superior design and top-tier performance! ✨

Since the project commenced in 2019, XiangShan has been dedicated to establishing an efficient open-source RISC-V processor that caters to various needs in architectural research for both academia and industry. 🍃 Leveraging the open RISC-V instruction set, it specifically supports the RV64GCBVH instruction set to ensure broad compatibility and application potential. As the project progresses, XiangShan has undergone rapid technological development and iteration, further advancing open-source processor technology! 📈

What Sets XiangShan Apart? Key Features Revealed 🔑

The microarchitecture design of XiangShan is highly adaptable, boasting multiple versions such as Yanqihu (焱栖湖), Nanhu (南湖), and the ever-evolving Kunminghu (昆明湖), with each version featuring unique functionalities and improvements to precisely meet the diverse needs of users! 🌊 The project operates under the Mulan PSL v2 open-source license, maintaining all design specifications, validation processes, and tools in an open state to ensure high transparency and accessibility. ✨

Even more exciting is XiangShan’s encouragement for community participation, emphasizing the importance of collaboration. It advocates for users to engage in discussions, submit code, and provide feedback, driving collective advancement of the project—truly a prime example of the open-source spirit! 🤝

Why Do Developers Choose XiangShan? What Makes It Attractive? 🌟

XiangShan is widely popular for its stunning performance, standing out among many open-source processor cores and attracting the attention of countless developers and enthusiasts domestically and internationally. 📣 The project provides rich documentation and learning resources, allowing users to easily access design specifications, technical slides, tutorials, and hands-on guides in its official documentation repository on GitHub, making learning and development smoother! 📚

Moreover, XiangShan integrates academic research with practical applications, offering developers a platform of immense practical value where innovative ideas quietly take shape! 💡

The XiangShan project is rapidly evolving and is worthy of high attention from both industry and academia. 👀 Developers and researchers can visit XiangShan’s GitHub page for more information and design codes and join this vibrant open-source community to drive innovation and development in the RISC-V processor field! 🌍

Installing XiangShan: A Step-by-Step Guide from Preparation to Execution 🚀

1. Installation Preparation 🛠️

Before we dive into the installation, make sure your system has Docker installed and that your computer is equipped with at least 32GB of RAM to meet memory and other dependency requirements! Next, initiate the XiangShan environment using the following Dockerfile:

# Dockerfile
FROM ubuntu:24.04

• FROM ubuntu:24.04: This line specifies that the base image for the current image is Ubuntu 24.04—selecting an appropriate base image is the first step in setting up a Docker environment!

Next, update the package manager and install the necessary development tools and libraries:

RUN apt-get update && apt-get install -y build-essential clang libclang-dev llvm-dev cmake libspdlog-dev vim git curl wget time default-jre default-jdk

• apt-get update: Updates the local package index to ensure we can access the latest software packages.
• apt-get install -y ...: Installs the tools and dependencies required for building and development, including compilers (like clang) and build systems (like cmake), laying the groundwork for compiling environments.

2. Cloning Project and Initialization 📥

Next, clone the XiangShan environment and initialize the related submodules:

RUN git clone --recursive https://github.com/OpenXiangShan/xs-env
WORKDIR /xs-env
RUN sed 's/apt\S* install/\0 -y/g;s/source /. /g;s/sudo //g' -i ./*.sh

• git clone --recursive ...: This command will clone the source code of the XiangShan environment completely, including all submodules, ensuring you have the full project.
• WORKDIR /xs-env: Sets the working directory to the cloned project directory, where all subsequent commands will be executed.
• sed ...: The sed command modifies Shell scripts to automatically add -y during installations, facilitating a smoother installation process.

Run the environment script to set variables and update submodules with the following steps:

RUN . ./env.sh && sed 's/\/master/\/master/g;s/$/; cd \/xs-env/g' -i ./update-submodule.sh && ./update-submodule.sh

• source ./env.sh: Executes the environment script to configure environment variables in the current Shell session.
• update-submodule.sh: Ensures that all submodules are updated to the latest state.

3. Setting Up Tools and Compiling 🔧

Now, set up the necessary tools and compile the project:

RUN . ./env.sh && ./setup-tools.sh
RUN . ./env.sh && . ./install-verilator.sh
RUN . ./env.sh && sed 's/^git submodule.*$//g;s/env.*$//g' -i ./setup.sh && . ./setup.sh

• setup-tools.sh: This script initializes the tools required for the project.
• install-verilator.sh: Installs Verilator, an important Verilog simulator.
• setup.sh: Responsible for the initialization of some project settings.

In the next step, compile XiangShan and DRAMsim3:

RUN . ./env.sh && make -C XiangShan init
RUN . ./env.sh && cd DRAMsim3 && mkdir build && cd build && cmake -D COSIM=1 .. && make -j 8
RUN . ./env.sh && make -C XiangShan emu CONFIG=DefaultConfig WITH_DRAMSIM3=1 MFC=1 -j 8

• make -C XiangShan init: Initializes the XiangShan project.
• cmake -D COSIM=1 .. && make -j 8: Processes the build files in the DRAMsim3 directory and compiles using 8 threads in parallel to enhance build efficiency.
• make emu ...: Compiles the XiangShan emulator, preparing for subsequent simulation work.

4. Generating and Running ⚙️

Finally, generate the Verilog code:

make verilog

• This command generates Verilog code after compilation, with the output file being build/XSTop.v, which is a critical component needed for subsequent simulations. Get ready for testing!

Next, set up the simulation environment:

# Set environment variables
export NEMU_HOME=<path-to-NEMU>
export NOOP_HOME=<path-to-XiangShan>
export AM_HOME=<path-to-AM>

• Make sure to set the environment variables to the absolute paths of the NEMU, XiangShan, and AM projects—this crucial step is vital for the smooth execution of the simulation, so don’t forget it!

Run the simulation:

make emu CONFIG=MinimalConfig EMU_THREADS=2 -j10
./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so

• make emu: Builds the emulator.
• ./build/emu ...: Executes the simulation, running the specified binary file for verification—this is the most critical step after setting up the entire environment, ensuring everything you’ve done is functioning properly!

Performance Optimization and Troubleshooting 🔍

1. Memory and Swap Settings ⚡

Ensure your machine has sufficient memory; specifically, it’s recommended:

• MinimalConfig: A configuration with more than 32GB of memory helps in basic functional testing and development.
• Complete XiangShan Version: A configuration with over 64GB of memory enhances overall performance and is suitable for larger-scale development and testing.

2. Java Version ☕️

Ensure you use Java 11 or newer to avoid compatibility issues with Java 8. It’s advisable to use GraalVM, which can effectively reduce memory usage, accelerate Java application compilation speed, and boost development efficiency!

3. Verilator 🔄

Make sure to use the latest version of Verilator, as older versions in apt-get are often outdated. Updating ensures better functionality support and performance, allowing you to utilize the newest features smoothly.

4. Submodule Initialization 📦

Ensure all git submodules are properly defined. If you encounter difficulties at any step, running the make init command can reinitialize and potentially resolve related issues, helping you maintain project integrity!

Give it a try, and you will find that you love XiangShan! 🎉