Debugging Virtual Machines Via JTAG#

Overview#

JTAG debugging provides hardware-level debugging capabilities for virtual machines using an external JTAG probe. Some JTAG debuggers support setting context-aware breakpoints that can only be hit when a specified VM is executing, enabling precise debugging of guest OS code.

The target VM is identified by its VMID (Virtual Machine ID), which is calculated based on its Guest ID (GID) as follows:

VMID = 2 * GID

The possible values of GID are generally 0, 1, and 2. VMIDs are guaranteed to remain the same across system reboots, providing consistent debugging sessions.

Drive OS Profiles#

This feature is available in the following Drive OS profiles:

Profile

Availability

Notes

dev_nsr, debug_sr

✓ Available

Full JTAG debugging capabilities enabled

prod_sr, prod_nsr, test_sr, test_nsr

✗ Not Available

JTAG debugging is disabled in production and test builds for security reasons

Configuration#

JTAG debugging requires:

  1. Hardware Setup: An external JTAG probe connected to the target system

  2. JTAG Debugger: A JTAG debugger that supports context-aware breakpoints

  3. VMID Calculation: Use the formula VMID = 2 * GID to identify the target VM

  4. Target: Target hardware must be unfused (i.e. not in production mode).

No additional software configuration is required beyond ensuring the system is built with debug capabilities enabled.

Limitations#

Limitation

Description

Impact

VMID Mapping Stability

VMID mapping formula may change in future DriveOS versions

Debugging scripts may need updates when upgrading DriveOS

Hardware Requirement

Requires external JTAG probe hardware

Not available for software-only debugging scenarios

Context-Aware Breakpoints

Support depends on JTAG debugger capabilities

Not all debuggers may support VM-specific breakpoints

Detailed Usage#

VMID Calculation

To debug a specific VM using JTAG, you must first determine its VMID. The VMID is calculated from the Guest ID (GID) using the formula:

VMID = 2 * GID

Example GID Values:

  • GID 0 corresponds to VMID 0

  • GID 1 corresponds to VMID 2

  • GID 2 corresponds to VMID 4

This VMID can be used to set context-aware breakpoints and watchpoints with a JTAG debugger.

Note

The VMID mapping formula (VMID = 2 * GID) is not guaranteed to remain the same in future versions of NVIDIA DriveOS. Update your debugging scripts and configurations when upgrading to new DriveOS versions.