StuBS
|
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.
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
).
git clone https://git.cs.tu-dortmund.de/BSB-WS22/gruppe-xx.git stubs
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.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.
smalloch@mars:~/oostubs> make kvmThe 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
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.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-gdbIn 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.(gdb) help <command>
gdb
must not be restarted with run
, but must be continued with continue
instead..gdbinit
in your own home directory.netboot
: smalloch@mars:~/oostubs> make netbootThis 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
#bsb-helpdesk.fachschaften.org
so that no one is interrupted while testing.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, use vesta.cs.tu-dortmund.de
and the program serial
to connect to a serial port. First, connect to mars
via SSH, and then issue the following command: ssh smalloch@vesta.cs.tu-dortmund.de serial /dev/ttyBSB1You can do that in one command if you want:
ssh -J mars.cs.tu-dortmund.de smalloch@vesta.cs.tu-dortmund.de serial /dev/ttyBSB1In more detail: The hardware test machine is connected to the host
vesta.cs.tu-dortmund.de
. The interface /dev/ttyBSB1
, for example, is the interface for the first test system StuBS1
. The utility serial
simplifies the configuration of the connection settings (baud rate, parity & stop bits), run it without any arguments for detailed usage instructions.-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