docs: IRQ handler testbench

Signed-off-by: Istvan-Zsolt Szekely <istvan.szekely@analog.com>

Author: IstvanZsSzekely

docs/testbenches/common/dependency_common.rst

@@ -7,6 +7,9 @@ Common with most testbenches:
    * - SV dependency name
      - Source code link
      - Documentation link
+   * - IRQ_HANDLER
+     - :git-testbenches:`library/utilities/irq_handler_pkg.sv`
+     - ---
    * - LOGGER_PKG
      - :git-testbenches:`library/utilities/logger_pkg.sv`
      - ---

docs/testbenches/ip_based/irq_handler/index.rst

@@ -0,0 +1,188 @@
+.. _irq_handler_tb:
+
+IRQ handler
+================================================================================
+
+Overview
+-------------------------------------------------------------------------------
+
+The purpose of this testbench is to give engineers a sandbox testbench, where
+they can test the interrupt request handler class.
+
+Block design
+-------------------------------------------------------------------------------
+
+The block design is based on the test harness with the addition of an IO VIP.
+The VIP is configure to be in master mode and connected to the interrupt
+controller's bit 0 position.
+
+Block diagram
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ./irq_handler_tb.svg
+   :width: 800
+   :align: center
+   :alt: IRQ_Handler/Testbench block diagram
+
+Configuration parameters and modes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are no parameters that can be configured in the testbench configuration
+files.
+
+Build parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are no build parameters for this testbench.
+
+Configuration files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As this is a sandbox testbench, engineers are encouraged to change parameters
+and see what happens in the simulation. Since there are no parameters available
+for edit, the coniguration file's purpose is to give the testbench instance a
+name.
+
+Tests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following test program file is available:
+
+============ ==============================
+Test program Usage
+============ ==============================
+test_program Creates a basic test stimulus.
+============ ==============================
+
+Available configurations & tests combinations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The test program is compatible with the configuration.
+
+CPU/Memory interconnects addresses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Below are the CPU/Memory interconnect addresses used in this project:
+
+======== ===========
+Instance Address
+======== ===========
+axi_intc 0x4120_0000
+======== ===========
+
+Interrupts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Below are the Programmable Logic interrupts used in this project:
+
+============= ===
+Instance name HDL
+============= ===
+irq_test_vip  0
+============= ===
+
+Test stimulus
+-------------------------------------------------------------------------------
+
+The test program is responsible for configuring and running the sequencers.
+
+Environment Bringup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The steps of the environment bringup are:
+
+* Create the environment
+* Link the agents
+* Instantiate the IRQ handler class
+* Start the environment
+* Start the clocks
+* Assert the resets
+
+IRQ handler testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Register the IO VIP device event to the IRQ handler
+* Start the IRQ handler class
+* Create a subthread to catch the triggered event from IRQ handler
+* Generate an IRQ and see if the subthread is triggered
+
+Priority packet generation testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Create 10 priority and 10 non-priority packets at the same time and check if
+  the priority packets are processed first.
+
+.. note::
+
+   Priority packet processing order is checked manually.
+
+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 <https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository>`__
+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/irq_handler
+   $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/irq_handler
+   $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/irq_handler
+   $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
+-------------------------------------------------------------------------------
+
+Testbenches related dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: ../../common/dependency_common.rst
+
+Testbench specific dependencies: None
+
+.. include:: ../../../common/more_information.rst
+
+.. include:: ../../../common/support.rst