docs: Add PulSAR ADC doc (#139)

* docs: Add PulSAR ADC doc

docs/testbenches/project_based/index.rst

@@ -11,3 +11,4 @@ Contents
 
    ad463x/index
    ad738x/index
+   pulsar_adc/index

docs/testbenches/project_based/pulsar_adc/index.rst

@@ -0,0 +1,338 @@
+.. _pulsar_adc_pmdz:
+
+PulSAR ADC PMDZ
+================================================================================
+
+Overview
+-------------------------------------------------------------------------------
+
+The purpose of this testbench is to validate the serial interface functionality
+of the :git-hdl:`projects/pulsar_adc` reference design.
+
+The entire HDL documentation can be found here
+:external+hdl:ref:`PULSAR-ADC HDL project <pulsar_adc>`.
+
+Block design
+-------------------------------------------------------------------------------
+
+The testbench block design includes part of the PulSAR ADC HDL reference design,
+along with VIPs used for clocking, reset, PS and DDR simulations.
+
+Block diagram
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ./pulsar_adc_pmdz_tb.svg
+   :width: 800
+   :align: center
+   :alt: PulSAR ADC/Testbench block diagram
+
+Configuration parameters and modes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following parameters of this project that can be configured:
+
+-  CLK_MODE: defines clocking mode of the device's digital interface:
+   Options: 0 - SPI mode
+-  NUM_OF_SDI: defines the number of MOSI lines of the SPI interface:
+   Options: 1 - Interleaved mode
+-  CAPTURE_ZONE: defines the capture zone of the next sample.
+   There are two capture zones: 1 - from negative edge of the BUSY line
+   until the next CNV positive edge -20ns
+-  DDR_EN: defines the type of data transfer. In echo and master clock mode
+   the SDI lines can have Single or Double Data Rates.
+   Options: 0 - MISO runs on SDR.
+
+Build parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The parameters mentioned above can be configured when starting the build, like in
+the following example:
+
+.. shell::
+   :showuser:
+
+   $make CLK_MODE=0 NUM_OF_SDI=1 CAPTURE_ZONE=1 DDR_EN=0
+
+but we recommend using the already tested build configuration modes, that can be
+found in the ``cfg`` section.
+
+Configuration files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following configuration file is available:
+
+   +-----------------------+-----------------------------------------------+
+   | Configuration mode    | Parameters                                    |
+   |                       +----------+------------+--------------+--------+
+   |                       | CLK_MODE | NUM_OF_SDI | CAPTURE_ZONE | DDR_EN |
+   +=======================+==========+============+==============+========+
+   | cfg1                  | 0        | 2          | 1            | 0      |
+   +-----------------------+----------+------------+--------------+--------+
+
+Tests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following test program file is available:
+
+============ ========================================
+Test program Usage
+============ ========================================
+test_program Tests the serial interface capabilities.
+============ ========================================
+
+Available configurations & tests combinations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The test program is compatible with the above mentioned configuration.
+
+CPU/Memory interconnect addresses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Below are the CPU/Memory interconnect addresses used in this project:
+
+=========================  ===========
+Instance                   Address
+=========================  ===========
+spi_pulsar_adc_axi_regmap  0x44A0_0000
+axi_pulsar_adc_dma         0x44A3_0000
+spi_clkgen                 0x44A7_0000
+pulsar_adc_trigger_gen     0x44B0_0000
+=========================  ===========
+
+Interrupts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Below are the Programmable Logic interrupts used in this project:
+
+==================  ===
+Instance name       HDL
+==================  ===
+axi_pulsar_adc_dma  13
+spi_pulsar_adc      12
+==================  ===
+
+
+Test stimulus
+-------------------------------------------------------------------------------
+
+The test program is structured into several tests as follows:
+
+Environment Bringup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The steps of the environment bringup are:
+
+* Create the environment
+* Start the environment
+* Start the clocks
+* Assert the resets
+
+Sanity Test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This test is used to check the communication with the AXI REGMAP module of the
+PulSAR ADC SPI Engine interface, by reading the core VERSION register, along
+with writing and reading the SCRATCH register.
+
+FIFO SPI Test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FIFO SPI Test verifies the simple serial transfers, made through the
+Execution module.
+
+The steps of this test are:
+
+* Start the SPI clock generator (axi_clkgen)
+* Configure the conversion signal generator (axi_pwmgen)
+* Enable SPI Engine & configure the Execution module
+* Set up the interrupts
+* Generate a FIFO transaction
+* Capture and compare the results, using the PEEK register of the AXI SPI Engine
+
+Offload SPI Test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Offload SPI Test verifies the Offload module functionality.
+
+The steps of this test are:
+
+* Configure the DMA
+* Configure the Offload module
+* Start the Offload module
+* Capture and compare the Offload SDI data
+
+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*
+
+Build all the possible combinations of tests and configurations, using only the
+command line.
+
+.. shell::
+   :showuser:
+
+   $cd testbenches/project/pulsar_adc_pmdz
+   $make
+
+*Example 2*
+
+Build all the possible combinations of tests and configurations, using the
+Vivado GUI. This command will launch Vivado, will run the simulation and display
+the waveforms.
+
+.. shell::
+   :showuser:
+
+   $cd testbenches/project/pulsar_adc_pmdz
+   $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/project/pulsar_adc_pmdz
+   $make MODE=gui CFG=cfg1 TST=test_program
+
+The built projects can be found in the ``runs`` folder, where each configuration
+specific build has it's 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_CLKGEN
+     - :git-hdl:`library/axi_clkgen <library/axi_clkgen>`
+     - :external+hdl:ref:`here <axi_clkgen>`
+   * - AXI_DMAC
+     - :git-hdl:`library/axi_dmac <library/axi_dmac>`
+     - :external+hdl:ref:`here <axi_dmac>`
+   * - AXI_HDMI_TX
+     - :git-hdl:`library/axi_hdmi_tx <library/axi_hdmi_tx>` *
+     - :external+hdl:ref:`here <axi_hdmi_tx>`
+   * - AXI_I2S_ADI
+     - :git-hdl:`library/axi_i2s_adi <library/axi_i2s_adi>` *
+     - ---
+   * - AXI_PWM_GEN
+     - :git-hdl:`library/axi_pwm_gen`
+     - :external+hdl:ref:`here <axi_pwm_gen>`
+   * - AXI_SPDIF_TX
+     - :git-hdl:`library/axi_spdif_tx <library/axi_spdif_tx>` *
+     - ---
+   * - AXI_SYSID
+     - :git-hdl:`library/axi_sysid <library/axi_sysid>`
+     - :external+hdl:ref:`here <axi_sysid>`
+   * - AXI_SPI_ENGINE
+     - :git-hdl:`library/spi_engine/axi_spi_engine <library/spi_engine/axi_spi_engine>`
+     - :external+hdl:ref:`here <spi_engine axi>`
+   * - SPI_ENGINE_EXECUTION
+     - :git-hdl:`library/spi_engine/spi_engine_execution <library/spi_engine/spi_engine_execution>`
+     - :external+hdl:ref:`here <spi_engine execution>`
+   * - SPI_ENGINE_INTERCONNECT
+     - :git-hdl:`library/spi_engine/spi_engine_interconnect <library/spi_engine/spi_engine_interconnect>`
+     - :external+hdl:ref:`here <spi_engine interconnect>`
+   * - SPI_ENGINE_OFFLOAD
+     - :git-hdl:`library/spi_engine/spi_engine_offload`
+     - :external+hdl:ref:`here <spi_engine offload>`
+   * - SYSID_ROM
+     - :git-hdl:`library/sysid_rom <library/sysid_rom>`
+     - :external+hdl:ref:`here <axi_sysid>`
+   * - UTIL_I2C_MIXER
+     - :git-hdl:`library/util_i2c_mixer <library/util_i2c_mixer>` *
+     - ---
+
+.. admonition:: Legend
+   :class: note
+
+   ``*`` instantiated only for AD40xx/ADAQ40xx
+
+     - ---
+
+Testbenches related dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :widths: 30 45 25
+   :header-rows: 1
+
+   * - SV dependency name
+     - Source code link
+     - Documentation link
+   * - ADI_REGMAP_CLKGEN_PKG
+     - :git-testbenches:`library/regmaps/adi_regmap_clkgen_pkg.sv`
+     - ---
+   * - ADI_REGMAP_DMAC_PKG
+     - :git-testbenches:`library/regmaps/adi_regmap_dmac_pkg.sv`
+     - ---
+   * - ADI_REGMAP_PKG
+     - :git-testbenches:`library/regmaps/adi_regmap_pkg.sv`
+     - ---
+   * - ADI_REGMAP_PWM_GEN_PKG
+     - :git-testbenches:`library/regmaps/adi_regmap_pwm_gen_pkg.sv`
+     - ---
+   * - ADI_REGMAP_SPI_ENGINE_PKG
+     - :git-testbenches:`library/regmaps/adi_regmap_spi_engine_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`
+     - ---     
+   * - UTILS
+     - :git-testbenches:`library/utilities/utils.svh`
+     - ---
+
+.. include:: ../../../common/more_information.rst
+
+.. include:: ../../../common/support.rst