run_hw_ila - 2024.1 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
UG835
Release Date
2024-05-30
Version
2024.1 English

Arm hardware ILAs.

Syntax

run_hw_ila [‑trigger_now] [‑compile_only] [‑file <arg>] [‑force] [‑quiet]
    [‑verbose] [<hw_ilas>...]

Usage

Name Description
[-trigger_now] Trigger and capture immediately.
[-compile_only] Test only compile trigger state machine file but do not upload.
[-file] Trigger at startup file name. Command will not arm ILA core.
[-force] Overwrite existing file
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution
[<hw_ilas>] hardware ILAs Default: Current hardware ILA

Categories

Hardware

Description

Arm triggers and run the specified hardware ILA debug cores on the current hardware device.

The Integrated Logic Analyzer (ILA) debug core lets you perform in-system debug of implemented designs, or design bitstreams, on a programmed AMD FPGA. The ILA core includes many advanced features of modern logic analyzers, including boolean trigger equations, and edge transition triggers. You can use the ILA core to probe specific signals of the design, to trigger on programmed hardware events, and capture data samples from the AMD FPGA in real-time. Refer to LogiCORE IP Integrated Logic Analyzer (PG172) for details of the ILA core.

You can add ILA debug cores into the RTL source files of a design, or in the synthesized netlist using the create_debug_core command. Refer to the Vivado Design Suite User Guide: Vivado Programming and Debugging (UG908) for more information on adding debug cores and signal probes to the design.

Debug cores and probes are written to a probes file (.ltx) using the write_debug_probes command, and associated with the hardware device along with the bitstream file (.bit) using the PROBES.FILE and PROGRAM.FILE properties of the hw_device object. The hardware device is programmed using the program_hw_devices command. The ILA debug cores in the design are accessible from the Hardware Manager using the get_hw_ilas command. The debug probes assigned to the ILA debug cores can be returned with the get_hw_probes command.

The steps to debug your design in hardware using an ILA debug core are:

  1. Connect to the hardware server and target using connect_hw_server and open_hw_target.
  2. Program the FPGA with the bitstream (.bit) and probes (.ltx) files using program_hw_devices.
  3. Set up the ILA debug core trigger events and data capture controls using set_property to configure properties of the ILA.
  4. Arm the ILA debug core triggers on the AMD FPGA using run_hw_ila. When a trigger event occurs, or the capture condition is met, the ILA capture buffer is filled.
  5. Uploaded sampled data from the hw_device into a Vivado™ logic analyzer hw_ila_data object using upload_hw_ila_data.
  6. View the captured data in the Waveform window of the Vivado logic analyzer feature using display_hw_ila_data.

You can set up an ILA debug core to trigger on specific events or conditions at the debug probes, and to capture data under specific conditions, using CONTROL properties on the hw_ila object. You set these properties with the set_property command. Refer to the Vivado Design Suite User Guide: Vivado Programming and Debugging (UG908) for more information on setting properties to configure debug cores and signal probes to monitor the design.

Note: The Vivado IDE provides a graphical interface to configure hw_ila and hw_probes for trigger and capture. You can use the Vivado IDE to see the properties needed to configure and run the hw_ila.

