Skip to content

Latest commit

 

History

History
128 lines (93 loc) · 3.68 KB

gdb-debugging.md

File metadata and controls

128 lines (93 loc) · 3.68 KB
Raw

GDB Debugging with Firecracker

The GDB feature is not for production use.

Firecracker supports debugging the guest kernel via GDB remote serial protocol. This allows us to connect GDB to the firecracker process and step through debug the guest kernel.

Prerequisites

Firstly, to enable GDB debugging we need to compile Firecracker with the gdb feature enabled, this will enable the necessary components for the debugging process.

To build firecracker with the gdb feature enabled we run:

cargo build --features "gdb"

Secondly, we need to compile a kernel with specific features enabled for debugging to work. The key config options to enable are:

CONFIG_FRAME_POINTER=y
CONFIG_DEBUG_INFO=y

For GDB debugging the gdb_socket_path option under machine-config should be set. When using the API the socket address must be set before instance start.

In this example we set the address to /tmp/gdb.socket in the config file:

{
  ...
  "machine-config": {
    ...
    "gdb_socket_path": "/tmp/gdb.socket"
    ...
  }
  ...
}

Using the API the socket address can be configured before boot like so:

sudo curl -X PATCH --unix-socket "${API_SOCKET}" \
  --data "{
    \"gdb_socket_path\": \"/tmp/gdb.socket\"
  }" "http://localhost/machine-config"

Starting Firecracker with GDB

With all the prerequisites in place you can now start firecracker ready to connect to GDB. When you start the firecracker binary now you'll notice it'll be blocked waiting for the GDB connection. This is done to allow us to set breakpoints before the boot process begins.

With Firecracker running and waiting for GDB we are now able to start GDB and connect to Firecracker. You may need to set the permissions of your GDB socket E.g. /tmp/gdb.socket to 0666 before connecting.

An example of the steps taken to start GDB, load the symbols and connect to Firecracker:

  1. Start the GDB process, you can attach the symbols by appending the kernel blob, for example here vmlinux

    gdb vmlinux

  2. When GDB has started set the target remote to /tmp/gdb.socket to connect to Firecracker

    (gdb) target remote /tmp/gdb.socket

With these steps completed you'll now see GDB has stopped at the entry point ready for us to start inserting breakpoints and debugging.

Notes

Software Breakpoints not working on start

When at the initial paused state you'll notice software breakpoints won't work and only hardware breakpoints will until memory virtualisation is enabled. To circumvent this one solution is to set a hardware breakpoint at start_kernel and continue. Once you've hit the start_kernel set the regular breakpoints as you would do normally. E.g.

> hbreak start_kernel
> c

Pausing Firecracker while it's running

While Firecracker is running you can pause vcpu 1 by pressing Ctrl+C which will stop the vcpu and allow you to set breakpoints or inspect the current location.

Halting execution of GDB and Firecracker

To end the debugging session and shut down Firecracker you can run the exit command in the GDB session which will terminate both.

Known limitations

  • The multi-core scheduler can in some cases cause issues with GDB, this can be mitigated by setting these kernel config values:

      CONFIG_SCHED_MC=n
  CONFIG_SCHED_MC_PRIO=n

  • Currently we support a limited subset of cpu registers for get and set operations, if more are required feel free to contribute.

  • On ARM the guest virtual address translation will only work on guests with 4kb pages and not all physical address sizes are supported. If the current translation implementation doesn't cover a specific setup, feel free to contribute.