NVidia's GDB Toolbox

This repository contains NVidia's GDB Python scripts and launcher utilities for debugging supported NVidia CPU complex targets through GDB and OpenOCD.

Overview

The GDB Toolbox loads a set of GDB commands for target attach, core selection, register access, and debug feature inspection. It currently includes top-level support for the following platforms:

• Grace
• Thor and ThorX
• Vera

After the toolbox is loaded, GDB commands are available for:

• Attaching and detaching platform targets with grace, thor, and vera.
• Selecting and listing active cores with core.
• Reading, writing, decoding, and searching APB, AXI/MMIO, and ARM SPR registers with apb, axi, and spr.
• Inspecting BRBE records and RAS status with brbe, and ras.

Platform attach commands automatically configure the relevant core topology, OpenOCD access path, and packaged register databases when they are available. Within GDB, use help <command> for the complete syntax of each command.

Getting Started

You will need CMake version 3.22.1 or newer.

mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=<install_path>
make -j8 install

The install step places the launcher in <install_path>/bin, GDB startup files in <install_path>/share/gdb, Python command modules in <install_path>/share/gdb/python, and packaged register databases in <install_path>/share/gdb/res. It creates a transferable package under <install_path>/packages.

To start GDB with the toolbox loaded:

<install_path>/bin/run_gdb.sh

On first run, run_gdb.sh creates a data directory named run_gdb.sh.data in the current directory, detects the Python interpreter used by GDB, creates a virtual environment, installs the Python dependencies, and writes a resolved runtime copy of init.gdb. Use --dir <dir> to choose another data directory or --force to recreate it.

Then attach to the target from inside GDB:

vera attach <openocd_host>

Use grace attach <openocd_host> or thor attach <openocd_host> for those platforms. Any non-launcher arguments are passed through to GDB, and arguments after -- are passed to GDB as-is:

<install_path>/bin/run_gdb.sh -- <gdb_arg> ...

You can also load the toolbox manually from an existing GDB session:

source <install_path>/share/gdb/init.gdb

Useful first commands after launch include:

help vera
vera attach <openocd_host>
core list

Requirements

The launcher expects a Linux host with a multi-architecture GDB. By default it looks for /usr/bin/gdb-multiarch; use --gdb <prog> to run a different GDB.

Runtime dependencies include Python 3, Python venv, pip, lsb_release, and pyyaml. OpenOCD must be running or reachable for target attach flows.

On Ubuntu, run_gdb.sh checks for and can install necessary packages including: libhidapi-hidraw0 and gdb-multiarch.

run_gdb.sh also supports --gdb <prog>, --dir <dir>, --gdbscripts <dir>, --verbose, and --force. Run <install_path>/bin/run_gdb.sh --help for the current launcher options.

Reporting an issue

Please report bugs, feature requests, or documentation issues here.

Community

Please email swteg-debug-help@nvidia.com if you have any question or feedback.

License

Files in this project are licensed according to their SPDX license identifiers. See LICENSE.md for details.