7 Debugging

GRUB2 can be difficult to debug because it runs on the bare-metal and thus does not have the debugging facilities normally provided by an operating system. This chapter aims to provide useful information on some ways to debug GRUB2 for some architectures. It by no means intends to be exhaustive. The focus will be one x86_64 and i386 architectures. Luckily for some issues virtual machines have made the ability to debug GRUB2 much easier, and this chapter will focus debugging via the QEMU virtual machine. We will not be going over debugging of the userland tools (eg. grub-install), there are many tutorials on debugging programs in userland.

You will need GDB and the QEMU binaries for your system, on Debian these can be installed with the ‘gdb’ and ‘qemu-system-x86’ packages. Also it is assumed that you have already successfully compiled GRUB2 from source for the target specified in the section below and have some familiarity with GDB. When GRUB2 is built it will create many different binaries. The ones of concern will be in the grub-core directory of the GRUB2 build dir. To aide in debugging we will want the debugging symbols generated during the build because these symbols are not kept in the binaries which get installed to the boot location. The build process outputs two sets of binaries, one without symbols which gets executed at boot, and another set of ELF images with debugging symbols. The built images with debugging symbols will have a .image suffix, and the ones without a .img suffix. Similarly, loadable modules with debugging symbols will have a .module suffix, and ones without a .mod suffix. In the case of the kernel the binary with symbols is named kernel.exec.

In the following sections, information will be provided on debugging on various targets using gdb and the ‘gdb_grub’ GDB script.