WeensyOS

This is WeensyOS, a teaching operating system built for Harvard’s CS 61.

Quickstart: make run will run the OS using the QEMU emulator.

make run will run the OS. On Docker, the OS will run in your terminal window; on a Linux virtual machine, QEMU will open a new window. (make run-console will run the OS in the terminal window on any OS.)

To exit the OS, type q into the terminal or QEMU window. Since this requires a semi-functioning kernel, it might not work for you; see Troubleshooting for other ways to kill the OS.

WeensyOS creates a debug log in log.txt. Run make LOG=stdio run to redirect the debug log to the standard output, or make LOG=file:FILENAME run to redirect it to FILENAME.

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

Finally, run make clean to clean up your directory.

Linux: WeensyOS should build natively on a Linux machine or virtual machine. qemu packages are required to run WeensyOS; on Ubuntu, sudo apt install qemu qemu-system-x86 should work. A recent compiler is required. You can use Clang, but only version 5 or later.

Mac OS X: WeensyOS can build on Mac OS X after some tools are installed.

1. Install Homebrew.

2. Install Homebrew’s new GCC package: brew install gcc

3. Install Homebrew’s QEMU: brew install qemu

4. Tap Sergio Benitez’s collection of cross-compilers: brew tap SergioBenitez/osxct

5. Install the x86_64-unknown-linux-gnu cross-compiler toolchain: brew install x86_64-unknown-linux-gnu

6. Create a file config.mk in this directory containing this:

   CCPREFIX=x86_64-unknown-linux-gnu-
   HOSTCC=gcc-12
   HOSTCXX=g++-12

   (Do not git add config.mk: it is intended for local configuration.)

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

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

• Open another terminal, change into the WeensyOS directory, and run make stop to stop all running QEMUs. If you are using Docker, you will need to enter Docker via ../cs61-run-docker before running make stop.

• If QEMU is running in a terminal window (in Docker, for instance), then press Alt-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 Terminal > Preferences > Keyboard and select “Use Option as Meta key”. You can also configure a special keyboard shortcut that sends the Escape 2 sequence.

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/weensyos.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.

Real operating systems are big. We have tried to boil down this OS to a minimum, comment it to help you, and separate x86-64 specifics from more fundamental issues.

The main output of the build process is a disk image, weensyos.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.