| axipmon Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

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
    6.10  ht   06/23/23 Added support for system device-tree flow.
    6.12  ht   12/01/24 Fix GCC warnings.