diff --git a/docs/testbenches/ip_based/index.rst b/docs/testbenches/ip_based/index.rst index d332b0e9..df88ecf4 100644 --- a/docs/testbenches/ip_based/index.rst +++ b/docs/testbenches/ip_based/index.rst @@ -9,5 +9,6 @@ Contents .. toctree:: :maxdepth: 1 + axis_sequencers/index base/index - axis_sequencers/index \ No newline at end of file + util_pack/index diff --git a/docs/testbenches/ip_based/util_pack/index.rst b/docs/testbenches/ip_based/util_pack/index.rst new file mode 100644 index 00000000..c10b2f40 --- /dev/null +++ b/docs/testbenches/ip_based/util_pack/index.rst @@ -0,0 +1,277 @@ +.. _util_pack: + +Util Pack +================================================================================ + +Overview +------------------------------------------------------------------------------- + +The purpose of this testbench is to validate the packaging functionality of the +:git-hdl:`library/util_pack/util_cpack2 ` and +:git-hdl:`library/util_pack/util_upack2 ` IP +cores. + +The entire HDL documentation can be found +:external+hdl:ref:`here ` and +:external+hdl:ref:`here `. + +Block design +------------------------------------------------------------------------------- + +The block design is based on the test harness with the DUT being the 2 packer +IPs and other auxiliary modules. For the ``util_upack`` IP testing, the +auxiliary modules are a DMAC, a master and a slave AXI4 Stream VIP. The AXIS +VIP is used to generate data for the DMAC IP. The DMAC IP then passed the input +data to the output AXIS interface, which is used by the util_upack IP. The +util_upack IP unpacks the data on the respective lanes. The data is +concatenated and fed into the slave AXIS VIP for verification. The +``util_cpack`` IP testing uses the same IPs, but in reversed order and +different configuration to match the required interfacing. + +Block diagram +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: ./util_pack_tb.svg + :width: 800 + :align: center + :alt: Util_pack/Testbench block diagram + +Configuration parameters and modes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following parameters of this project that can be configured: + +- CHANNELS: defines the data generation mode: + Integer value between 2 and 16 +- SAMPLES: defines the valid delays between data beats: + Options: 2, 4, 8, 16 +- WIDTH: defines the valid delays between packets: + Options: 8, 16, 32, 64 + +.. note:: + + The max width is calculated with: CHANNELS*SAMPLES*WIDTH and it cannot + exceed 2048. + +Build parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The parameters mentioned above can be configured when starting the build, like +in the following example: + +.. shell:: + :showuser: + + $make CHANNELS=3 SAMPLES=2 WIDTH=16 + +Configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following configuration files are available: + + +-----------------------+-----------------------------+ + | Configuration mode | Parameters | + | +----------+---------+--------+ + | | CHANNELS | SAMPLES | WIDTH | + +=======================+==========+=========+========+ + | cfg1 | 3 | 2 | 16 | + +-----------------------+----------+---------+--------+ + | cfg_rand | random | random | random | + +-----------------------+----------+---------+--------+ + +Tests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following test program file is available: + +============ ========================= +Test program Usage +============ ========================= +test_program Tests the packer modules. +============ ========================= + +Available configurations & tests combinations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The test program is compatible with all the above-mentioned configurations. + +CPU/Memory interconnects addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +=========== =========== +Instance Address +=========== =========== +axi_intc 0x4120_0000 +ddr_axi_vip 0x8000_0000 +dmac_rx 0x5000_0000 +dmac_tx 0x5001_0000 +=========== =========== + +Interrupts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nothing connected. + +Test stimulus +------------------------------------------------------------------------------- + +The test program is running in parallel for both TX and RX testing in the same +code space. + +Environment Bringup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The steps of the environment bringup are: + +* Create the environment +* Start the environment +* Start the clocks +* Assert the resets + +Packer testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Configure the data_length +* Enable RX and TX DMA +* Initializes the sequencers, monitors and scoreboards +* Configures the DMA +* Configures the watchdog +* Starts the data transmission and the watchdog +* Waits for scoreboard to check all the data +* Stops the watchdog + +.. warning:: + + Increasing the hardcoded value for the data length might cause the watchdog + timer to trigger prematurely! + +Building the test bench +------------------------------------------------------------------------------- + +The testbench is built upon ADI's generic HDL reference design framework. +ADI does not distribute compiled files of these projects so they must be built +from the sources available :git-hdl:`here ` and :git-testbenches:`here `, +with the specified hierarchy described :ref:`build_tb set_up_tb_repo`. +To get the source you must +`clone `__ +the HDL repository, and then build the project as follows: + +**Linux/Cygwin/WSL** + +*Example 1* + +Building and simulating the testbench using only the command line. + +.. shell:: + :showuser: + + $cd testbenches/ip/util_pack + $make + +*Example 2* + +Building and simulating the testbench using the Vivado GUI. This command will +launch Vivado, will run the simulation and display the waveforms. + +.. shell:: + :showuser: + + $cd testbenches/ip/util_pack + $make MODE=gui + +*Example 3* + +Build a particular combination of test and configuration, using the Vivado GUI. +This command will launch Vivado, will run the simulation and display the +waveforms. + +.. shell:: + :showuser: + + $cd testbenches/ip/util_pack + $make MODE=gui CFG=cfg1 TST=test_program + +The built project can be found in the ``runs`` folder, where each configuration +specific build has its own folder named after the configuration file's name. +Example: if the following command was run for a single configuration in the +clean folder (no runs folder available): + +``make CFG=cfg1`` + +Then the subfolder under ``runs`` name will be: + +``cfg1`` + +Resources +------------------------------------------------------------------------------- + +HDL related dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :widths: 30 45 25 + :header-rows: 1 + + * - IP name + - Source code link + - Documentation link + * - AXI_DMAC + - :git-hdl:`library/axi_dmac` + - :external+hdl:ref:`here ` + * - UTIL_CPACK2 + - :git-hdl:`library/util_pack/util_cpack2 ` + - :external+hdl:ref:`here ` + * - UTIL_UPACK2 + - :git-hdl:`library/util_pack/util_upack2 ` + - :external+hdl:ref:`here ` + +Testbenches related dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :widths: 30 45 25 + :header-rows: 1 + + * - SV dependency name + - Source code link + - Documentation link + * - ADI_REGMAP_DMAC_PKG + - :git-testbenches:`library/regmaps/adi_regmap_dmac_pkg.` + - --- + * - ADI_REGMAP_PKG + - :git-testbenches:`library/regmaps/adi_regmap_pkg.sv` + - --- + * - DMA_TRANS + - :git-testbenches:`library/drivers/dmac/dma_trans.sv` + - --- + * - DMAC_API + - :git-testbenches:`library/drivers/dmac/dmac_api.sv` + - --- + * - LOGGER_PKG + - :git-testbenches:`library/utilities/logger_pkg.sv` + - --- + * - M_AXI_SEQUENCER + - :git-testbenches:`library/vip/amd/m_axi_sequencer.sv` + - --- + * - M_AXIS_SEQUENCER + - :git-testbenches:`library/vip/amd/m_axis_sequencer.sv` + - --- + * - REG_ACCESSOR + - :git-testbenches:`library/regmaps/reg_accessor.sv` + - --- + * - S_AXI_SEQUENCER + - :git-testbenches:`library/vip/amd/s_axi_sequencer.sv` + - --- + * - S_AXIS_SEQUENCER + - :git-testbenches:`library/vip/amd/s_axis_sequencer.sv` + - --- + * - WATCHDOG + - :git-testbenches:`library/drivers/common/watchdog.sv` + - :ref:`watchdog` + * - UTILS + - :git-testbenches:`library/utilities/utils.svh` + - --- + +.. include:: ../../../common/more_information.rst + +.. include:: ../../../common/support.rst diff --git a/docs/testbenches/ip_based/util_pack/util_pack_tb.svg b/docs/testbenches/ip_based/util_pack/util_pack_tb.svg new file mode 100644 index 00000000..7155f915 --- /dev/null +++ b/docs/testbenches/ip_based/util_pack/util_pack_tb.svg @@ -0,0 +1,1865 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + TEST MODULE + + TEST PROGRAM + + + AXIS VIP + + + + DMAC + + + + UPACK + + + + AXIS VIP + + + + AXIS VIP + + + + CPACK + + + + DMAC + + + + + + + + + + AXIS VIP + + + DDR VIP + + PS AXI VIP + UNIT LEVEL BLOCK DESIGN + Util UPack + Util CPack + + + + TOP MODULE + + +