Setting up Xv6

Xv6 is a real operating system kernel, and hence, it needs real hardware to boot. Fortunately, today we can emulate hardware in software. Programs like QEMU can emulate functionality of the real physical CPU in software. I.e., QEMU implements the normal CPU loop similar to the one we discussed in class: fetches an instruction pointed by the instruction pointer register (EIP), decodes it, performs all permission and condition checks, computes the outcome, increments EIP and continues to the next instruction.

Like a real PC platform, QEMU emulates hardware boot protocol. QEMU starts by loading the disk sector number 0 into the memory location 0x7c00 and jumping to it. Xv6 takes it from there. At a high level, for Xv6 it does not matter if it runs on the real hardware or under QEMU. Of course, emulation is slower than real hardware, but besides that as long as QEMU implements the logic of the CPU correctly we do not see any deviations from a real baremetal execution. Surprisingly, QEMU is reasonably fast, so you as a human barely notice the difference.

SSH into Openlab (circinus-XX)

We will use circinus machines 1 to 48: circinus-1.ics.uci.edu to circinus-48.ics.uci.edu. Before you begin, you need to select a circinus server for yourself. We have the following method to select a server just to provide some uniform distribution of students across different servers:

• Find out your student ID number (Let's say: 66541280).
• Obtain the server number (SN) you will connect to: SN = ID % 47 + 1 (Ex: 66541280 → 44).
• Your server name is : circinus-SN.ics.uci.edu (Ex: circinus-44.ics.uci.edu).

This is the server you will use for the rest of the quarter. Unless it has a problem, stick to it. To configure your Xv6 environment, first, login to your server:

Troubleshooting your Circinus ssh connection

If a specific server is not available, try with SN + 1, and so on. If you get an error message like this:

And you're connecting from outside of campus, you need to need to either use AnyConnect VPN to tunnel in or setup an SSH keypair for passwordless login. Openlab machines do not accept outside password login attempts.

Clone and build QEMU

To run Xv6 we need to compile and install a version of the QEMU emulator. Default QEMU's debugging facilities, while powerful, are somewhat immature, so it is highly recommend you use a patched version of QEMU which is maintained by MIT instead of the stock version that may come with your distribution.

From inside your home folder create a new directory for this class. I suggest you start in your home folder (unless you know what you're doing this is a good way to go)

Change into this new directory

Clone the MIT's QEMU distribution into the qemu folder

Change into qemu folder and initialize an internal git submodule

Configure QEMU with minimal settings and the prefix pointing to the install folder

For example, for me this becomes:

Make and install QEMU (this will take some time)

To make QEMU accessible from other programs add it to your path. You can either add it every time you log in to the circinus machine by exporting the PATH variable:

Or you can add the command to your ~/.bash_profile to include the QEMU path in PATH automatically evey time you login. You can open and edit such file with the program nano:

Use the arrows to go to the end of the file and add these two lines (the first one is a comment):

To save and exit, press Ctrl + X (to say that you want to exit), then Y (to say that you want to save the file), and Enter (to confirm your choice).

Clone, build, and boot Xv6

Change back into the cs238p folder and clone Xv6 repository.

If you want, put an eye on what is in

Build Xv6 (you only will see a bunch of output from the make command that invokes the gcc compiler on all kernel files, links the kernel with ld, creates the kernel file system with all user-level programs that will be available inside Xv6, and so on):

You're now ready to run Xv6.

You are now running Xv6 on top a hardware platform that is emulated by the QEMU emulator. You are now done with the Xv6 setup and can continue moving to any homeworks that are currently assigned.

You can find more information about QEMU monitor and GDB debugger here, feel free to explore them.

Xv6 on your own Linux system

While we provide instructions for how to use Circinus machines, you are more than welcome to configure and run Xv6 on your own laptop, desktop, or VM. If you decide to use your own environment, see the instructions on the Xv6 tools page for how to set up Xv6.

I've successfully built Xv6 on my Ubuntu 14.04 LTS and later on Ubuntu 16.04 and 18.04 LTS. I had to install the following packages in order to build QEMU: libz-dev, libtool-bin, libtool, libglib2.0-dev, libpixman-1-dev, libfdt-dev.

Xv6 in Docker

In case you want to use run Xv6 on your own machine using docker containers, you can try it out as well. I have successfully built Xv6 using the grantbot/xv6 image hosted in the docker hub

In my local machine, I downloaded the Xv6 source code as follows:

Next, you will need to setup Docker, if you don't have it already on your machine. I followed the instructions from here.

You will find similar instructions for other OS as well in the docker website. Once you have the setup ready, download the grantbot/xv6 image using

Then you can start the container using

Once you have the bash prompt you can type the following to start Xv6: