Using the GNU debugger (GDB)

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

There are two ways to use GDB to debug a guest's VM:

Running GDB on your development host machine and connecting to the qvm process instance on the target machine.
Triggering a debug session from guest activity on the target.

For either method, when the GDB toolchain attaches to the qvm process instance, the VM is paused, allowing you to see symbol information for the VM context and hence, view OS variables and source code. Note that this is distinct from application-level debugging on the guest, although the guest applications will still be paused.

The supported GDB functionality includes:

breakpoints
single-stepping
reading and writing to guest memory
reading and writing to vCPU registers
switching between vCPUs
continuing the qvm process

For more information about using GDB in a QNX environment, see the gdb entry in the QNX Neutrino Utilities Reference. For general 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 VM to run so the guest OS can start and run until GDB connects to the TCP/IP 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 VM prior to the first instruction executing on each vCPU. 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

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

Starting and connecting to the guest VM

Assuming that you have specified the gdb option in the qvm configuration file for your guest's VM, to connect to and start debugging the VM, do the following:

Boot the hypervisor (see Booting the QNX hypervisor host).

You can configure your hypervisor to start your guests immediately, or start them later.
On your host computer, 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 Utilities Reference).

If 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 QNX 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. 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 specified in the qvm configuration.

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

Triggering a debug session from guest activity

There are two ways to trigger a GDB debug session for a guest's VM based on guest activity:

Launch the VM (qvm process instance) in debug mode (with GDB attached), set breakpoints based on memory regions of interest, then continue the guest so it can execute. When the guest accesses the memory region (and thus, hits the breakpoints), the debug session pauses the guest and you can debug the VM.
Without starting the VM in debug mode, you can configure the guest to communicate with the hypervisor host to initiate a debug session on demand. Communication with the hypervisor host can be done through a custom vdev or applications using TCP/IP or shared memory. Then, a debug session can be launched to immediately pause and debug the VM (and thus, the guest).

Page updated: March 12, 2026