All necessary tools required for the exercises (and thus for the development of StuBS) are installed in the IRB Pool as welll as the sys student server mars.cs.tu-dortmund.de. However, the first ones only offer KVM-enabled qemu when locally signed in.

Of course you can also work on the assignments at home, we therefore recommend using an up-to-date Linux. Below are some hints on how to configure your Linux system accordingly.

In addition, the script setup-env.sh will help you checking the requirements and setting up a passwordless SSH connection for working at home.

Attention: If you want to install the software at home, you are (of course) fully responsible for all problems. Issues on your private system are no excuse for late submissions of the assignment.

Note: Since errors can sometimes sneak in during operating system development, you have to extensively test your solution before you hand it in. You can use an emulator (Qemu) and the dedicated StuBS test hardware (our reference platform) located in the sys lab (OH16, E07). The presentation of your solution is done on the test hardware, a solution only running in an emulator is not sufficient!

Requirements

To build StuBS, the C++ source files are compiled using g++ from a current GCC (version > 7) as specified in the Makefile, however The LLVM C++ compiler clang++ can be used as well. Startup code and hardware-related subprograms written in assembly are translated using the Netwide Assembler (nasm). The x86 emulator Qemu is suitable for preliminary testing and, thanks to a built-in debug stub, also for debugging with the GNU Debugger (gdb).

Skeleton / Source Code Management

We provide a skeleton for StuBS, with the basic boot code. This is available via git repository in our Gitea.
```
git clone https://git.cs.tu-dortmund.de/BSB-WS22/gruppe-xx.git stubs
```
For the remaining exercises we will update your master branch for each task successively - these changes usually contain new files for the exercise.
A short overview of the git commands can be found here. For a deeper introduction to distributed source code management we recommend the Pro Git book, available under the Creative Commons license.

Building StuBS

The files you receive from us should usually compile without an error, but contain incomplete code and are therefore missing the required functionality. You have to complete code in the functions and classes according to the documentation on this website.
You can start the actual building of StuBS by calling make in the projects root directory. All .cc and .asm files in this directory are then compiled with the appropriate tools (compiler or assembler) and linked together to a bootable system image. The commands make {kvm,qemu,netboot}{,-gdb}{-dbg,-opt,-noopt,-verbose} are available for testing and debugging.

The Makefile target help will give you a detailed overview about its capabilities.

smalloch@mars:~/oostubs> make help

MAKEFILE for the teaching operating system OOStuBS
--------------------------------------------------

Executing 'make' will compile the operating system from source.

All targets exist in different flavours in addition to <name>:
<name>-noopt, <name>-opt, <name>-dbg, and <name>-verbose.
Targets suffixed with -noopt are compiled without optimizations,
-opt targets produce a highly optimized binary, while
-dbg targets only use optimizations not hindering debugging.
Targets suffixed with -verbose generate binaries including
verbose output (via DBG_VERBOSE), making such targets useful for
debugging.
To get a verbose make output, clear VERBOSE, e.g. make VERBOSE=.
The following targets are available (each target can be suffixed
by -noopt  and -verbose):

  all      Builds OOStuBS, generating an ELF binary

  qemu     Starts OOStuBS in QEMU
           Due to the internal design of QEMU, some things
           (especially race conditions) might behave
           different compared to hardware!

  qemu-gdb Starts OOStuBS in QEMU with internal GDB stub and
           attaches it to a GDB session allowing step-by-step
           debugging

  kvm      Starts OOStuBS in KVM, a hardware-accelerated
           virtual machine

  kvm-gdb  Same as qemu-gdb, but with hardware acceleration

  iso      Generates a bootable system image
           (File: .build/stubs.iso)

  qemu-iso Starts the system in QEMU by booting from the
           virtual CD drive

  kvm-iso  Same as qemu-iso, but with hardware acceleration

  usb      Generates a bootable USB mass-storage device;
           the environment variable USBDEV should point
           to the USB device

  cd       Generates a bootable CD; the environment variable
           should point to the CD writer

  lint     Checks the coding style using CPPLINT

  tidy     Uses Clang Tidy for a static code analysis

  netboot  Copies OOStuBS to the network share, allowing
           the test systems to boot your system
           Define the shell variable USERNAME to use a specific user.
           This is useful if your local username
           differs from the one on mars.

Apart from the above targets that run your implementation,
our solution can be run in KVM (at least when called in the sys lab)
using the target

  solution-exercise

where exercise is the number of the exercise whose solution
should be executed.

Testing and Debugging StuBS

