Run Application Project

Launch Configurations

To debug, run, and profile an application, you must create a launch configuration that captures the settings for executing the application. To do this, right-click on the application project and select Run As > Run Configurations .... The Run configuration window opens. Double click the Single Application Debug to create a Run Configuration. The Run Configuration window opens with the Main tab.

Main Tab

The main tab has the following options:

Debug Type
You can choose from Standalone Application Debug, Linux Application Debug, or Attach to running target.
Connection
In the connection field, you can create a target connection by clicking New.
Note: The other options will populate automatically to run the application.

Application Tab

In the Application tab, set up the details for your application project and select the ELF file.



Stop At Main
Used to stop the debugger at main() function.
Stop at Program Entry
Used to stop the debugger at program entry.
Reset Processor
You can choose to reset the entire hardware system or the specific processor, or choose not to reset. Performing a reset ensures that there are no side effects from a previous debug session.
Advanced Options
These options are used for profiling an application. Click Edit to see the options. The options to select are This is a self relocating application and Profiling Options.

Target Setup Tab

Provide a unique name for your configuration. Next, in the Target Setup tab, set up the following details:

  • Debug Type
  • Connection: Local or Remote

Select Local for running the program on a target that is connected to local host.

Create a remote connection by clicking New, and select the same for running the program on a target connected to the remote host.

FPGA Device
This is automatically selected for you.
PS Device
This is automatically selected for you.
Hardware Platform
Select the hardware platform for your design.
Bitstream file
Search or browse to your Bitstream file.
FSBL File or Initialization File
Selects either the FSBL file or Initialization file based on whether the checkbox is selected. By default, the Use FSBL Flow for Initialization check-box is checked.
Reset Entire System
Perform a system reset if there is only one processor in the system.
Initialize Using FSBL file
Initialize PS using FSBL file.
Reset APU
Reset all the APU processor cores.
Reset RPU
Reset all the RPU processor cores.
Enable RPU Split Mode
Put RPU cores in split mode so that they can be used independent of each other.
Program FPGA
To program the bit file.
Skip Revision Check
Enabling this option will skip the device revision while programming bit stream.


Profiler

The Vitis™ unified software platform provides capability to profile your software application. Use the Profiler tab to specify options for the profiler. Refer to Profile/Analyze for more information.

Creating or Editing a Launch Configuration

You can launch Run, Debug and Profile tasks directly with a set of default configurations. Right-click on the desired application and select Run As, or Debug As. Select Launch on Hardware (Single Application Debug) from the context menu.

Customizing Launch Configurations

The Launch Configurations preferences page allows you set filtering options that are used throughout the workbench to limit the exposure of certain kinds of launch configurations. These filtering setting affect the launch dialog, launch histories and the workbench.

Table 1. Launch Configuration Options
Option Description Default
Filter configurations in closed projects Filter out configurations that are associated with a project that is currently closed On
Filter configurations in deleted or missing projects Filter out configurations that are associated with a project that has been deleted or are simply no longer available On
Apply windows working set Applies the filtering from any working sets currently active to the visibility of configurations associated with resources in the active working sets. That is to say, if project P has two configurations associated with it, but is not in the currently active working set, the configurations do not appear in the UI, much like P does not. On
Filter checked launch configuration types Filter all configurations of the selected type regardless of the other filtering options. The checked options are not displayed in the Run/Debug Configurations dialog box.
Note: To avoid confusion, only configurations that are supported by the Vitis software platform are available by default.
On
Delete configurations when associated project is deleted Any launch configurations associated with a project being deleted are also deleted if this option is enabled. After they have been deleted, the configurations are not recoverable. On
Migrate As new features are added to the launching framework, there sometimes exists the need to make changes to launch configurations. Some of these changes are made automatically, but those that are not (nonreversible ones) are left up to the end user. The migration section allows you to self-migrate any launch configurations that require it. Upon pressing the Migrate... button, if there are any configurations requiring migration, they are presented to you, and you can select the ones that you want to migrate.

Target Connections

The Target Connections view allows you to configure multiple remote targets. It shows connected targets and gives you an option to add or delete target connections.

The Vitis software platform establishes target connections through the Hardware Server agent. In order to connect to remote targets, the hardware server agent must be running on the remote host, which is connected to the target.

The target connection has been extended to all utilities within the Vitis software platform that deal with targets at runtime.



Creating a New Target Connection

You can configure the remote target details by adding a new connection in the Target Connections view.

To create new target connection:

  1. In the Target Connections window of the Vitis IDE, click the Add Target Connection button ().
  2. The Target Connection Details dialog box opens.
  3. In the Target Name field, type a name for the new remote connection.
  4. Check the Set as default target checkbox to set this target as default. The Vitis software platform uses the default target for all the future interactions with the board.
  5. In the Host field, type the name or IP address of the remote host machine. This is the machine that is connected to the target and the hw_server is running.
  6. In the Port field, type the port number on which the hw_server is running. By default, the hw_server runs on port 3121.
  7. Select Use Symbol Server, if the hardware server is running on a remote host.
  8. Click OK to create a new target connection.

