Using qemu for 6.828
====================

1. Why?

 There are two main advantages to using qemu over bochs. First off, it
 is much faster, noticeably so. More interestingly, qemu has a mature
 and fully-functional gdb stub, which lets you do full source-level
 debugging of your operating system using gdb.

2. Caveats

 *Always test your code under bochs as well as qemu*

 qemu is a less faithful emulator in some way, and I have seen several
 instances of code that works properly under qemu but fails in bochs
 -- and in almost all of these cases, bochs was behaving in the way
 real hardware would.

3. HOWTO

 Running JOS under qemu is actually very easy. Just run:

 $ qemu -hda obj/kern/bochs.img -parallel /dev/stdout

 and JOS should boot and run fine under qemu.

3.1 Using qemu with gdb

 1. Add `-s -S' to your command line:

   $ qemu -s -S -hda obj/kern/bochs.img -parallel /dev/stdout

   This will cause qemu to boot and wait for a gdb connection before
   continuing.

 2. Launch gdb:

   $ gdb obj/kern/kernel

   You can also use gdb's `file' command to select a different binary
   to debug, once you hit labs 3 and 4 and have a userspace. Note that
   qemu and gdb don't know anything about user processes vs. kernel
   space, though, so if there are multiple processes running, figuring
   out which you're attached to a debugging a single one is tricky.

   If you're cross-compiling from a mac, you'll need a gdb that groks
   ELF.  Building gdb 6.8 with --target=i386-jos-elf should be
   sufficient, but you may need to patch gdb-6.8/gdb/Makefile by
   removing -Werror from WERROR_CFLAGS around line 145. I don't use
   Macs, but if you are having issues, you can try asking Evan Broder
   <broder@mit.edu>, who's made it work.

 3. Attach to qemu from gdb

   gdb> target remote localhost:1234

   You will now be connected to qemu, with full symbols loaded from
   the kernel ELF, and can set breakpoints, step through instructions
   and code, and generally use gdb as you'd expect. A gdb tutorial is
   beyond the scope of this document.

   Optionally, in order to get better debug symbols, replace the
   '-gstabs' in CFLAGS in GNUMakefile with just `-g'. Note that I
   believe you'll need to change this back for doing exercises that
   depend on the STABS debugging symbols, which I _think_ is only Lab
   1.

   Note that until you have paging set up in Lab 2, qemu may be
   confused and you may not be able to properly inspect code or set
   breakpoints, since qemu expects virtual memory to be set up in the
   code it's debugging.

4. Adding the filesystem

 Once you read Lab 5 and are building a filesystem as a second disk,
 you'll need to add `-hdb obj/fs/fs/.img' to your qemu command. As an
 example, here is a fragment of my modified GNUMakefile when I took
 the class:

<<<<<< CUT HERE >>>>>>
QEMUOPTS = -hda $(OBJDIR)/kern/bochs.img -hdb $(OBJDIR)/fs/fs.img -parallel /dev/stdout

qemu: $(IMAGES)
	qemu $(QEMUOPTS)

qemu-nox: $(IMAGES)
	qemu -nographic $(QEMUOPTS)

qemu-gdb: $(IMAGES)
	qemu -hda $(QEMUOPTS) -s -S

qemu-gdb-nox: $(IMAGES)
	qemu -nographic $(QEMUOPTS) -s -S
<<<<<< END CUT >>>>>>

Hope this helps someone.

- Nelson <nelhage@mit.edu>