Using a GNU debugger (GDB)

You can use GDB to better understand and debug a guest OS's activities inside its hypervisor VM (qvm process instance).

Currently supported GDB functionality includes:

break points
single-stepping
reading and writing to guest memory
reading and writing to vCPU registers
switching between vCPUs

For more information about using GDB in a QNX environment, see the “Using GDB” chapter in the QNX Neutrino OS 7.0 Programmers's Guide, and gdb in the QNX SDP Utilities Reference. For more information about GDB, see https://www.gnu.org/software/gdb/documentation/.

Enabling GDB in a qvm process instance

To use GDB, you must enable it in the qvm process instance (VM) hosting the guest you want to examine. To do this, specify the gdb option in the VM's *.qvmconf configuration file (see gdb in the “VM Configuration Reference” chapter). For example:

gdb 1234

Pausing

For the hypervisor host, the guest is a blob. Since the GDB monitor runs on the hypervisor host, it pauses the guest indirectly by pausing the guest's vCPU threads in its qvm process instance.

The gdb paused configuration option is used to configure guest OS behavior at guest startup.

If the option is not specified, the qvm process allows the guest OS to start and run until GDB connects to the port specified in the configuration. When GDB connects to its port, the qvm process causes the guest OS to pause.

If the option is specified (e.g., gdb paused 1234), the qvm process pauses the guest OS at the guest OS's first instruction. When the GDB server in the qvm process receives a single-stepping or continue command, it allows the guest OS to execute, according to the command.

GDB client versions

QNX Neutrino OS 7.0 includes GDB clients for all its supported hardware architectures. QNX hypervisors run 64-bit hardware, so you need one of either ntoaarch64-gdb (AArch64) or ntox86_64-gdb (x86-64).

Starting and connecting

Assuming that you have specified the gdb option in the configuration file for the qvm process instance hosting your guest (e.g., gdb 1234), to connect the GDB client, do the following:

Boot the hypervisor (see “Booting the host”).

You can configure your hypervisor to start your guest or guests immediately, or start them later.
On your host computer (laptop or desktop), open a terminal and establish a connection to the hypervisor host domain on your target (e.g., a serial connection or a TCP connection over SSH; see “Viewing hypervisor activity” in the “Booting and Shutting Down” chapter).
Use ifconfig to find out your hypervisor host domain's IP address (see ifconfig in the QNX SDP Utilities Reference).

Since you are using TCP, you must have io-pkt-* running in your hypervisor host (see io-pkt-* in the Utilities Reference).
If the guest whose behavior you want to examine isn't started, start it (see “Starting and using guests” in the “Building a Hypervisor System” chapter)
On your host computer terminal command line, start the GDB client version for your target board, either ntoaarch64-gdb or ntox86_64-gdb.
When prompted by the GDB client, specify that you want to connect to a remote target, and provide your hypervisor host's IP address and the port number you specified for the gdb option in the qvm configuration. For example:
```
gdb>
target remote 10.122.30.1:1234
```
where 10.122.30.1 is the IP address of the hypervisor host, and 1234 is the port number specifed in the qvm configuration.

You should now be able to use any of the basic GDB commands to examine your guest's behavior.