You’ll use two sets of tools in this class: an x86 emulator, QEMU, for running your kernel; and a compiler toolchain, including assembler, linker, C compiler, and debugger, for compiling and testing your kernel. This page has the information you’ll need to download and install your own copies. This class assumes familiarity with Unix commands throughout.
It should be possible to get this development environment running under windows with the help of Cygwin. Install cygwin, and be sure to install the flex and bison packages (they are under the development header).
Using a Virtual Machine¶
Otherwise, the easiest way to get a compatible toolchain is to install a modern Linux distribution on your computer. With platform virtualization, Linux can cohabitate with your normal computing environment. Installing a Linux virtual machine is a two step process. First, you download the virtualization platform.
- Download and install Virtualbox/Vagrant
- Download and install the latest version of virtualbox
- Download and install the latest version of vagrant
- (Windows only, as ssh client) Download and install git
- Ubuntu users may also use the following commands to get virtualbox and vagrant.
[host] $ apt-get install virtualbox [host] $ apt-get install vagrant
It is optional to use vagrant for our labs. You can use virtualbox only.
If you decide to use virtualbox only.
- you could download Ubuntu desktop here like ubuntu-16.04.3-desktop-i386.iso
- Start up your virtualization platform and create a new (32-bit) virtual machine. Use the downloaded Ubuntu image as a boot disk
- Follow all steps that described below except vagrant parts.
- Add guest OS and run the VM (Vagrant users only)
# clone our handy Vagrant repository [host] $ git clone email@example.com:cs3210-fall2017/cs3210-vagrant.git [host] $ cd cs3210-vagrant [host] $ vagrant up [host] $ vagrant ssh
- Once you have the VM up and running, initialize your VM for this course:
[VM] $ mkdir ~/cs3210 [VM] $ cd ~/cs3210
- If you haven’t previously, create an ssh key and upload it to github.gatech.edu by following the instructions here: https://help.github.com/articles/generating-an-ssh-key/. Then clone your repo replacing YOUR-USERNAME with your github username.
# it's time for setting up your environment [vm] $ git clone firstname.lastname@example.org:cs3210-fall2017/cs3210-lab-YOUR-USERNAME lab Cloning into lab... $ cd lab
- Most GNU/Linux distributions have simple installation processes based on package repositories. It is often best to use the repository approach for installing QEMU, as you can be confident that it will just install and run.
[VM] $ apt-get install qemu libvirt-bin
Compilation from the source
- You might prefer to install QEMU by compiling the source code, which is available on the QEMU website
- First you must decompress the sources:
[VM] $ cd /tmp [VM] $ tar -zxvf qemu-x.y.z.tar.gz [VM] $ cd qemu-x.y.z
- Configure QEMU and build it
[VM] $ ./configure [VM] $ make
- Make to install QEMU in /usr/local
[VM] $ make install
Familiarity with your environment is crucial for productive development and debugging. This page gives a brief overview of the JOS environment and useful GDB and QEMU commands. Don’t take our word for it, though. Read the GDB and QEMU manuals. These are powerful tools that are worth knowing how to use.
If you’re getting unexpected interrupts, exceptions, or triple faults, you can ask QEMU to generate a detailed log of interrupts using the -d argument.
User environments (lab 3+)¶
GDB also lets you debug user environments, but there are a few things you need to watch out for, since GDB doesn’t know that there’s a distinction between multiple user environments, or between user and kernel.
You can symbolically debug user code, just like you can kernel code, but
you have to tell GDB which symbol table to use with the
symbol-file command, since it can only use one
symbol table at a time. The provided
.gdbinit loads the kernel
obj/kern/kernel. The symbol table for a user
environment is in its ELF binary, so you can load it using symbol-file
obj/user/name. Don’t load symbols from any
.o files, as those
haven’t been relocated by the linker (libraries are statically linked
into JOS user binaries, so those symbols are already included in each
user binary). Make sure you get the right user binary; library
functions will be linked at different EIPs in different binaries and GDB
won’t know any better!
(Lab 4+) Since GDB is attached to the virtual machine as a whole, it sees clock interrupts as just another control transfer. This makes it basically impossible to step through user code because a clock interrupt is virtually guaranteed the moment you let the VM run again. The stepi command works because it suppresses interrupts, but it only steps one assembly instruction. Breakpoints generally work, but watch out because you can hit the same EIP in a different environment (indeed, a different binary altogether!).
The JOS Makefile includes a number of phony targets for running JOS
in various ways. All of these targets configure QEMU to listen for GDB
*-gdb targets also wait for this connection). To
start once QEMU is running, simply run gdb from your lab directory. We
.gdbinit file that automatically points GDB at QEMU, loads
the kernel symbol file, and switches between 16-bit and 32-bit mode.
Exiting GDB will shut down QEMU.
- make qemu
- Build everything and start QEMU with the VGA console in a new window
and the serial console in your terminal. To exit, either close the
VGA window or press
Ctrl-a xin your terminal.
- make qemu-nox
make qemu, but run with only the serial console. To exit, press
Ctrl-a x. This is particularly useful over SSH connections to Athena dialups because the VGA window consumes a lot of bandwidth.
- make qemu-gdb
make qemu, but rather than passively accepting GDB connections at any time, this pauses at the first machine instruction and waits for a GDB connection.
- make qemu-nox-gdb
- A combination of the
- make run-name
- (Lab 3+) Run user program name. For example,
- make run-name-nox, run-name-gdb, run-name-gdb-nox,
- (Lab 3+) Variants of
run-namethat correspond to the variants of the
The makefile also accepts a few useful variables:
- make V=1 …
- Verbose mode. Print out every command being executed, including arguments.
- make V=1 grade
- Stop after any failed grade test and leave the QEMU output in
- make QEMUEXTRA=’args’ …
- Specify additional arguments to pass to QEMU.
When building JOS, the makefile also produces some additional output files that may prove useful while debugging:
- Assembly code listings for the bootloader, kernel, and user programs.
- Symbol tables for the kernel and user programs.
- Linked ELF images of the kernel and user programs. These contain symbol information that can be used by GDB.
See the GDB manual for a full guide to GDB commands. Here are some particularly useful commands for cs3210, some of which don’t typically come up outside of OS development.
- Halt the machine and break in to GDB at the current instruction. If QEMU has multiple virtual CPUs, this halts all of them.
- c (or continue)
- Continue execution until the next breakpoint or
- si (or stepi)
- Execute one machine instruction.
- b function or b file:line (or breakpoint)
- Set a breakpoint at the given function or line.
- b *addr (or breakpoint)
- Set a breakpoint at the EIP addr.
- set print pretty
- Enable pretty-printing of arrays and structs.
- info registers
- Print the general purpose registers,
eflags, and the segment selectors. For a much more thorough dump of the machine register state, see QEMU’s own
- x/Nx addr
- Display a hex dump of N words starting at virtual address addr. If N is omitted, it defaults to 1. addr can be any expression.
- x/Ni addr
- Display the N assembly instructions starting at addr. Using
$eipas addr will display the instructions at the current instruction pointer.
- symbol-file file
- (Lab 3+) Switch to symbol file file. When GDB attaches to QEMU, it
has no notion of the process boundaries within the virtual machine,
so we have to tell it which symbols to use. By default, we configure
GDB to use the kernel symbol file,
obj/kern/kernel. If the machine is running user code, say
hello.c, you can switch to the hello symbol file using
QEMU represents each virtual CPU as a thread in GDB, so you can use all of GDB’s thread-related commands to view or manipulate QEMU’s virtual CPUs.
- thread n
- GDB focuses on one thread (i.e., CPU) at a time. This command switches that focus to thread n, numbered from zero.
- info threads
- List all threads (i.e., CPUs), including their state (active or halted) and what function they’re in.
QEMU includes a built-in monitor that can inspect and modify the machine state in useful ways. To enter the monitor, press Ctrl-a c in the terminal running QEMU. Press Ctrl-a c again to switch back to the serial console.
For a complete reference to the monitor commands, see the QEMU manual. Here are some particularly useful commands:
- xp/Nx paddr
- Display a hex dump of N words starting at physical address
paddr. If N is omitted, it defaults to 1. This is the physical
memory analogue of GDB’s
- info registers
Display a full dump of the machine’s internal register state. In particular, this includes the machine’s hidden segment state for the segment selectors and the local, global, and interrupt descriptor tables, plus the task register. This hidden state is the information the virtual CPU read from the GDT/LDT when the segment selector was loaded. Here’s the CS when running in the JOS kernel in lab 1 and the meaning of each field:
CS =0008 10000000 ffffffff 10cf9a00 DPL=0 CS32 [-R-]
- The visible part of the code selector. We’re using segment 0x8. This also tells us we’re referring to the global descriptor table (0x8&4=0), and our CPL (current privilege level) is 0x8&3=0.
- The base of this segment. Linear address = logical address + 0x10000000.
- The limit of this segment. Linear addresses above 0xffffffff will result in segment violation exceptions.
- The raw flags of this segment, which QEMU helpfully decodes for us in the next few fields.
- The privilege level of this segment. Only code running with privilege level 0 can load this segment.
- This is a 32-bit code segment. Other values include
DSfor data segments (not to be confused with the DS register), and
LDTfor local descriptor tables.
- This segment is read-only.
- info mem
(Lab 2+) Display mapped virtual memory and permissions. For example,
ef7c0000-ef800000 00040000 urw efbf8000-efc00000 00008000 -rw
tells us that the 0x00040000 bytes of memory from 0xef7c0000 to 0xef800000 are mapped read/write and user-accessible, while the memory from 0xefbf8000 to 0xefc00000 is mapped read/write, but only kernel-accessible.
QEMU also takes some useful command line arguments, which can be passed into the JOS makefile using the QEMUEXTRA variable.
- make QEMUEXTRA=’-d int’ …
Log all interrupts, along with a full register dump, to
qemu.log. You can ignore the first two log entries, “SMM: enter” and “SMM: after RMS”, as these are generated before entering the boot loader. After this, log entries look like
4: v=30 e=0000 i=1 cpl=3 IP=001b:00800e2e pc=00800e2e SP=0023:eebfdf28 EAX=00000005 EAX=00000005 EBX=00001002 ECX=00200000 EDX=00000000 ESI=00000805 EDI=00200000 EBP=eebfdf60 ESP=eebfdf28 ...
The first line describes the interrupt. The
4:is just a log record counter.
vgives the vector number in hex.
egives the error code.
i=1indicates that this was produced by an
intinstruction (versus a hardware interrupt). The rest of the line should be self-explanatory. See info registers for a description of the register dump that follows.
Note: If you’re running a pre-0.15 version of QEMU, the log will be written to
/tmpinstead of the current directory.
Questions or comments regarding cs3210? Post to Piazza.