Performance Monitor FPGA IP User Guide: Agilex™ 5 and Agilex™ 7 FPGAs

ID 817760
Date 7/08/2024
Public
Document Table of Contents

A. Performance Monitor (PMON) Library Functions

This topic lists the PMON TCL library functions for use with the System Console.

To learn about other PMON functions, and how to use PMON functions in the System Console, refer to the pmon_library.tcl file, located here: <path to generated pmon ip files>/pmon_global_monitor_100/synth/pmon_library.tcl

To use the PMON functions in the System Console, follow these steps:

  1. In the Quartus® Prime software, click Tools > System Debugging Tools > System Console to open the System Console.
  2. Load the ed_synth.sof file into the System Console by clicking File > Load Design > ed_synth.sof. (Alternatively, you can load the .sof file from the terminal command line, if you prefer not to use the System Console.)
  3. Load the pmon_library.tcl file in the System Console by entering the following command:
    source <path to pmon library>/pmon_library.tcl
    

Once the PMON library is loaded, you can use any of the PMON library functions listed in the table below.

Tip: In the following table, index refers to the JTAG index of the PMON instance, and umon represents the unit monitor within the instance of PMON. The umon value is fixed to 0 in current release.
Table 42.  PMON Library Functions
PMON Function Description
pmon_discover_all Performs the discovery process for all PMON JTAGs for all monitors and initialize all top level list variables. Called automatically when loading library and needed for all following functions.
pmon_print_counter_data {index} {umon} Prints the counter data register of each counter of PMON <index> unit monitor <umon> with its address in memory.
pmon_print_info {index} Prints parameters and path of given PMON JTAG <index>.
pmon_freeze {index} {umon} Sets Freeze field of UCTRL register of PMON <index> Unit monitor <umon> to 1.
pmon_unfreeze {index} {umon} Sets Freeze field of UCTRL register of PMON <index> Unit monitor <umon> to 0.
pmon_reset_counter_control {index} {umon} Reset counter metric configuration for PMON <index> unit monitor <umon>.
pmon_reset_counter_data {index} {umon} Reset counter data and internal state for PMON <index> unit monitor <umon>.
pmon_reset_status {index} {umon} Clears the status bits of PMON <index> unit monitor <umon>.
pmon_print_status {index} {umon} Prints out the overflow status of each counter in PMON <index> unit monitor <umon>.
pmon_print_counter_control {index} {umon} Prints out the counter control register of each counter of PMON <index> unit monitor <umon> with its address in memory.
pmon_get_counter_control {index} {umon} Returns a list of the counter counter register values of PMON <index> unit monitor <umon>.
pmon_get_counter_data {index} {umon} Returns a list of the counter data register values of PMON <index> unit monitor <umon>.
pmon_get_status {index} {umon} Returns a list overflow status of each counter in PMON <index> unit monitor <umon>.
pmon_num_ins Returns the number of PMON instances in design.
pmon_num_umon {index} Returns the number of unit monitors of PMON instance <index>.
pmon_define_configs {index} Initializes library supported PMON configurations. Called automatically when loading library and needed for all following functions.
pmon_set {config} {index} {umon} Sets counter control of PMON <index> unit monitor <umon> based on the provided <config> argument. Find accepted configs through calling pmon_help config.
pmon_read {index} {umon} Read the derived metrics of PMON <index> unit monitor <umon> based on the currently set configuration of the monitor.
pmon_help {option} Display information about the PMON library.
pmon_check_viol {index} {umon} Debug function, checks if max outstanding transactions or traffic gap violations were found after reading results and prints errors. Checking traffic gap or outstanding transaction violations corrupts counter data so ensure all data is collected before checking violations.

Appending _all (available on any set, read, reset or check function) to a function will call the function for all unit monitors in the design. For example:

pmon_set_all {config}
Table 43.  PMON Configuration Table
Argument Name Description
empty Empty Sets all counters to an idle state and clears all filters.
basic_eff Basic efficiency Set metrics for Read efficiency, Write efficiency, and Average Data transactions per cycle of the AXI4 Interface.
ch_eff AXI4 subchannel efficiency Set metrics for efficiency of the AR, R, AW, W subchannels of the AXI4 Interface.
ch_bp AXI4 subchannel backpressure Set metrics for backpressure of the AR, R, AW, W subchannels of the AXI4 Interface. For the B channel backpressure, use the secondary configuration which is described later in this table.
basic_rw Basic read/write Set metrics for the Read, Write efficiency and average latencies of the AXI4 Interface.
wo Write only Set metrics for AXI4 subchannel (AW,W,B) efficiency, transactions, average write burst length, expected write data transactions and average write latency of the AXI4 Interface.
ro Read only Set metrics for AXI4 subchannel (AR,R) efficiency, transactions, backpressure, average read burst length, expected read data transactions and average read latency of the AXI4 Interface.
diag Diagnostics Set metrics for number of AXI4 subchannel transactions (AR,R,AW,W,B), expected R,W transactions, and total traffic duration of the AXI4 Interface.
primary Primary side Set metrics for AXI4 subchannel (AR,AW,W) efficiency, transactions, average read and write latency of the AXI4 Interface.
secondary Secondary side Set metrics for AXI4 subchannel (R,B) efficiency, transactions, backpressure, expected R and B transactions of the AXI4 Interface.
basic_lat Basic latency Set metrics for Read & Write average latencies, maximum outstanding transactions, and average burst lengths of the AXI4 Interface.