Development Environment

The required software for the Lab has been installed on Ubuntu Linux 22.04 (make sure to pick this one when switching on a machine) in the APB PC pools including room APB/E040. Of course, you can also work on the tasks on your own computers. You can either work in a pre-configured VirtualBox VM image we provide on the downloads page. Alternatively, you will find some hints on how to configure your own Linux installation below. Note that we only support Linux, although you may get WSL to work.

Since bugs can creep in during operating-system development from time to time, you have to test your solutions before you submit them. We use the emulator QEMU for this, using other emulators like Bochs is also possible.

OOStuBS on Ubuntu 22.04 LTS (x86-64) in the APB PC pools

We will use the pre-installed tools (compiler, linker etc.) of the host system (Linux). You don't have to pay attention to anything special.

OOStuBS in our VirtualBox VM

The VirtualBox VM image we provide on the downloads page is accompanied by a PDF with setup instructions and boots into a Debian Linux 11 installation with all necessary tools preinstalled.

OOStuBS on your own machine

In these instructions, we assume an x86-64 Linux (sometimes also referred to as x64 or amd64) that contains reasonably recent versions of the programs mentioned below from 2015 or later, and have only tested the commands on such systems. You can probably get OOStuBS to work on WSL, MacOS X, BSD or i386 Linux with a few changes – we're always happy to receive feedback and patches.
For compiling OOStuBS you need gcc and g++ (for C and C++) and the Netwide Assembler (NASM) (for assembler files). Additionally you need GNU make.
For generating a bootable and emulatable system, we use the GRand Unified Bootloader (GRUB). This requires the programs grub-mkrescue, mformat (from GNU mtools) and xorriso.
For local testing you also need the QEMU emulator (more specifically: qemu-system-x86_64). The GDB debugger (version 10 or newer works fine) is necessary if you want to look into your OS's internal state.
On Debian or Ubuntu machines, these requirements are fulfilled by installing the following packages via "sudo apt install ...":
nasm qemu qemu-system-x86 qemu-kvm build-essential binutils gcc-multilib g++ g++-multilib grub-common grub-pc-bin mtools xorriso

Setup

Regardless of where you want to develop OOStuBS, you first need the operating-system kernel and the Makefile. These are included in the template code from the Git repository that you need to clone:

$ git clone https://os.inf.tu-dresden.de/Studium/OSC/SS2023/oostubs.git
$ cd oostubs

Now you are ready to go: You can edit OOStuBS with a text editor or IDE of your choice, compile, and test. However, as long as you haven't implemented anything, you won't see a lot happening besides a few lines of BIOS startup output.

If you want to work on the next task, you have to add the new template files coming with it to your repository. You can use git pull to do this. If you are behind schedule and need an older template first, use git fetch followed by e.g. git merge task2. Note that before using either git pull or git merge, all your local changes must already have been committed.

Developing OOStuBS

When building OOStuBS, a lot of different C, C++ and assembler files are compiled and linked to one system file. This file is subsequently used to create a bootable and emulatable system image with GRUB.

The Makefile from the template repository provides targets to use this system image in several different ways. We won't document all of them here (read the Makefile!). If you want to know what a particular target does behind the scenes, add VERBOSE= to your make command, for example:

$ make VERBOSE= qemu

Building OOStuBS

It suffices to run make to build OOStuBS. This generates two important output files:

build/system is the linked operating system in the ELF64 format. This file can be loaded and started by Multiboot-capable emulators and boot loaders, and be used by a debugger to analyze a running OOStuBS system. (But: QEMU only supports 32-bit Multiboot and therefore cannot start this ELF64 binary by itself.)
build/bootdisk.iso is an image created by grub-mkrescue, which contains the GRUB boot loader and the OOStuBS system binary described above. This image can be used for testing on real hardware using a CD/DVD, a hard disk or an USB stick, or in an arbitrary x86-64 emulator.

Testing and Debugging in an Emulator

For testing, the created system image can be executed with QEMU. For this you only have to type make qemu. If you have changed source code before, it will be recompiled first and the image will be updated – so make qemu is sufficient and has the same effect as make; make qemu.
If you are working on the multi-processor variant MPStuBS, you should use make qemu-smp, which emulates a system with two CPUs. (In fact, you also can start OOStuBS this way, the second CPU will then simply be ignored.)
If you are hunting a bug and get stuck, debugging with GDB is a good option. To do this, you should first start QEMU with an active GDB stub using make qemu-gdb, and then connect to it in a second terminal using make gdb (or one of the other debuggers described in the Makefile). As soon as the connection is established, you can start the emulation using the GDB command c (short for continue), interrupt it pressing CTRL-C, and inspect the system state with GDB commands like bt (short for backtrace), print kout.buffer or print (Thread)bellringer.head to see what the system is doing.
You can read up on how the debugger can be used in detail in the GDB documentation. We will also look into this in one of the exercises. If you want a more comfortable debugging experience, you can use one of the many GDB frontends out there; for two of them, we offer Makefile targets.

Testing on Real Hardware

The submission of each task includes a demonstration on real PC hardware in the pool room. For this you need a USB stick that is either used exclusively for OOStuBS or has been set up with GRUB for parallel use for OOStuBS and as a storage medium.

With the exclusive variant, all data on the stick are lost. There is a separate make target for this, but you must specify the device to be used (for example /dev/sdb if your machine has one mass storage device): make DRIVE_HD=/dev/sdb bootdisk. You can figure out which device your USB stick belongs to e.g. with lsblk or dmesg. Note that this method usually requires root permissions and is not available on the pool machines.
ATTENTION: Using the wrong DRIVE_HD target might overwrite the wrong mass-storage media, resulting in data loss.

A more versatile variant is to install GRUB on your USB stick (only necessary once, with elevated / root permissions necessary) and use it to load the OOStuBS image. This requires a stick with a classic ("msdos" / "dos") partition table and a FAT32-formatted partition. Note that the following instructions have only been tested with the BIOS version of GRUB (grub-pc). For EFI systems with grub-efi, other steps may be necessary.

For the initial setup, the stick must be mounted e.g. in /mnt. Now the boot loader can (with root privileges) be installed permanently on the USB stick via grub-install -d /usr/lib/grub/i386-pc --boot-directory=/mnt /dev/sdb. Again, the correct device file (in this example /dev/sdb) must be specified. Ask the Lab personnell if you need assistance with this step.
Then a configuration must be created under grub/grub.cfg to tell the boot loader which image to load. A basic configuration for task 1 is available here. This assumes that the file build/system is on the stick as oostubs/task1.elf. To be able to load further tasks, additional menu entries must be created. This way you can continue to use your USB stick as a mass storage device and also switch between the different versions of OOStuBS.