Doc IRQ handler

docs/library/utilities/index.rst

@@ -8,5 +8,6 @@ Contents
 
 .. toctree::
    :maxdepth: 1
+   :glob:
 
-   Test Harness <test_harness/index>
+   */index

docs/library/utilities/irq_handler/index.rst

@@ -0,0 +1,67 @@
+.. _irq_handler:
+
+IRQ Handler
+================================================================================
+
+Overview
+-------------------------------------------------------------------------------
+
+The purpose of this class is to provide an object that can simulate a processor
+interrupt handler. The class relies on the AXI Interrupt Controller from AMD and
+it uses an IO VIP to monitor the IRQ pin. 
+
+.. svg:: library/utilities/irq_handler/irq_handler.svg
+   :align: center
+
+Variables
+-------------------------------------------------------------------------------
+
+None are available for direct external access.
+
+Functions
+-------------------------------------------------------------------------------
+
+function new();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates the irq_handler object. It requires a name, a master AXI sequencer
+reference object with which it accesses the interrupt controller, the address of
+the controller, the IO VIP interface handler and a parent if it's the case.
+
+function void enable_software_testing();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enables software testing.
+
+task software_irq_testing();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Triggeres a software interrupt test, which can be used to verify certain
+functions at system powerup.
+
+task start();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starts the IRQ handler, which configures and enables the interrupt controller.
+After that, it monitors the IO VIP, waiting for the arrival of interrupts. Once
+triggered, it goes over the list of triggered interrupts and signals the
+responsible classes to handle their respective interrupt. If software testing is
+enabled, it will automatically trigger a software interrupt after starting the
+monitor.
+
+function event register_device(input int position);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Registers an event reference for an object, that has an interrupt signal
+connected to the controller. Gives a fatal error if a device is already
+registered in the same location.
+
+Usage
+-------------------------------------------------------------------------------
+
+* Declare the irq handler, set up with the required parameters
+* Registers all devices that are connected to the interrupt controller
+* Optionally enable software interrupt
+* Start the irq handler
+
+.. include:: ../../../common/support.rst

docs/library/utilities/irq_handler/irq_handler.txt

@@ -0,0 +1,30 @@
+# Classes
+
+# Base
+adi_reporter: {shape: class}
+adi_component: {shape: class}
+m_axi_sequencer: {shape: class}
+io_vip: {shape: class}
+
+# Scoreboard
+irq_handler: {
+  shape: class
+  \#irq_vip_if
+  \#irq_event_list
+  \#irq_valid_list
+  \#software_testing
+  +enable_software_testing()
+  +software_irq_testing()
+  +start()
+  +register_device()
+}
+
+# Inheritances
+
+adi_reporter <- adi_component: {shape: triangle; source-arrowhead.style.filled: false}
+adi_component <- irq_handler: {shape: triangle; source-arrowhead.style.filled: false}
+
+# Aggregations
+
+irq_handler <- m_axi_sequencer: {source-arrowhead: {shape: diamond; style.filled: false}}
+irq_handler <- io_vip: {source-arrowhead: {shape: diamond; style.filled: true}}

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