/Teaching/Operating Systems/Tutorials/Debugging the SWEB-Kernel with cgd

Debugging the SWEB-Kernel with cgd

  1. sudo apt-get install cgdbto install cgdb
  2. make debug
  3. make
  4. make qemugdb
  5. Open a second command line and run make runcgdb (or another debugger you’re preferring make runddd / make rungdb / …)

Wenn diese Befehle nicht funktionieren:

  • in the directory utils/gdb/gdbinitthere is a useful gdbinit File.
  • gdb -nx -x utils/gdb/gdbinit -r ../sweb-bin/kernel.x. -nx results in gdb not executing .gdbinit (optional).

Ahhh! How do I get rid of the debug information?

  • simply run make x86_64

SWEB debugging locking errors debugging

Debugging locking errors with a debugger is much more difficult than without it. This is due to different timings when executing the binary. But there is a different possibility to debug locks by using debug()-statements. However, Thomas Malcher, wrote an add-on for gdb to apply the so-called Locktree-algorithm onto mutexes in SWEB. Further research has to be done on the efficiency evaluation of this algorithm. Nevertheless, it’s worth a try. Further details can be found on this page in the materials: Debugging SWEB with GDB Lock Tree

Using Eclipse CDT debugger

  1. Compiling the whole project (cmake . and make) (this is to assure that the compiled kernel image is in the sweb-bin folder)
  2. Create a new debug configuration (Debug as) in Eclipse: “C/C++ Remote Application” with the following settings:
    • Main:
      • C/C++ Application: …/sweb-bin/kernel.x (choose with browse)
      • Disable auto build
      • Debugging Launcher: GDB (SDF) Manual Remote Debugging Launcher
    • Debugger:
      • Stop on startup at: startup
      • Connection: TCP / localhost / 1234
    • Common:
      • Display in favorites menu: Debug
  3. run make qemugdb in the terminal
  4. now debug with the debug configuration chosen in eclipse before
  5. Choose the appropriate resolution in the grub startup menu

Eclipse would stop the execution of the kernel-image at the startup function in the file /sweb/common/source/kernel/main.cpp if set up correctly.  This specific breakpoint can be changed in your debug configuration if you want to use different or additional breakpoints.

The demo video can be found here: http://www.youtube.com/watch?v=TXbgYE-lRCU

Debugging using VSCode

If you already know how to debug using VSCode, just get the zipfile and you should be good to go (just make sure your /tmp/sweb folder is empty or does not exist):

vscode – debug config


  • Download the .vscode folder, put it into your source code root folder (the one that contains README.md and the arch, common, userspace folders) (Hint: You have to enable ‘show hidden files‘, on linux systems, files starting with ‘.’ are usually hidden by default)
  • Your folder structure should now look something like this: bs23a1/.vscode/settings.json (repository folder name will vary, the .vscode folder contains settings, tasks and launch).
  • Install the extensions “C/C++” and “CMake Tools” if you have not done so already.
  • In VSCode, open your sweb, more specifically the source code root folder.
  • The debug config pauses qemu before starting sweb by default. If you do not need to debug the boot process, you can for example remove the -S (upper case) flag from arch/x86/64/CMakeLists.include in the lines after add_custom_target(qemugdb.
  • In Scheduler.cpp, add a breakpoint in line 52, at the break; statement just after the currentThread = *it; line. You can do so by clicking to the left of the line number. There should now be a little red circle to the left of the line number.
  • Make sure your /tmp/sweb folder is empty or does not exist.
  • Press F5, or alternatively from the menu: Run->Start Debugging.
  • VSCode may complain on the first debug run with a popup, you can probably just press ‘cancel’ and debug anyway.
  • The qemu window with sweb should now appear, select the first boot entry.
  • VSCode should now display line 52 in yellow color (meaning the program flow is halted at that line).
  • Open the debug menu on the left (the one with the little bug symbol), click the ‘+‘ symbol in the ‘watch‘ tab.
  • In the field that opens, write ‘currentThread‘, press enter.
  • It should now write an address next to currentThread, and if you click on it it should show you all members and their current values for currentThread.
  • On the bottom, the tab ‘Debug Console’ displays gdb output, where you can also use gdb commands, like “-exec info registers”.
  • On the bottom, switch to the tab ‘Terminal‘ and then on the right side, switch to ‘Task‘ to see the sweb debug output. You can open both the debug console and the sweb debug output side-by-side, just drag the fields to where you would like them.
  • To restart, close the qemu window or press ctrl+c in the ‘Task’ Terminal, then press F5 again.

Some tips:

  • If your IntelliSense is not working, press ctrl+shift+p and run “CMake: Build“. If cmake asks for a kit, select “gcc-9” or similar. If it asks you which task it should use, select “build dbg sweb“.
  • Don’t have a flag called ‘DEBUG’ in your debug.h file (make will complain when you try to compile).

Debugging using Clion

Setup to use the debugger:

  • Build your SWEB as it is described here. Make sure there is a file called kernel64.x in your build directory (normally, the build directory is /tmp/sweb).
  • Open Clion in your project directory
  • In Clion go to Run -> Edit Configurations... -> Add New Configuration(the ‘+’ in the top left corner)
  • Select Remote Debug. After that, the configuration dialogue opens
  • Give your debug configuration a name (for example debug_sweb)
  • In 'target remote' args the IP address of the remote debugger needs to be passed. Insert here.
  • In symbol file pass the path to the kernel64.x file. (for example: /tmp/sweb/kernel64.x)
  • Click on apply

Now the setup should work and you can start debugging. Add the breakpoints to your code you want to observe. Then execute the commands

  1. make debug
  2. make -j
  3. make qemugdb

in /tmp/swebin order to start Qemu in debugging mode, in which it waits for the Clion debugger to connect. This is indicated by the line Guest has not initialized the display (yet).which is printed in Qemu. In the next step, start the debugger in Clion by selecting the previously created debug configuration and clicking on the bug icon. After that, the set breakpoints will stop the program execution once they are hit and you can continue with ordinary debugging. The rest (how to single-step, step-into, etc.) is self-explaining or you can look it up on the internet.