|
| 1 | +WeensyOS |
| 2 | +======== |
| 3 | + |
| 4 | +This is WeensyOS, a teaching operating system built for Harvard’s |
| 5 | +[CS 61]. |
| 6 | + |
| 7 | +Quickstart: `make run` will run the OS using the [QEMU] emulator. |
| 8 | + |
| 9 | +Running the OS |
| 10 | +-------------- |
| 11 | + |
| 12 | +`make run` will run the OS. On Docker, the OS will run in your terminal |
| 13 | +window; on a Linux virtual machine, QEMU will open a new window. (`make |
| 14 | +run-console` will run the OS in the terminal window on any OS.) |
| 15 | + |
| 16 | +To exit the OS, type `q` into the terminal or QEMU window. Since this requires |
| 17 | +a semi-functioning kernel, it might not work for you; see |
| 18 | +[Troubleshooting](#troubleshooting) for other ways to kill the OS. |
| 19 | + |
| 20 | +WeensyOS creates a debug log in `log.txt`. Run `make LOG=stdio run` to |
| 21 | +redirect the debug log to the standard output, or `make |
| 22 | +LOG=file:FILENAME run` to redirect it to `FILENAME`. |
| 23 | + |
| 24 | +Run `make D=1 run` to ask QEMU to print verbose information about interrupts |
| 25 | +and CPU resets to the standard error. This setting will also cause QEMU to |
| 26 | +quit after encountering a [triple fault][] (normally it will reboot). |
| 27 | + |
| 28 | +Finally, run `make clean` to clean up your directory. |
| 29 | + |
| 30 | +Building |
| 31 | +-------- |
| 32 | + |
| 33 | +**Linux:** WeensyOS should build natively on a Linux machine or |
| 34 | +virtual machine. `qemu` packages are required to run WeensyOS; on |
| 35 | +Ubuntu, `sudo apt install qemu qemu-system-x86` should work. A recent |
| 36 | +compiler is required. You can use [Clang](https://clang.llvm.org/), |
| 37 | +but only version 5 or later. |
| 38 | + |
| 39 | +**Mac OS X:** WeensyOS can build on Mac OS X after some tools are installed. |
| 40 | + |
| 41 | +1. Install [Homebrew]. |
| 42 | + |
| 43 | +2. Install Homebrew’s new GCC package: `brew install gcc` |
| 44 | + |
| 45 | +3. Install Homebrew’s QEMU: `brew install qemu` |
| 46 | + |
| 47 | +4. Tap [Sergio Benitez’s collection of cross-compilers](https://github.com/SergioBenitez/homebrew-osxct): `brew tap SergioBenitez/osxct` |
| 48 | + |
| 49 | +5. Install the `x86_64-unknown-linux-gnu` cross-compiler toolchain: `brew install x86_64-unknown-linux-gnu` |
| 50 | + |
| 51 | +6. Create a file `config.mk` in this directory containing this: |
| 52 | + |
| 53 | + ```make |
| 54 | + CCPREFIX=x86_64-unknown-linux-gnu- |
| 55 | + HOSTCC=gcc-12 |
| 56 | + HOSTCXX=g++-12 |
| 57 | + ``` |
| 58 | + |
| 59 | + (Do not `git add config.mk`: it is intended for local configuration.) |
| 60 | + |
| 61 | +Troubleshooting |
| 62 | +--------------- |
| 63 | + |
| 64 | +There are several ways to kill a recalcitrant WeensyOS (if, for instance, your |
| 65 | +OS has become unresponsive). |
| 66 | + |
| 67 | +* If QEMU is running in its own graphical window, then close the window. This |
| 68 | + will kill the embedded OS. |
| 69 | + |
| 70 | +* Open another terminal, change into the WeensyOS directory, and run `make |
| 71 | + stop` to stop all running QEMUs. If you are using Docker, you will need to |
| 72 | + enter Docker via `../cs61-run-docker` before running `make stop`. |
| 73 | + |
| 74 | +* If QEMU is running in a terminal window (in Docker, for instance), then |
| 75 | + press `Alt-2`. This will bring up the QEMU Monitor, which looks like this: |
| 76 | + |
| 77 | + ``` |
| 78 | + compat_monitor0 console |
| 79 | + QEMU 4.2.0 monitor - type 'help' for more information |
| 80 | + (qemu) |
| 81 | + ``` |
| 82 | + |
| 83 | + Type `quit` and hit Return to kill the embedded OS and return to your |
| 84 | + shell. If this leaves the terminal looking funny, enter the `reset` shell |
| 85 | + command to restore it. |
| 86 | + |
| 87 | + If `Alt-2` does not work, you may need to configure your terminal to |
| 88 | + properly send the Alt key. For instance, on Mac OS X’s Terminal, go to |
| 89 | + Terminal > Preferences > Keyboard and select “Use Option as Meta key”. You |
| 90 | + can also configure a special keyboard shortcut that sends the `Escape 2` |
| 91 | + sequence. |
| 92 | + |
| 93 | +Run `make run-gdb` to start up the OS with support for GDB debugging. |
| 94 | +This will start the OS, but not GDB. You must run `gdb -ix |
| 95 | +build/weensyos.gdb` to connect to the running emulator; when GDB |
| 96 | +connects, it will stop the OS and wait for instructions. |
| 97 | + |
| 98 | +If you experience runtime errors involving `obj/libqemu-nograb.so.1`, put |
| 99 | +`QEMU_PRELOAD_LIBRARY=` in `config.mk`. This disables a shim we use that |
| 100 | +prevents QEMU from grabbing the mouse. |
| 101 | +
|
| 102 | +Source files |
| 103 | +------------ |
| 104 | +
|
| 105 | +Real operating systems are big. We have tried to boil down this OS to |
| 106 | +a minimum, comment it to help you, and separate x86-64 specifics from |
| 107 | +more fundamental issues. |
| 108 | +
|
| 109 | +### Common files |
| 110 | +
|
| 111 | +| File | Description | |
| 112 | +| --------------- | -------------------------------------- | |
| 113 | +| `types.h` | Type definitions | |
| 114 | +| `lib.hh/cc` | C library | |
| 115 | +| `x86-64.h` | x86-64 hardware definitions | |
| 116 | +| `elf.h` | ELF64 structures for loading programs | |
| 117 | +
|
| 118 | +### Boot loader |
| 119 | +
|
| 120 | +| File | Description | |
| 121 | +| ---------------- | ---------------------------- | |
| 122 | +| `bootentry.S` | Boot loader entry point | |
| 123 | +| `boot.cc` | Boot loader main code | |
| 124 | +| `build/boot.ld` | Boot loader linker script | |
| 125 | +
|
| 126 | +### Kernel core |
| 127 | +
|
| 128 | +| File | Description | |
| 129 | +| ------------------- | ------------------------------------ | |
| 130 | +| `kernel.hh` | Kernel declarations | |
| 131 | +| `k-exception.S` | Kernel entry points | |
| 132 | +| `k-hardware.cc` | Kernel initialization and hardware | |
| 133 | +| `k-vmiter.hh/cc` | Page table iterators | |
| 134 | +| `kernel.cc` | Kernel exception handlers | |
| 135 | +| `k-memviewer.cc` | Kernel memory viewer | |
| 136 | +| `build/kernel.ld` | Kernel linker script | |
| 137 | +
|
| 138 | +### Kernel libraries |
| 139 | +
|
| 140 | +| File | Description | |
| 141 | +| ------------------- | ------------------------------------ | |
| 142 | +| `k-apic.hh` | Interrupt controller hardware | |
| 143 | +| `k-pci.hh` | PCI bus hardware | |
| 144 | +
|
| 145 | +### Processes |
| 146 | +
|
| 147 | +| File | Description | |
| 148 | +| ------------------ | ------------------------------------------------ | |
| 149 | +| `u-lib.cc/hh` | Process library and system call implementations | |
| 150 | +| `p-*.cc` | Process code | |
| 151 | +| `build/process.ld` | Process binary linker script | |
| 152 | +
|
| 153 | +Build files |
| 154 | +----------- |
| 155 | +
|
| 156 | +The main output of the build process is a disk image, |
| 157 | +`weensyos.img`. QEMU “boots” off this disk image, but the image |
| 158 | +could conceivably boot on real hardware! The build process also |
| 159 | +produces other files that can be useful to examine. |
| 160 | +
|
| 161 | +| File | Description | |
| 162 | +| -------------------------- | ------------------------------------ | |
| 163 | +| `obj/kernel.asm` | Kernel assembly (with addresses) | |
| 164 | +| `obj/kernel.sym` | Kernel defined symbols | |
| 165 | +| `obj/p-PROCESS.asm`, `sym` | Same for process binaries | |
| 166 | +
|
| 167 | +[triple fault]: https://en.wikipedia.org/wiki/Triple_fault |
| 168 | +[CS 61]: https://cs61.seas.harvard.edu/ |
| 169 | +[QEMU]: https://qemu.org/ |
| 170 | +[Homebrew]: https://brew.sh/ |
0 commit comments