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:
Clone the QEMU git repository
git clone http://debug.cs.columbia.edu/qemu.git
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.
- 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:
- 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.
- make qemu-nox
Run xv6 without the VGA console.
- make qemu-gdb
Run xv6 with GDB port open. Refer to the GDB section.
- 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:
- Run xv6 with GDB port open
make qemu-nox-gdbdepending on whether you want the VGA console.
- Run GDB with the kernel binary
gdb kerneland 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.
- Ctrl-C (when in execution)
Halt the execution and break into GDB at the current instruction.
Continue execution to the next breakpoint, or till the next Ctrl-C.
Step in, execute one instruction and halt.
- b *addr
Set a breakpoint at EIP address addr. EIP addresses can be found in .asm files.
- b func
Set a breakpoint at function of name func.
- b file:N
Set a breakpoint at line N of source code file.
- info registers
Print the general purpose registers, eip, eflags, and the segment selectors. For more detailed result use info registers in the QEMU monitor.
- x/Nx addr
Dump in hex N words starting at virtual address addr.
- x/Ni addr
Display N assembly instructions starting at virtual address addr.
- symbol-file file
Switch to symbol file file.
- set print pretty
Print arrays and structs in a pretty easy-to-read format.
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:
- xp/Nx paddr
Dump in hex N words starting at physical address paddr.
- info registers
Display a full detailed dump of registers.
- info mem
Display the page table in a compact form.
- info pg
Display the current page table structure. Different from info mem, this command distinguishes between PDE and PTE. Unbroken sequences of PDE's or PTE's with identical permissions are compressed into a single line. This command is added by MIT folks.
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.