axipmon
Xilinx Vitis Drivers API Documentation
axipmon Documentation

The XAxiPmon driver supports the Xilinx AXI Performance Monitor device.The AXI Performance Monitor device provides following features:

  Configurable number of Metric Counters and Incrementers
    Computes performance metrics for Agents connected to
  monitor slots (Up to 8 slots)

The following Metrics can be computed:

Metrics computed for an AXI4 MM agent: Write Request Count: Total number of write requests by/to the agent. Read Request Count: Total number of read requests given by/to the agent. Read Latency: It is defined as the time from the start of read address transaction to the beginning of the read data service. Write Latency: It is defined as the period needed a master completes write data transaction, i.e. from write address transaction to write response from slave. Write Byte Count: Total number of bytes written by/to the agent. This metric is helpful when calculating the throughput of the system. Read Byte Count: Total number of bytes read from/by the agent. Average Write Latency: Average write latency seen by the agent. It can be derived from total write latency and the write request count. Average Read Latency: Average read latency seen by the agent. It can be derived from total read latency and the read request count. Master Write Idle Cycle Count: Number of idle cycles caused by the masters during write transactions to the slave. Slave Write Idle Cycle Count: Number of idle cycles caused by this slave during write transactions to the slave. Master Read Idle Cycle Count: Number of idle cycles caused by the master during read transactions to the slave. Slave Read Idle Cycle Count: Number of idle cycles caused by this slave during read transactions to the slave.

Metrics computed for an AXI4-Stream agent:

  Transfer Cycle Count: Total number of writes by/to the agent.
  Data Byte Count: Total number of data bytes written by/to the agent.
             This metric helps in calculating the throughput
             of the system.
  Position Byte Count: Total number of position bytes transferred.
  Null Byte Count: Total number of null bytes transferred.
  Packet Count: Total number of packets transferred.

There are three modes : Advanced, Profile and Trace.

  • Advanced mode has 10 Mertic Counters, Sampled Metric Counters, Incrementors and Sampled Incrementors.
  • Profile mode has only 47 Metric Counters and Sampled Metric Counters.
  • Trace mode has no Counters. User should refer to the hardware device specification for detailed information about the device.

This header file contains the prototypes of driver functions that can be used to access the AXI Performance Monitor device.

Initialization and Configuration

The device driver enables higher layer software (e.g., an application) to communicate to the AXI Performance Monitor device.

XAxiPmon_CfgInitialize() API is used to initialize the AXI Performance Monitor device. The user needs to first call the XAxiPmon_LookupConfig() API which returns the Configuration structure pointer which is passed as a parameter to the XAxiPmon_CfgInitialize() API.

Interrupts

The AXI Performance Monitor does not support Interrupts

Virtual Memory

This driver supports Virtual Memory. The RTOS is responsible for calculating the correct device base address in Virtual Memory space.

Threads

This driver is not thread safe. Any needs for threads or thread mutual exclusion must be satisfied by the layer above this driver.

Asserts

Asserts are used within all Xilinx drivers to enforce constraints on argument values. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that users leave asserts on during development.

Building the driver

The XAxiPmon driver is composed of several source files. This allows the user to build and link only those parts of the driver that are necessary.

Limitations of the driver



MODIFICATION HISTORY:
Ver   Who    Date     Changes