The specific properties on the hw_ila you can use to configure a debug core include the following:

  • CONTROL.DATA_DEPTH - Defaults to the MAX_DATA_DEPTH of the ILA debug core, which was set when the debug core was created or inserted into the design. The data depth defines the number of data samples the hw_ila object can capture in a data window. Set the data depth as an integer which is a power of two, from 1 to the maximum data depth (MAX_DATA_DEPTH) of the hw_ila.
    Note: The value of DATA_DEPTH is related to CONTROL.WINDOW_COUNT by the equation: DATA_DEPTH * WINDOW_COUNT = MAX_DATA_DEPTH
  • CONTROL.WINDOW_COUNT - Lets you divide the MAX_DATA_DEPTH of the ILA core into a number of data windows to store sample data from multiple trigger events. In the case of 10 data windows for example, the first window will be filled at the first trigger event, and each subsequent window will be filled upon subsequent triggering events or capture conditions.
  • CONTROL.TRIGGER_POSITION - An integer value related to the DATA_DEPTH. Positions the trigger event in the sample data buffer. For a DATA_DEPTH of 1024, position 0 refers to the first (or left-most) data buffer and 1023 refers to the last (or right-most) data buffer. The TRIGGER_POSITION lets you capture sample data ahead of the trigger event. For instance, with a DATA_DEPTH of 256, a TRIGGER_POSITION of 100 allows you to capture 100 data samples ahead of the trigger, and 155 data samples at and after the trigger event.
    Note: In the case of run_hw_ila -trigger_now 1, the TRIGGER_POSITION merely positions the trigger mark in the Vivado logic analyzer waveform window. Because the trigger event is immediate, there is no time to capture data samples ahead of the trigger.
  • CONTROL.TRIGGER_MODE - Valid values include:
    • BASIC_ONLY - The trigger condition is the result of a Boolean equation using the TRIGGER_CONDITION to evaluate the values on each of the associated ILA probes.
    • BASIC_OR_TRIG_IN - The ILA core is triggered by a Boolean equation considering probe values, or by the TRIG_IN port on the core.
    • ADVANCED_ONLY - The ILA core is configured to have advanced trigger capabilities defined in a user-defined Trigger State Machine (TSM).
    • ADVANCED_OR_TRIG_IN - The ILA core is triggered by the TSM or by the TRIG_IN port on the core.
    • TRIG_IN_ONLY - The ILA core is triggered only by the TRIG_IN port on the core.
  • CONTROL.TRIGGER_CONDITION - Defines a Boolean equation which evaluates comparators on participating probes on the ILA debug core. When the condition evaluates to true, the BASIC trigger mode is satisfied. Valid values include:
    • AND - Trigger condition is "true" if all participating probe comparators evaluate "true", otherwise trigger condition is "false".
    • NAND - Trigger condition is "true" if at least one participating probe comparator evaluates "false", otherwise trigger condition is "false".
    • OR - Trigger condition is "true" if at least one participating probe comparator evaluates "true", otherwise trigger condition is "false".
    • NOR - Trigger condition is "true" if all participating probe comparators evaluate "false", otherwise trigger condition is "false".
    Note: The evaluation of the probes participating in the trigger condition is determined by the TRIGGER_COMPARE_VALUE property assigned to the hw_probe object, as returned by get_hw_probes. If the TRIGGER_COMPARE_VALUE is 'X' then it is not participating in the trigger condition.
  • CONTROL.TSM_FILE - Specify the path to a file defining a Trigger Finite State Machine (TSM) to be used for advanced trigger handling.
  • CONTROL.TRIG_OUT_MODE - Used to transition the TRIG_OUT port on the ILA core to be used to drive the TRIG_IN port on other ILA cores. Valid values include:
    • DISABLED - Disable the TRIG_OUT port on the ILA core.
    • TRIGGER_ONLY - Transition the TRIG_OUT port when the trigger conditions have been satisfied.
    • TRIG_IN_ONLY - Transition the TRIG_OUT when the TRIG_IN signal transitions. Use this to pass the trigger event along a chain of ILA cores.
    • TRIGGER_OR_TRIG_IN - Transition the TRIG_OUT when either the trigger conditions are satisfied, or the TRIG_IN transitions.
  • CONTROL.CAPTURE_MODE - Valid values include ALWAYS or BASIC. Capture and store a data sample on the debug core ALWAYS during a given clock cycle, or only if the CAPTURE_CONDITION evaluates to "true" (BASIC).
  • CONTROL.CAPTURE_CONDITION - Defines a Boolean equation for participating probe comparators on the ILA debug core that must evaluate to TRUE to meet the data capture condition. When the capture condition evaluates to true, the BASIC capture mode is satisfied. Valid values include:
    • AND - Capture condition is "true" if all participating probe comparators evaluate "true", otherwise capture condition is "false".
    • NAND - Capture condition is "true" if at least one participating probe comparator evaluates "false", otherwise capture condition is "false".
    • OR - Capture condition is "true" if at least one participating probe comparator evaluates "true", otherwise capture condition is "false".
    • NOR - Capture condition is "true" if all participating probe comparators evaluate "false", otherwise capture condition is "false".
    Note: The evaluation of the probes participating in the capture condition is determined by the CAPTURE_COMPARE_VALUE property assigned to the hw_probe object, as returned by get_hw_probes. If the CAPTURE_COMPARE_VALUE is 'X' then it is not participating in the trigger condition.
