Spring 2012 -- Junfeng Yang

QEMU setup instructions

QEMU is a modern and fast PC emulator. Unfortunately, QEMU's debugging facilities, while powerful, are somewhat immature, so we highly recommend that you use version of QEMU patched by MIT folks instead of the stock version that may come with your distribution. To download and build your own patched version of QEMU on CLIC machines:

  1. Clone the QEMU git repository

    git clone http://debug.cs.columbia.edu/qemu.git

  2. Configure the source code

    ./configure [--prefix=PFX] [--target-list="i386-softmmu x86_64-softmmu"]

    The prefix argument specifies where to install QEMU; without it QEMU will install to /usr/local by default. Since you do not have root access on CLIC machines, set PFX to be inside your home directory, such as $PWD/install. The target-list argument simply slims down the architectures QEMU will build support for.

  3. Run make && make install

You may also install QEMU on your own machine. On Linux, you may need to install the SDL development libraries to get a graphical VGA window. On Debian/Ubuntu, this is the libsdl1.2-dev package. You can find out more information about the version of QEMU we're using here.

Running xv6 with make

The Makefile provided with xv6 has several phony targets for running the system:

  1. make qemu
    Build everything and run xv6 with QEMU, with a VGA console in a new window and the serial console in the terminal where you typed this command. Close the VGA window or press Ctrl-C or Ctrl-A X to stop.
  2. make qemu-nox
    Run xv6 without the VGA console.
  3. make qemu-gdb
    Run xv6 with GDB port open. Refer to the GDB section.
  4. make qemu-nox-gdb
    Run xv6 with GDB port open, without the VGA console.

GDB debug instructions

QEMU supports debugging with GDB. To debug with GDB:

  1. Run xv6 with GDB port open
     make qemu-gdb
     make qemu-nox-gdb
    depending on whether you want the VGA console.
  2. Run GDB with the kernel binary
     gdb kernel
    and GDB will automatically connect to the GDP port.

Refer to the GDB Manual for a complete instruction of GDB. Some commands are proved to be useful.

QEMU monitor

QEMU itself has a built-in monitor available to inspect and modify the machine state. Press Ctrl-A C in the terminal running QEMU to get into the monitor. Refer to the QEMU Manual for a complete instruction of QEMU monitor.

Some commands are pariticularly useful:

Remote access

You can work remotely by connecting to a CLIC machine via SSH. If you desktop runs Linux or MacOS, you should be able to instal an SSH client easily. For example, on Ubuntu, run

$ sudo apt-get install openssh-client

If your desktop runs Windows, you'll need to install two programs. First, you need an SSH client, such as the putty SSH client or Cygwin with the OpenSSH package. To get the GUI window working on your desktop, you also need an X server, such as the Xming X Server or the XWin32 Server. Configure your SSH client to forward X11 streams.


Git is a distributed version control software. We use git to distributed all kernel program assignments. To learn about Git, take a look at the Git user's manual, or, if you are already familiar with other version control systems, you may want to read this Git overview.