1.00a bss 02/27/12 First release 2.00a bss 06/23/12 Updated to support v2_00a version of IP. 3.00a bss 09/03/12 To support v2_01_a version of IP: Deleted XAxiPmon_SetAgent, XAxiPmon_GetAgent APIs and added XAPM_FLAG_EVENT, XAPM_FLAG_EVNTSTAR, XAPM_FLAG_EVNTSTOP. Deleted XAxiPmon_SetAgent, XAxiPmon_GetAgent APIs and modified XAxiPmon_SetMetrics, XAxiPmon_GetMetrics APIs in xaxipmon.c Deleted XAPM_AGENT_OFFSET Macro in xaxipmon_hw.h 3.01a bss 10/25/12 To support new version of IP: Added XAPM_MCXLOGEN_OFFSET macros in xaxipmon_hw.h. Added XAxiPmon_SetMetricCounterCutOff, XAxiPmon_GetMetricCounterCutOff, XAxiPmon_EnableExternalTrigger and XAxiPmon_DisableExternalTrigger APIs in xaxipmon.c Modified XAxiPmon_SetMetrics and XAxiPmon_GetMetrics (CR #683746) in xaxipmon.c Added XAxiPmon_EnableEventLog, XAxiPmon_DisableMetricsCounter, XAxiPmon_EnableMetricsCounter APIs in xaxipmon.c to replace macros in this file. Added XAPM_FLAG_XXX macros. Added XAxiPmon_StartCounters and XAxiPmon_StopCounters APIs (CR #683799). Added XAxiPmon_StartEventLog and XAxiPmon_StopEventLog APIs (CR #683801). Added XAxiPmon_GetMetricName API (CR #683803). Deleted XAxiPmon_SetAgent, XAxiPmon_GetAgent declarations (CR #677337) 4.00a bss 01/17/13 To support new version of IP: Added XAPM_METRIC_SET_12 to XAPM_METRIC_SET_15 macros. Added XAxiPmon_SetLogEnableRanges, XAxiPmon_GetLogEnableRanges, XAxiPmon_EnableMetricCounterTrigger, XAxiPmon_DisableMetricCounterTrigger, XAxiPmon_EnableEventLogTrigger, XAxiPmon_DisableEventLogTrigger, XAxiPmon_SetWriteLatencyId, XAxiPmon_SetReadLatencyId, XAxiPmon_GetWriteLatencyId, XAxiPmon_GetReadLatencyId APIs and removed XAxiPmon_SetMetricCounterCutOff, XAxiPmon_GetMetricCounterCutOff, XAxiPmon_EnableExternalTrigger and XAxiPmon_DisableExternalTrigger APIs in xaxipmon.c Added XAPM_LATENCYID_OFFSET, XAPM_CR_EVTLOG_EXTTRIGGER_MASK, XAPM_LATENCYID_RID_MASK and XAPM_LATENCYID_WID_MASK in xaxipmon_hw.h 5.00a bss 08/26/13 To support new version of IP: XAxiPmon_SampleMetrics Macro. Modified XAxiPmon_CfgInitialize, Assert functions Added XAxiPmon_GetMetricCounter, XAxiPmon_SetSampleInterval, XAxiPmon_GetSampleInterval, XAxiPmon_SetWrLatencyStart, XAxiPmon_SetWrLatencyEnd, XAxiPmon_SetRdLatencyStart, XAxiPmon_SetRdLatencyEnd, XAxiPmon_GetWrLatencyStart, XAxiPmon_GetWrLatencyEnd, XAxiPmon_GetRdLatencyStart, XAxiPmon_GetRdLatencyEnd, XAxiPmon_SetWriteIdMask, XAxiPmon_SetReadIdMask, XAxiPmon_GetWriteIdMask and XAxiPmon_GetReadIdMask APIs Renamed : XAxiPmon_SetWriteLatencyId to XAxiPmon_SetWriteId, XAxiPmon_SetReadLatencyId to XAxiPmon_SetReadId, XAxiPmon_GetWriteLatencyId to XAxiPmon_GetWriteId and XAxiPmon_SetReadLatencyId to XAxiPmon_GetReadId. in xaxipmon.c Added Macros XAPM_MC10_OFFSET to XAPM_MC47_OFFSET, XAPM_SMC10_OFFSET to XAPM_SMC47_OFFSET, XAPM_IDMASK_OFFSET, XAPM_CR_IDFILTER_ENABLE_MASK, XAPM_CR_WRLATENCY_START_MASK, XAPM_CR_WRLATENCY_END_MASK, XAPM_CR_RDLATENCY_START_MASK, XAPM_CR_RDLATENCY_END_MASK and XAPM_MAX_COUNTERS_PROFILE. Renamed: XAPM_LATENCYID_OFFSET to XAPM_ID_OFFSET, XAPM_LATENCYID_RID_MASK to XAPM_ID_RID_MASK, XAPM_LATENCYID_WID_MASK to XAPM_ID_WID_MASK. in xaxipmon_hw.h. Modified driver tcl to generate new parameters ScaleFactor, ModeProfile, ModeTrace and ModeAdvanced in Config structure. 6.0 adk 19/12/13 Updated as per the New Tcl API's 6.1 adk 16/04/14 Updated the driver tcl for the newly added parameters in The Axi pmon IP. 6.2 bss 04/21/14 Updated XAxiPmon_CfgInitialize in xaxipmon.c to Reset counters and FIFOs based on Modes(CR#782671). And if both profile and trace modes are present set mode as Advanced. 6.2 bss 03/02/15 To support Zynq MP APM: Added Is32BitFiltering in XAxiPmon_Config structure. Updated XAxiPmon_SetWriteId, XAxiPmon_SetReadId, XAxiPmon_GetWriteId, XAxiPmon_GetReadId XAxiPmon_SetWriteIdMask, XAxiPmon_SetReadIdMask XAxiPmon_GetWriteIdMask, XAxiPmon_GetReadIdMask functions in xaxipmon.c. Added XAPM_RID_OFFSET and XAPM_RIDMASK_OFFSET in xaxipmon_hw.h

6.3     kvn  07/02/15   Modified code according to MISRA-C:2012 guidelines.
6.4   sk   11/10/15 Used UINTPTR instead of u32 for Baseaddress CR# 867425.
                    Changed the prototype of XAxiPmon_CfgInitialize API.
6.5   ms   01/23/17 Modified xil_printf statement in main function for all
                    examples to ensure that "Successfully ran" and "Failed"
                    strings are available in all examples. This is a fix
                    for CR-965028.
      ms   03/17/17 Added readme.txt file in examples folder for doxygen
                    generation.
6.6   ms   04/18/17 Modified tcl file to add suffix U for all macro
                    definitions of axipmon in xparameters.h