Tip: There are other properties on the ILA core that also determine the operation of the core, but they are not user-configurable.

With the ILA core configured, you can use the run_hw_ila command to arm the ILA cores on the target part. When this command is run, the trigger configurations defined in the hw_ila and hw_probe objects are written to the target AMD FPGA (hw_device) and arms the ILA core or cores on the device.

With the hw_ila armed and running, the wait_on_hw_ila command stops your Tcl script to wait for the data sample buffers to be populated with captured data. When the memory of the ILA core is full on the physical hw_device, the wait_on_hw_ila command returns, and your Tcl script resumes.

You can use upload_hw_ila_data to upload the captured data from the physical memory of the hw_device into a hw_ila_data object in the Vivado logic analyzer. Then view the ILA data in the waveform window of the Vivado logic analyzer using display_hw_ila_data, and write the data for use in external tools using the write_hw_ila_data command.

You can also immediately trigger the probes on the hw_device using the -trigger_now option, to capture data from the device right away, rather than waiting for trigger events or capture conditions to be met over time.

You can use reset_hw_ila to restore the CONTROL properties of the ILA debug core to their default setting, and reset the probe comparator values to 'X'.

Arguments

-trigger_now - (Optional) Immediately trigger the ILA debug cores, regardless of trigger conditions, to capture sample data at the debug ports. This is a boolean argument enabled by its presence.

-compile_only - (Optional) Compile the trigger state machine file (CONTROL.TSM_FILE) to perform syntax checking and report compiler errors and warnings. This option does not load and arm the hardware device. This option is only supported when in advanced trigger mode (CONTROL.TRIGGER_MODE ADVANCED_ONLY), and will otherwise return an error.

-quiet - (Optional) Execute the command quietly, returning no messages from the command. The command also returns TCL_OK regardless of any errors encountered during execution.
Note: Any errors encountered on the command-line, while launching the command, will be returned. Only errors occurring inside the command will be trapped.
-verbose - (Optional) Temporarily override any message limits and return all messages from this command.
Note: Message limits can be defined with the set_msg_config command.

-file <arg> - (Optional) When the TRIGGER_MODE is set to BASIC_ONLY, this option will export a file containing the current trigger and probe configuration settings. The trigger file can be used by the apply_hw_ila_trigger command to define triggers for the hw_device to use on startup, or upon booting the device. Using the -file option prevents the run_hw_ila command from arming the ILA core triggers on the hardware device.

Note: If no extension is specified, a default file extension of .tas is assigned.

-force - (Optional) Overwrite the specified trigger file if it already exists. By default the tool will not overwrite an existing file.

<hw_ilas> - (Optional) Specify one or more hw_ila objects to run. The hw_ila objects can either be specified as objects returned by the get_hw_ilas or current_hw_ila commands, or specified by name. If the hw_ila is not specified, the current_hw_ila will be run.

Important: You can only specify one hw_ila object when using the -file option.

Example

The following example sets the trigger and capture properties on the current hw_ila object, and then runs the hw_ila, specified by name, to arm the hw_device and wait for the data buffers to be filled:

current_hw_ila [get_hw_ilas hw_ila_1]
set_property CONTROL.DATA_DEPTH 1024 [current_hw_ila]
set_property CONTROL.TRIGGER_MODE BASIC_ONLY [current_hw_ila]
set_property CONTROL.TRIGGER_CONDITION AND [current_hw_ila]
set_property CONTROL.CAPTURE_MODE ALWAYS [current_hw_ila]
run_hw_ila -trigger_now hw_ila_1
wait_on_hw_ila hw_ila_1

This example writes a trigger configuration file for the current hw_ila object, to the specified file, but does not arm the current hw_device:

run_hw_ila -file C:/Data/trigger_config1
Note: A default file extension of .tas is assigned to the specified file.