Setup xv6-riscv Development Environment

This article introduces how to set up the development environment of xv6-riscv.

Introduction

xv6 is a re-implementation of Dennis Ritchie’s and Ken Thompson’s Unix Version 6 (v6). The main purpose of xv6 is as a teaching operating system for MIT’s 6.1810^[1].

Environment

The system environment I use:

• Ubuntu 24.04.1 LTS

Installation

We need to install related cross-compilation tools, as well as QEMU to simulate the RISC-V chip. The following commands are modified from mmikaitis/xv6-tools-container/xv6-tools-container.def^[2]。

sudo apt update
sudo apt install -y build-essential gcc-riscv64-linux-gnu qemu-system-riscv64 gdb-multiarch

Download xv6-riscv

git clone git@github.com:mit-pdos/xv6-riscv.git
cd xv6-riscv

Compile and Run

make
make qemu

Now you can see the following output, which means the compilation and running are successful:

xv6 kernel is booting

hart 2 starting
hart 1 starting
init: starting sh
$

To exit QEMU, you can press Ctrl + A, then press X.

QEMU No Response After Startup

I encountered the problem of no response after starting make qemu when setting up the environment. Finally, I found this issue. The solution provided by the related PR works.

After my attempt, update the system and QEMU to the latest version can also solve the problem. I finally used Ubuntu 24.04.1 LTS and QEMU emulator version 8.2.2 (Debian 1:8.2.2+ds-0ubuntu1.2).

You may also download and compile the latest version of QEMU^[3].

wget https://download.qemu.org/qemu-8.2.2.tar.xz
tar -xf qemu-8.2.2.tar.xz
cd qemu-8.2.2
./configure --disable-kvm --disable-werror --prefix=/usr/local --target-list="riscv64-softmmu"
make
sudo make install
cd ..

When compiling QEMU, you may need to install Ninja^[4].

sudo apt install ninja-build

IDE Remote Development

The project is located on a remote Linux server. If we want to develop using a powerful IDE locally instead of using vim and other text editors on the server, we can use Clion to connect to the server via SSH for development.

After the connection is established, you can develop as if you were working on a local project. Run make qemu in the terminal to run xv6-riscv.

Code Analysis

For some strange historical reason, Clion does not recognize the file structure of Makefile projects well. At first it says “This file does not belong to any project target”, and after marking the directory as “Project Sources and Headers”, it still fails to find the correct header file.

To solve this problem, we just need to create a CMakeLists.txt file to trick the IDE into recognizing the file structure of the project.

cmake_minimum_required(VERSION 3.24)
project(xv6 C)

set(CMAKE_C_STANDARD 99)

include_directories(.)

add_executable(xv6
        kernel
        mkfs
        user
        kernel/main.c
)

Please note include_directories(.), which is used to add the given directories to those the compiler uses to search for include files.

Close Clion and delete the .idea directory, then reopen the project and select “Open as CMake Project”:

Remote Debug

First, map GDB port to the local machine, and add a remote debug configuration:

Then run

make qemu-gdb

After starting, it will wait, run the remote debug just added, and the program will stop at the breakpoint:

If you need to debug user programs instead of the kernel, add another remote debug:

References

1. mit-pdos. xv6-riscv. Archived on 2024-07-23. Retrieved 2024-10-15. ↩
2. xv6-tools-container.def. 2024-09-07. Archived on 2024-10-06. Retrieved 2024-10-15. ↩
3. rovast. qemu-system-riscv64 is not found in package qemu-system-misc. 2022-03-06. Archived on 2024-10-06. Retrieved 2024-10-24. ↩
4. Oleksii Chernykh. Pre built Ninja packages. 2024-04-09. Archived on 2024-10-06. Retrieved 2024-10-24. ↩
5. Zhang Yuxuan. 【99%环境搭建系列】xv6-riscv内核调试教程. 2022-03-19. Archived on 2024-10-06. Retrieved 2024-10-15. ↩
6. 钟万祥. xv6 Remote Debug using CLion. 2019-02-16. Archived on 2024-10-06. Retrieved 2024-10-17. ↩