You’ll use two sets of tools in this class: QEMU, a machine emulator for running your kernel; and a compiler toolchain, including assembler, linker, C compiler, and debugger, for compiling and testing your kernel.

You have two options to install your development environment. Please take care of this as soon as the semester starts as it can take some time to get familiar with the environment. There is technically a third option whereby you install all software and dependencies manually on Linux or Mac, but this is not officially supported.

Option 1: Docker on Personal Machine

We recommend the use of Docker Desktop, if your personal machine:

is reasonably new (maybe 4 years),
is reasonably up to date,
has adequate free disk space (ten gigabytes should do it).

Follow the installation instructions.

Option 2: Docker on Duke VCM Virtual Machine

We have reserved a set of virtual machines (VMs) on Duke VCM. You first need to figure out how to ssh into the VM; if you are unfamiliar with this, please see the Duke VCM SSH Guide.

Using Docker

Docker constructs the environment for building and running course projects. Under the hood, Docker launches a container that runs alongside the host operating system, managing all dependencies and software requirements. We provide a standard Docker image on Dockerhub, which supports xv6 environment for the labs. The container runs bash with user xv6. The password of the user is also xv6.

Each lab will rely on the same base repo that contains all of the necessary files (e.g., xv6, grading scripts). Please clone the base repo in your host system (i.e., your personal machine or Duke VCM) before you start. Follow the git instructions to learn how to clone the base repo. Once you have the base repo cloned, you can start a new Docker container by running:

On Macbook/Linux:

$ cd <PathToBaseRepo>
$ docker run -it --rm -v $PWD:/home/xv6/xv6-riscv iqicheng/cps310-env

On Windows Powershell:

$ cd <PathToBaseRepo>
$ docker run -it --rm -v ${PWD}:/home/xv6/xv6-riscv iqicheng/cps310-env

On Windows Cmd:

$ cd <PathToBaseRepo>
$ docker run -it --rm -v "%cd%":/home/xv6/xv6-riscv iqicheng/cps310-env

This command also maps the xv6 repository directory into /home/xv6/xv6-riscv inside your container. If successful, you should see the following output from the container:

To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

xv6@0c765f60374a:~/xv6-riscv$ 

The shell prompt (xv6@0c765f60374a:~/xv6-riscv$) consists of the username (xv6), hostname (0c765f60374a), and current working directory (/home/xv6/xv6-riscv or ~/xv6-riscv). The hostname is the same as the container ID, so it will likely differ from the above example.

Building and Running xv6

All of the kernel-oriented labs rely on the xv6 teaching OS. The Docker container will support building and running xv6 wit QEMU. To do this, run the following commands:

xv6@0c765f60374a:~/xv6-riscv$ make
...
xv6@0c765f60374a:~/xv6-riscv$ make qemu
...
xv6 kernel is booting

hart 2 starting
hart 1 starting
init: starting sh
$ 

At this point, you are now in a shell hosted by the xv6 OS. You can run any available user-space programs (e.g., ls).

To exit from xv6 and return to the Docker container, type ctrl-a followed by x.

Working on Projects

Now you are free to start working on your lab. The lab repo in your host system is mounted into the docker container, so you can open the repo with any editor of your choice on your host system (e.g., VSCode, vim, emacs). All the modifications will be reflected in the Docker container automatically.

If you are using a VCM machine, you can use VSCode and the Remote-SSH plugin to connect to you VCM machine.