The fastest and easiest way to test your implementation is to run your system image in Qemu with hardware virtualization:
```
smalloch@mars:~/oostubs> make kvm
```
The QEMU target will by default emulate a system with four cores. For the development of OOStuBS, this does not bother you, because the additional cores are simply ignored. For MPStuBS, only the acceleration provided with the KVM extension will makes your system run really parallel on multiple cores. Hence, this is quite close to the test on real hardware in terms of race conditions and faulty synchronization. If, however, hardware virtualization is not available, please use QEMU:
```
smalloch@mars:~/oostubs> make kvm
```
To simplify troubleshooting, hardware virtualization can also be disabled by using the make qemu command instead. In this mode the guest system is only emulated pseudo-parallel, which makes it easier to find more serious bugs, but on the other hand it might mask existing ones that otherwise only occur with make kvm or on real hardware.
If you get stuck with simple printf debugging, you can use the debug stub integrated in Qemu and connect a debugger (e.g., gdb) to the emulation. This allows you to easily run your operating system code step by step, easing the detection of the reason for crashes or unwanted behavior. For this purpose the Makefile provides the targets qemu-gdb and kvm-gdb (which can be appended with -dbg for a debug build):
```
smalloch@mars:~/oostubs> make qemu-gdb
```
In this configuration, the Qemu debug stub waits in the emulator for a socket connection through which a gdb debugger can connect. The debugger will automatically be started so that the gdb prompt appears in the terminal immediately after Qemu is started. For remote debugging on mars via SSH, please use a different make target: make qemu-gdb-tmux. It will start a tmux session with four windows. One for GDB, one for QEMU, one for the QEMU monitor, and finally one for the serial console.
A brief reference of the GDB functions can be found here. If you want detailed instructions on how to use a specific GDB command, you can use the built-in help function in GDB:
```
(gdb) help <command>
```
Attention
Since Qemu pauses the operating system when using the debug stub, the program execution in gdb must not be restarted with run, but must be continued with continue instead.
For a faster overview of the register and stack contents, we recommend to store this gdbinit under the name .gdbinit in your own home directory.
To test your operating system on the reference hardware in the sys lab, just use the Makefile target netboot:
```
smalloch@mars:~/oostubs> make netboot
```
This will compile your StuBS and copy the system image to the TFTP server so that the test hardware can access it with the help of the network boot loader PXELinux. The test hardware automatically boot from the network when they are switched on. In the boot menu that appears, you only have to select the current semester and then the entry with your login name to boot your kernel. You can override the username used by our Makfile when working on your own machine:
```
al@ganymed:~/oostubs> USERNAME=smalloch make netboot
```
Note
During the exercises, please don't allocate the hardware for too long. After you've finished testing, please reboot the system.
You can access the hardware via the web interface with the user and password from the lecture. You can start the hardware using the management overview:

StuBS Hardware Managment web site

Turn on the desired machine, and click on the corresponding link KVM next to the power buttons.
Attention
Try to coordinate access to the test computers with your fellow students using the Matrix channel #bsb-helpdesk.fachschaften.org so that no one is interrupted while testing.

StuBS VNC web client

If you have setup a passwordless SSH login (using a key) on mars, you can even use the Makefile target netboot from your private PC after adjusting the variable NETBOOTSSH in the tools/remote.mk.

If you want use the serial console, click on the serial link next to your machine. That will open a dedicated website that allows interaction with the console:

StuBS Serial Console
The default behavior of the default build system is to use optimization level -O3, however the resulting machine code can make debugging much more difficult on persistent bugs. For these cases, all the Makefile targets above are also available with the suffix -dbg (use -Og, which enables only optimizations not interfering with debugging) and -noopt (which completely disables the compiler optimizations with -O0):
```
smalloch@mars:~/oostubs> make qemu-gdb-dbg
```
And – if nothing works – always remember: Don't Panic. Grep some coffee, take a break and then read your code again. Every bit can be crucial. Don't worry, debugging is an essential part in operating system development (like swearing).

Automatic formatting, auto-completion and error checking

If you want the amenities of a full IDE, you can install the ClangD language server. It is included as a package in many Linux distributions (Debian/Ubuntu: clangd). It works with both C and C++ and will automatically notify your editor of choice about errors, format the source code before saving and offer auto-completion for classes and functions. The installation setup is provided on the documentation website and also listed here for Visual Studio Code
1. Install the clangd plugin from the extension marketplace within VS Code.
2. Open the VS Code settings (shortcut: Ctrl + ,)
3. Set the option Editor: Default Formatter to clangd
4. It is highly recommended to also enable Editor: Format on Save
ClangD requires a few configuration files: .clangd (general setup) and .clang-format (style guide rules) and an index called compile_commands.json (files related to building the project). These configuration files have to be located in the root directory of your project. A minimal .clangd configuration would look like this:
```
CompileFlags:
  Add: [-xc++, -Wall -std=c++11]  # Flags passed to the compiler
  Remove: -W*                     # strip all other warning-related flags
  Compiler: clang++               # The invoked compiler (only for diagnostics!)

InlayHints:                       # Type hints for variables and function parameters
  Enabled: Yes
  ParameterNames: Yes
  DeducedTypes: Yes
```
This will enable a basic feature set that should be enough for most projects. For a full list of features, check out the documentation.
Clang-format's style guide can be written either from scratch or generated for you by invoking the clang-format binary (usually included in the clang package for most distributions):
```
$ clang-format -style=Google -dump-config > .clang-format
```
This will create a file based on the Google styling rules that you then can edit afterwards. A full list of options can be found in the documentation. You will only need the clang-format binary for creating the style guide. Afterwards, ClangD will handle the formatting (clang-format is already included).
Lastly, ClangD needs to have a compilation database in order to know which files are needed for building a project. There are several ways generate this index, based on the build system in use. For Makefile-based projects like StuBS, you need a separate program called bear to generate this (Debian/Ubuntu: package name is bear). Creating the database is straightforward: Just call:
```
$ bear -- make <target>
```
in the root directory. You may need to run make clean first if you already built the target prior. This is necessary because make will otherwise skip over already existing build files. Afterwards, compile_commands.json will include all files that were built or referenced during the make call.
You should now have auto-completion suggestions while typing, type annotations/documentation while hovering over a symbol name and live error-checking.
A sample configuration for .clangd and .clang-format for the StuBS project is provided in the directory src/.