# Linux Kernel Module Cheat

### 23.8. Debug the emulator

When you start hacking QEMU or gem5, it is useful to see what is going on inside the emulator themselves.

This is of course trivial since they are just regular userland programs on the host, but we make it a bit easier with:

    ./run --debug-vm

Or for a faster development loop you can pass `-ex` command as a semicolon separated list:

    ./run --debug-vm-ex 'break qemu_add_opts;run'

which is equivalent to the more verbose:

    ./run --debug-vm-args '-ex "break qemu_add_opts" -ex "run"'

if you ever want need anything besides -ex.

Or if things get really involved and you want a debug script:

    printf 'break qemu_add_opts
    run
    ' > data/vm.gdb
    ./run --debug-vm-file data/vm.gdb

Our default emulator builds are optimized with `gcc -O2 -g`. To use `-O0` instead, build and run with:

    ./build-qemu --qemu-build-type debug --verbose
    ./run --debug-vm
    ./build-gem5 --gem5-build-type debug --verbose
    ./run --debug-vm --emulator-gem5

The `--verbose` is optional, but shows clearly each GCC build command so that you can confirm what `--*-build-type` is doing.

The build outputs are automatically stored in a different directories for optimized and debug builds, which prevents `debug` files from overwriting `opt` ones. Therefore, `--gem5-build-id` is not required.

The price to pay for debuggability is high however: a Linux kernel boot was about 3x slower in QEMU and 14 times slower in gem5 debug compared to opt, see benchmarks at: Section 35.2.1, “Benchmark Linux kernel boot”.

Similar slowdowns can be observed at: Section 35.2.2, “Benchmark emulators on userland executables”.

When in QEMU text mode, using `--debug-vm` makes Ctrl-C not get passed to the QEMU guest anymore: it is instead captured by GDB itself, so allow breaking. So e.g. you won’t be able to easily quit from a guest program like:

    sleep 10

In graphic mode, make sure that you never click inside the QEMU graphic while debugging, otherwise you mouse gets captured forever, and the only solution I can find is to go to a TTY with `Ctrl-Alt-F1` and `kill` QEMU.

You can still send key presses to QEMU however even without the mouse capture, just either click on the title bar, or alt tab to give it focus.

- Reverse debug the emulator

- Debug gem5 Python scripts