VPU Debugging#

The PVA SDK provides source-level debugging of VPU programs built with the NVVPU toolchain. You can debug a VPU running on target hardware or in the x86 emulator (EMU) using the LLDB debugger supplied with the PVA SDK.

For a step-by-step worked example, including command-line and VS Code debugging, see VPU Debugging with LLDB.

How It Works#

LLDB communicates with the VPU over the GDB Remote Serial Protocol (RSP). An RSP server translates LLDB requests into operations on the VPU’s on-chip debug (OCD) interface.

On target hardware, the RSP server runs on the SoC’s CPU and accesses the OCD interface through the PVA driver. This is known as Debug over IP (DoIP): it provides the capabilities of a dedicated debug cable, but uses the network connection to the board. The pva-sdk-2.10-doip utility on the development machine manages the server for you. It detects the target OS and PVA generation, deploys and starts the matching server over SSH, then launches LLDB connected to it. Do not deploy or start the server directly.

EMU contains its own RSP server. Enable it with the PVA_EMU_DEBUG_PORT environment variable and connect LLDB directly to the local port; the DoIP utility is not used.

Note

DoIP is for debugging in a controlled environment only. The RSP server runs with elevated privileges to access the on-chip debugger, which must not be made available to any process in a production environment.

LLDB can be used through three clients:

  • the interactive lldb command line,

  • LLDB’s curses-based terminal UI (the gui command), and

  • VS Code, through the LLDB Debug Adapter Protocol bridge lldb-dap.

Preparing an Application for Debugging#

On target hardware, the VPU must be halted before the debugger can connect. Insert a swbrk() call at the point where debugging should begin, then rebuild and deploy the application. See Inserting a Software Breakpoint for an example. EMU halts at the start of a debug-enabled run, so an initial swbrk() is not required.

The debugger connects to a single VPU core. If your host code does not schedule work on a deterministic VPU core, either make the scheduling deterministic while debugging or connect separate debugger instances to each core.

Supported Platforms#

Execution Environment

Required Platform Package

OCD Interface

x86 EMU

pva-sdk-2.10-emu-dev

Embedded RSP server on localhost

Linux L4T (aarch64)

pva-sdk-2.10-l4t-doip-nvvpu

/sys/kernel/debug/pva0/ocd_vpu* (ioctl)

The commands in Installation install LLDB, the DoIP utility, and the target-side server package for L4T.

Note

LLDB debugging of NVVPU binaries on QNX targets is not available in this release. To debug VPU code on QNX, build it with ASIP Programmer and use ChessDE; see Debug over IP with ChessDE.

ASIP Programmer#

Binaries built with ASIP Programmer cannot be debugged with LLDB. Use ChessDE instead; see Debug over IP with ChessDE.