Debug over IP (DoIP)#

PVA applications can be debugged with just an Ethernet cable connection over IP. On-chip Debug over IP (DoIP) feature provides all the benefits of debugging with a dedicated cable, but uses the SOC’s CPU to interface with the on-chip debugger.

Note

DoIP is for debugging purposes only in a controlled environment. The DoIP server is executed with elevated privileges to access the on-chip debugger. The on-chip debugger should not be made available to any processes in a production environment.

This page demonstrates how to use the DoIP feature. We use the mat_add sample application which comes with PVA SDK, but the instructions are equally applicable to users’ applications. Please follow the instructions in Installation for installing the PVA SDK first.

DoIP feature setup is executed in 4 steps:

  1. Modify your application to manually cause the VPU engine to enter a debugging state. This can be made conditional if required, for example if you only want to debug a specific frame in sequence. Rebuild, re-deploy and run the VPU application as you would normally.

  2. On the host machine, launch the DoIP tunnel for ChessDE.

  3. On the host machine, launch ChessDE and connect to the DoIP endpoint.

  4. Use the ChessDE GUI to debug your application.

Steps 3 and 4 are common to cable-based debugging. Refer to On-chip debugging for more information on using chessDE.

1. Modify the Application to be Debugged and Run#

This step explains how to modify the mat_add sample application VPU code to insert an initial hard-coded software breakpoint, deploy and run it on the target.

a. Add a Breakpoint#

Add a hard-coded initial software breakpoint to your PVA code. Please see comments on the below example code segment:

Example: mat_add/vpu/mat_add_top.c

#include "mat_add_knl.h"
#include "mat_add_param.h"

#include <cupva_device.h>

//Below two lines are added for debugging support
#define CUPVA_ALLOW_NONSAFETY 1
#include <cupva_device_debug.h>

// VMEM is used to declare all global VMEM buffers required
VMEM(A, int32_t, src1Buf, CUPVA_DOUBLE_BUFFER_LENGTH(MAX_BLK_W, MAX_BLK_H));
VMEM(B, int32_t, src2Buf, CUPVA_DOUBLE_BUFFER_LENGTH(MAX_BLK_W, MAX_BLK_H));
VMEM(C, int32_t, dstBuf, CUPVA_DOUBLE_BUFFER_LENGTH(MAX_BLK_W, MAX_BLK_H));

VMEM(A, uint32_t, niter1Buf);
VMEM(A, uint32_t, niter2Buf);

VMEM(A, uint32_t, srcTrig);
VMEM(A, uint32_t, dstTrig);

VMEM(A, uint32_t, blkW);
VMEM(A, uint32_t, blkH);

CUPVA_VPU_MAIN()
{
    int niter2   = niter2Buf;
    int niter1   = niter1Buf;
    int pingPong = 0;

    //Below two lines are added for debugging support
    swbrk();
    chess_separator_scheduler();
    ...

b. Modify Host Scheduling#

When debugging, you need to choose which VPU core the debugger will connect to. If this is not deterministic in your host scheduling code, it may be beneficial to modify the scheduling code to make it deterministic. Alternatively, multi-VPU debugging is supported, so it is possible to connect multiple instances of ChessDE to a single DoIP endpoint, targeting different VPU cores.

c. Deploy and Run the Application#

After modifying the code, follow the instructions in PVA SDK samples for building and deploying the modified application to the target board.

Run your application as you normally would on the target device. The application stops at the inserted software breakpoint. Refer to PVA SDK samples for more information on running PVA applications on a target board.

2. Launch DoIP Tunnel#

Launch the JTALK server on the host PC using the system-wide pva-sdk-2.7-doip command.

Use the --help option to see the list of options that can be set.

pva-sdk-2.7-doip --help

Note

Make sure to set required environment variables before launching JTALK as below:

export PVA_GEN2_ASIP_PATH=<PATH_TO_ASIP_PROGRAMMER>
export PVA_GEN3_ASIP_PATH=<PATH_TO_ASIP_PROGRAMMER>

The DoIP tunnel only needs to be started once per board. Any number of ChessDE instances may share the same VPU DoIP tunnel while being connected to different VPU cores.

Once the tunnel has been launched, users may launch chessDE and their application for debugging. Refer to On-chip debugging for more information on using chessDE.