Setting Custom JTAG Frequency

You can now operate at a different frequency supported by the JTAG cable, by setting a custom JTAG frequency.

To set a custom JTAG frequency:

  1. In the Target Connections view, click the Add Target Connection button (). The Target Connection Details dialog box opens.
  2. Specify the name of the new remote target connection, for example test.
  3. Check the Set as default target checkbox to set this target as default. The Vitis software platform uses the default target for all the future interactions with the board.
  4. Specify the name or IP address of the remote host machine. This is the machine that is connected to the target and the hw_server is running.
  5. Specify the port number on which the hw_server is running. By default, the hw_server runs on port 3121. Select Use Symbol Server, if the hardware server is running on a remote host.
  6. Click Advanced to view the JTAG device chain details.
  7. Select the JTAG device chain and click Frequency to open the Set JTAG Frequency dialog box.
  8. From the Set custom frequency drop-down list, select the frequency.
    Note: Current frequency can be the default frequency set by the server or the custom frequency set by a debug client.
  9. Click OK to save the configuration and close the Set JTAG Frequency dialog box. The selected frequency is saved in the workspace and is used to set the frequency before executing a connect command for the selected device.
  10. Click OK to create a new target connection.
    Note: If only one client is connected to the server, the frequency of the cable is reset to the default value whenever the connection is closed. However, in case of multiple clients connected to the server, it is not recommended to perform simultaneous debug operations from different clients.

Establishing a Target Connection

To establish a target connection, you can use either the local board or the remote board. By default, the local target connection is selected in the Target Connections view. You can confirm connections to the local board by checking the local connection.

To use a remote board to establish a target connection:

  1. Ensure that the target is connected to the remote host.
  2. Launch the hw_server manually on the remote host:
    1. Take a shell on the remote host.
    2. Source the setup scripts by using C:/Xilinx/Vitis/<version>/settings64.bat (or) /opt/Xilinx/ Vitis/<version>/settings64.csh.
  3. Run the hw_server on the machine that connects to the board.
    Note: Ensure that the target (board) is connected to the remote host.
  4. Select the port number and the hostname to create a target connection to the host running the hw_server.
  5. Right-click the newly created target connection and select Set As Default.

Viewing Memory Contents

The Memory view lets you monitor and modify your process memory. The process memory is presented as a list called memory monitors. Each monitor represents a section of memory specified by its location called base address. Each memory monitor can be displayed in different predefined data formats known as memory renderings.

The Memory view contains these two panes:

  • Monitors panel - Displays the list of memory monitors added to the debug session currently selected in the Debug view.
  • Renderings panel - Displays memory renderings. The content of this panel is controlled by the selection in the Monitors panel.

To open the Memory view, click the Memory tab of the Debug perspective. Alternatively, from the IDE menu bar, select Window > Show View > Memory.

Dump/Restore Memory

The Memory window does not have the ability to load or dump memory contents from or to a file.

You can use the Dump/Restore Memory function to copy the memory file contents to a data file and restore data file contents back to memory. To do this:

  1. Launch the hardware server, if it is not already running.
  2. Select Xilinx > Dump/Restore Memory.
  3. The Dump/Restore Memory dialog box opens.

  4. Click Select to select a Processor from the Select Peer and Context window. The Vitis software platform creates peers based on available target connections. For this example, the Vitis software platform creates a peer called Zc706_remote.
  5. Select the peer corresponding to your Target connection from the Peers list (in this case, Zc706_remote), and then select the related processor, ARM Cortex-A9 MPCore #0, from the APU Context.
    Note: Select the processor context, not the device context. In the example here, the processor context is APU.
  6. Click OK to select the processor.
  7. Set the location of the data file to restore from or dump to.
  8. Select either the Restore Memory or Dump Memory option button.
  9. In the Start field, specify the starting memory address from which you want to dump or restore memory.
  10. In the Size (in bytes) field, specify the number of bytes to be dumped or restored.
  11. Click OK. The Vitis software platform dumps or restores data from the starting address specified.

Viewing Target Registers

The Registers view lists all registers, including general purpose registers and system registers. As an example, for Zynq® devices, the Registers view shows all the processor and co-processor registers when Cortex™-A9 targets are selected in the Debug view. The Registers view shows system registers and IOU registers when an APU target is selected.

To open the Registers view, click the Registers tab of the Debug perspective. Alternatively, from the IDE menu bar, select Window > Show View > Registers.

You can modify editable field values, during debug. You can also pin the Registers view using the Pin to Debug Context toolbar icon, as shown in the figure below.



Viewing IP Register Details

The Vitis software platform now supports viewing of IP register details, using either the Hardware (system.xsa) view or during debug using the Registers view. After successful platform project creation, the system.xsa file in the Hardware Specification view is opened. The file now displays cross-references to the registers of IP blocks present in the design.



To view register details, click on the Registers link on the Hardware Specification view.