| trafgen Vitis Drivers API Documentation

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

trafgen Documentation

This file contains the implementation of the AXI Traffic Generator driver.User documentation for the driver functions is contained in this file in the form of comment blocks at the front of each function.

The AXI Traffic Generator IP is designed to generate AXI4 traffic which can be used to stress different modules/interconnect connected in the system. Different configurable options allow the user to generate a wide variety of traffic based on their requirements. The core is broadly separated into a master and slave block, each of which contains the write block and read block. Other support features are provided by the Control registers and Internal RAMs.

The commands to be issued by the AXI traffic generator are loaded in a 128-bit wide, 512 deep command RAM through AXI Slave interface. After the core is enabled, control logic issues the write/read commands based on the command settings programmed. The core updates the Status registers and asserts interrupts on the completion of issuing programmed commands.

The Axi Traffic Genrator has five different modes:

- Advanced Mode: Advanced Mode allows full control over the traffic generation Control registers are provided to you to program the core to generate different AXI4 transactions.
- Basic Mode: Basic Mode allows basic AXI4 traffic generation with less resource overhead.
- Static Mode: Static Mode allows you to generate a simple AXI4 traffic with very less resource and minimum processor intervention.In this Mode the core continuously generates fixed address and fixed length INCR type read and write transfers.
- System Init Mode: System Init Mode is a special Mode where core provides only AXI4-Lite Master write interface.This mode can be used in a system without a processor to initialize the system peripherals with preconfigured values on system reset.
- Streaming Mode: In Streaming Mode the core can be configured to generate traffic based on the register configuration.

Initialization & Configuration

The XTrafGen_Config structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on HW build properties.

To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized in the following way:

- XTrafGen_LookupConfig(DeviceId) - Use the divide identifier to find the static configuration structure defined in xtrafgen_g.c. This is setup by the tools. For some operating systems the config structure will be initialized by the software and this call is not needed.
- XTrafGen_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a configuration structure provided by the caller. If running in a system with address translation, the provided virtual memory base address replaces the physical address present in the configuration structure.

Command Handling

AXI Traffic Generator core operates based on the commands programmed into Command and Parameter RAMs. The CMDRAM and PARAMRAM is divided into two regions: write and read. Each region can hold 256 entries. Once the core is enabled, the internal control logic issues write/read commands. To handle command programming efficiently, we are maintaining a software list of commands. Following APIs are provided to handle this mechanism:

- XTrafGen_AddCommand(): This function prepares the Command Words and Parameter Word from the Command structure passed from the user application. It then adds to a software list of commands.
- XTrafGen_WriteCmdsToHw(): This function writes the prepared list of Command and Parameter Words prepared to CMDRAM and PARAMRAM.
- XTrafGen_GetLastValidIndex(): This function gets last Valid Command Index of Write/Read region. The last valid command index is used to set 'my_depend' and 'other_depend' fields of the Command RAM.
- XTrafGen_EraseAllCommands(): This function clears the list of commands maintained in software and also updates the respective RAMs.
- XTrafGen_PrintAllCmds(): This function displays the list of commands.

Master RAM Handling

AXI Traffic Generator uses MSTRAM to

- Take data from this RAM for write transactions
- Store data to this RAM for read transaction User need to call this API to write/read to/from Master RAM,
- XTrafGen_AccessMasterRam() - This function programs the Master RAM with the data which is used in master logic. The amount of the data is limited by the size of master RAM.

Interrupts

The driver defaults to no interrupts at initialization such that interrupts must be enabled if desired. An interrupt is generated for one of the following conditions:

- Master Logic Completion Interrupt
- Error Interrupt (For Master and Slave Errors)

The application can control which interrupts are enabled using these functions:

- XTrafGen_EnableMasterCmpInterrupt()
- XTrafGen_MasterErrIntrEnable()
- XTrafGen_SlaveErrIntrEnable()

The interrupt system has to be set up and if the interrupts are enabled, Traffic Generator notifies the software either about the completion or an error in transfer through interrupts.

Examples

We provided two examples to show how to use the driver API:

- One for interrupt mode (xtrafgen_interrupt_example.c)
- One for polling mode (xtrafgen_polling_example.c)

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.

RTOS Independence

This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.00a srt  01/24/13 First release
    1.01a adk  03/09/13 Updated Driver to Support Streaming and Static Mode
    2.00a adk  16/09/13 Fixed CR:737291
    2.01a adk  21/10/13 Fixed CR:740522 Updated the MasterRam offset as per latest
                  IP.This driver is valid only for IP(v2.0) onwards. The
                  XTG_MASTER_RAM_OFFSET has been changed from
                  0x10000 to 0xc000.
    2.01a adk  15/11/13 Fixed CR:760808 added Macro's for the New bit fields added
                          in the latest tarfgen IP(v2.0).
    3.0   adk  12/10/13 Updated as per the New Tcl API's
    3.1   adk  28/04/14 Fixed CR:782131 Incorrect mask value for the
                  loopenable bit.
    3.2   adk  05/08/14 Fixed CR:798742 The last word of 8KB Master RAM in
                  axi traffic generator can't access and CR:799554
                          Some incorrect parameter in axi traffic generator driver.
    4.0   sd  19/08/15 Fixed CR:876564 Added 64-bit Support to axi traffic generator
                 driver.
    4.1   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.
          ms  04/05/17 Added tabspace for return statements in functions of
                       trafgen examples for proper documentation while
                       generating doxygen and also modified filename tag in
                       master streaming example file to include it in doxygen
                       examples.
    4.2   ms  04/18/17 Modified tcl file to add suffix U for all macros
                       definitions of trafgen in xparameters.h
    4.4   sd   09/03/20 Updated makefile for parallel execution.
    4.7   ar   03/07/24 Modified trafgen intr examples added macro for Interrupt ID.
    4.8   ht   12/01/24 Fixed GCC warnings.