Chickadee OS

This is Chickadee, a teaching operating system built for Harvard’s CS 161.

Quickstart: make run or make run-PROGRAM will run the OS using the QEMU emulator.

Make targets

make NCPU=N run runs the OS with N virtual CPUs (default is 2). Close the QEMU window, or type q inside it, to exit the OS.

make run-console runs the OS in the console window.

make SAN=1 run runs with sanitizers enabled.

Chickadee’s debug log is written to log.txt by default. make LOG=stdio run redirects the debug log to the standard output, and make LOG=file:FILENAME run redirects it to FILENAME.

make D=1 run tells QEMU to print verbose information about interrupts and CPU resets to the file qemu.log. This setting will also cause QEMU to quit after encountering a triple fault (normally it will reboot).

make run-PROGRAM runs p-PROGRAM.cc as the first non-init process. The default is alloc.

make HALT=10 run-PROGRAM should make QEMU exit 10 centiseconds (0.1 sec) after all processes exit.

Chickadee process executables are built from files named p-*.cc. If a process source file starts with #define CHICKADEE_OPTIONAL_PROCESS 1, then it is included only on explicit request (e.g., make run-testforksimple).

Troubleshooting

There are several ways to kill a recalcitrant QEMU (for instance, if your OS has become unresponsive).

• If QEMU is running in its own graphical window, then close the window. This will kill the embedded OS.

• If QEMU is running in a terminal window (in Docker, for instance), then press Alt-2 (or Option-2). This will bring up the QEMU Monitor, which looks like this:

  compat_monitor0 console
  QEMU 4.2.0 monitor - type 'help' for more information
  (qemu)
  

  Type quit and hit Return to kill the embedded OS and return to your shell. If this leaves the terminal looking funny, enter the reset shell command to restore it.

  If Alt-2 does not work, you may need to configure your terminal to properly send the Alt key. For instance, on Mac OS X’s Terminal, go to the Edit menu, select “Use Option as Meta key”, and press Option-2. You can also configure a special keyboard shortcut that sends the Escape 2 sequence.

• Run make stop in another terminal. This will kill all QEMU processes you own. (If you’re using Docker, this other terminal must be open to the same Docker instance.)

Run make run-gdb to start up the OS with support for GDB debugging. This will start the OS, but not GDB. You must run gdb -ix build/chickadee.gdb to connect to the running emulator; when GDB connects, it will stop the OS and wait for instructions.

If you experience runtime errors involving obj/libqemu-nograb.so.1, put QEMU_PRELOAD_LIBRARY= in config.mk. This disables a shim we use that prevents QEMU from grabbing the mouse.

Source files

Common files

File	Description
types.h	Type definitions
lib.hh/cc	C library
x86-64.h	x86-64 hardware definitions
elf.h	ELF64 structures for loading programs

Boot loader

File	Description
bootentry.S	Boot loader entry point
boot.cc	Boot loader main code
boot.ld	Boot loader linker script

Kernel core

File	Description
kernel.hh	Kernel declarations
k-exception.S	Kernel entry points
k-init.cc	Kernel initialization
k-lock.hh	Kernel spinlock
k-vmiter.hh/cc	Page table iterators
k-cpu.cc	Kernel cpustate type
k-proc.cc	Kernel proc type
kernel.cc	Kernel exception handlers
k-memviewer.cc	Kernel memory viewer
kernel.ld	Kernel linker script

Kernel libraries

File	Description
k-memrange.hh	Memory range type tracker
k-hardware.cc	General hardware access
k-devices.hh/cc	Keyboard, console, memory files
k-apic.hh/cc	Interrupt controller hardware
k-pci.hh	PCI bus hardware
k-mpspec.cc	Boot-time configuration
k-sanitizers.cc	Sanitizer support

Processes

File	Description
u-lib.cc/hh	Process library and system call implementations
p-allocator.cc	Allocator process
process.ld	Process binary linker script

File system

File	Description
chickadeefs.hh	Defines chkfs (ChickadeeFS) layout
journalreplayer.cc	Logic for replaying chkfs journals

Build files

The main output of the build process is a disk image, chickadeeboot.img. QEMU “boots” off this disk image, but the image could conceivably boot on real hardware! The build process also produces other files that can be useful to examine.

File	Description
obj/kernel.asm	Kernel assembly (with addresses)
obj/kernel.sym	Kernel defined symbols
obj/p-PROCESS.asm, sym	Same for process binaries