Bare-metal Debug from the Vitis IDE - 2021.1 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID
UG1076
Release Date
2021-07-19
Version
2021.1 English

With the bare-metal system project built as described in Building a Bare-metal AI Engine in the Vitis IDE, you must use the following steps to debug both the AI Engine graph, together with the bare-metal PS application on the Hardware build target.

This process is a bit more complex than debugging a Linux application in the Vitis IDE. In that case the PS host application was built as a part of the top-level system project. Here the PS application is built as a standalone project, and must be separately included in the debug configurations when launching the debug environment. This is detailed in the following steps.

  1. Right-click on the top-level system project and select the Debug As > Debug Configurations command.

    This opens the Debug Configurations dialog box to let you set up the tool.

    Important: For the Hardware build, you will need to create two Debug configurations: one for the top-level system project, and a second for the bare-metal PS application.
  2. In the Debug Configurations dialog box select the New Launch Configuration () command to open the Debug Configurations dialog box as shown.

    Notice the following fields on the Debug Configurations dialog box:

    • Project: Reflects the name of the top-level system project which includes the AI Engine graph application, the PL kernels, and the HW-Link projects.
    • Hardware Server: Specifies a local connection to the board. You can configure this differently for a remotely connected board.
    • Linux TCF Agent: Is disabled for bare-metal systems.
    • Disable build before launch: Enable this to prevent the tool from building your system before launching the application.
  3. Select Apply to save and apply your changes, and select Close to close the dialog box.
  4. Right-click the baremetal_app project in the Explorer view, and select Debug As > Debug Configurations as shown in the following image.

  5. The Single Application Debug Configurations dialog box opens as shown in the following figure.

  6. Specify a Name to identify the configuration as applying to the PS application. The Connection is set up automatically for the local hardware.
  7. Change to select the Target Setup tab of the Debug Configurations dialog box, and deselect the Reset entire system and Program Device check boxes in the dialog box.
  8. Click Apply to proceed.
  9. You also need to create a launch group containing the two debug configurations you just created. The launch group lets you launch multiple configurations as a group. Use the main toolbar menu command by selecting Debug > Debug Configurations to open the Debug Configurations dialog box, and then select Launch Group as shown.
    Important: You must use the main toolbar menu Debug command because it provides the complete set of Debug Configuration options rather than the reduced options found in the Explorer or Assistant views, which are limited by your selections.


    Click on Launch Group, and provide a Name for the new group. Click Add the top-level project and PS application Debug configurations to the group as shown in the previous image. Click OK to create the launch group.

  10. The Launch Group is displayed with both debug configurations added. Click Debug to launch the Debug perspective.
  11. Because you are launching both the top-level project and PS debug configurations on a single target connection, the Vitis IDE will display a Launch Config Conflict message. Click No on the conflict message to proceed.
  12. The Debug perspective is opened, as shown in the following image. Because there are two debug configurations, you will see two instances of the PS application. You can ignore the second instance of the PS application.

From this point you can do all the debug activities: step in, step over, viewing variables, apply break points in the emulation environment. Refer to Using the Debug Environment for more information.