From 6f826cec7c4b2505884007e9a7efc6db3472415e Mon Sep 17 00:00:00 2001 From: StancaPop <53567076+StancaPop@users.noreply.github.com> Date: Fri, 15 Nov 2024 11:57:11 +0200 Subject: [PATCH] docs: Add PulSAR ADC doc (#139) * docs: Add PulSAR ADC doc --- docs/testbenches/project_based/index.rst | 1 + .../project_based/pulsar_adc/index.rst | 338 +++ .../pulsar_adc/pulsar_adc_pmdz_tb.svg | 1923 +++++++++++++++++ 3 files changed, 2262 insertions(+) create mode 100644 docs/testbenches/project_based/pulsar_adc/index.rst create mode 100644 docs/testbenches/project_based/pulsar_adc/pulsar_adc_pmdz_tb.svg diff --git a/docs/testbenches/project_based/index.rst b/docs/testbenches/project_based/index.rst index a852fa56..9b3a1626 100644 --- a/docs/testbenches/project_based/index.rst +++ b/docs/testbenches/project_based/index.rst @@ -11,3 +11,4 @@ Contents ad463x/index ad738x/index + pulsar_adc/index diff --git a/docs/testbenches/project_based/pulsar_adc/index.rst b/docs/testbenches/project_based/pulsar_adc/index.rst new file mode 100644 index 00000000..41af897c --- /dev/null +++ b/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 `. + +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 `__ +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 ` + - :external+hdl:ref:`here ` + * - AXI_DMAC + - :git-hdl:`library/axi_dmac ` + - :external+hdl:ref:`here ` + * - AXI_HDMI_TX + - :git-hdl:`library/axi_hdmi_tx ` * + - :external+hdl:ref:`here ` + * - AXI_I2S_ADI + - :git-hdl:`library/axi_i2s_adi ` * + - --- + * - AXI_PWM_GEN + - :git-hdl:`library/axi_pwm_gen` + - :external+hdl:ref:`here ` + * - AXI_SPDIF_TX + - :git-hdl:`library/axi_spdif_tx ` * + - --- + * - AXI_SYSID + - :git-hdl:`library/axi_sysid ` + - :external+hdl:ref:`here ` + * - AXI_SPI_ENGINE + - :git-hdl:`library/spi_engine/axi_spi_engine ` + - :external+hdl:ref:`here ` + * - SPI_ENGINE_EXECUTION + - :git-hdl:`library/spi_engine/spi_engine_execution ` + - :external+hdl:ref:`here ` + * - SPI_ENGINE_INTERCONNECT + - :git-hdl:`library/spi_engine/spi_engine_interconnect ` + - :external+hdl:ref:`here ` + * - SPI_ENGINE_OFFLOAD + - :git-hdl:`library/spi_engine/spi_engine_offload` + - :external+hdl:ref:`here ` + * - SYSID_ROM + - :git-hdl:`library/sysid_rom ` + - :external+hdl:ref:`here ` + * - UTIL_I2C_MIXER + - :git-hdl:`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 diff --git a/docs/testbenches/project_based/pulsar_adc/pulsar_adc_pmdz_tb.svg b/docs/testbenches/project_based/pulsar_adc/pulsar_adc_pmdz_tb.svg new file mode 100644 index 00000000..dea90cb3 --- /dev/null +++ b/docs/testbenches/project_based/pulsar_adc/pulsar_adc_pmdz_tb.svg @@ -0,0 +1,1923 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + MEMORY INTERCONNECT + + + + TEST MODULE + + TESTBENCH + + PULSAR_ADC_DMA + 40/50/80MHz + + + + + + + + + MISO/SDI + SPI ENGINE FRAMEWORK + CS + SCLK + + + + + + OFFLOAD + + INTER-CONNECT + + + EXECUTION + + AXI REGMAP + + + sys_clk = 100MHz + + + + + + + + AXI PWM GEN + + AXI CLKGEN + spi_clk = 160/100MHz + + + + + + + + DDR VIP + + PS AXI VIP + PROJECT LEVEL BLOCK DESIGN (DUT) + + + + + TOP MODULE + MOSI/SDO + + 32b + + + 32b + trigger + +