7.1 i386-pc

The i386-pc target is a good place to start when first debugging GRUB2 because in some respects it’s easier than EFI platforms. The reason being that the initial load address is always known in advance. To start debugging GRUB2 first QEMU must be started in GDB stub mode. The following command is a simple illustration:

qemu-system-i386 -drive file=disk.img,format=raw \
    -device virtio-scsi-pci,id=scsi0 -S -s

This will start a QEMU instance booting from disk.img. It will pause at start waiting for a GDB instance to attach to it. You should change disk.img to something more appropriate. A block device can be used, but you may need to run QEMU as a privileged user.

To connect to this QEMU instance with GDB, the target remote GDB command must be used. We also need to load a binary image, preferably with symbols. This can be done using the GDB command file kernel.exec, if GDB is started from the grub-core directory in the GRUB2 build directory. GRUB2 developers have made this more simple by including a GDB script which does much of the setup. This file is at grub-core/gdb_grub in the build directory and is also installed via make install. When using a pre-built GRUB, the distribution may have a package which installs this GDB script along with debug symbol binaries, such as Debian’s ‘grub-pc-dbg’ package. The GDB script is intended to be used like so, assuming that ‘/path/to/script’ is the path to the directory containing the gdb_grub script and debug symbol files:

cd $(dirname /path/to/script/gdb_grub)
gdb -x gdb_grub

Once GDB has been started with the gdb_grub script it will automatically connect to the QEMU instance. You can then do things you normally would in GDB like set a break point on grub_main.

Setting breakpoints in modules is trickier since they haven’t been loaded yet and are loaded at addresses determined at runtime. The module could be loaded to different addresses in different QEMU instances. The debug symbols in the modules .module binary, thus are always wrong, and GDB needs to be told where to load the symbols to. But this must happen at runtime after GRUB2 has determined where the module will get loaded. Luckily the gdb_grub script takes care of this with the runtime_load_module command, which configures GDB to watch for GRUB2 module loading and when it does add the module symbols with the appropriate offset.