.. _how_to_vcs_simulation:

===============================
How to Simulate Using VCS
===============================

Full-scale behavioral verification of Pix2PGP is done with Synopsys VCS
under the ruckus flow. Each supported ASIC has its own target directory
under ``firmware/targets/``.

Steps
=====

#. Setup Xilinx / Synopsys tooling (refer to :ref:`setup_vivado_setup`).
   As of ``v2.5.2``, simulation is done with **Vivado 2025.2** and
   **VCS X-2025.06**

#. Navigate to the ASIC target directory. For example, for SparkPix-S:

   .. code-block:: bash

      $ cd pix2pgp/firmware/targets/Pix2PgpSparkPixSEmu

   Available targets:

   * ``Pix2PgpSparkPixSEmu``   — SparkPix-S
   * ``Pix2PgpSparkPixSv2Emu`` — SparkPix-Sv2
   * ``Pix2PgpSparkPixTEmu``   — SparkPix-T
   * ``Pix2PgpThriglavEmu``    — Thriglav

#. Clean and build the VCS simulator:

   .. code-block:: bash

      $ make clean && make vcs

   Follow the terminal prompts to invoke the simulator once elaboration
   completes

#. Observe the VCS console. Depending on the testbench configuration, one
   of two things happens:

   * With ``BENCHMARKING_G = false``, a fixed hit pattern is issued and
     the testbench prints a per-event summary
   * With ``BENCHMARKING_G = true``, the testbench sweeps occupancy
     percentages and prints running counters. When the sweep completes, a
     table of ``colBusyCnt``, ``superBusyCnt``, and ``totalLatencyCnt`` is
     printed for every occupancy point (see :ref:`how_to_run_benchmarking`)

#. Decode the AXI-Stream data dump generated by the testbench:

   .. code-block:: bash

      $ python software/scripts/axiDataParser.py \
           --asicType SparkPixS --verbose --input <path/to/data.txt>

Configuring the Testbench
==========================

The testbench top-level generics are declared in
``firmware/targets/Pix2Pgp<Asic>Emu/tb/Pix2Pgp<Asic>EmuTb.vhd``. The main
knobs are:

* ``BENCHMARKING_G``            — sweep occupancy percentages for
  benchmarking rather than a single fixed pattern
* ``BANDWIDTH_STRESS_TEST_G``   — bandwidth-stress mode
* ``COLMANAGER_DATA_DEPTH_G``   — Data FIFO depth per Column Manager
* ``COLMANAGER_STATUS_DEPTH_G`` — Status FIFO depth per Column Manager
* ``TIMEOUT_LIMIT_WIDTH_G``     — width of the Column Supervisor timeout
  watchdog counter
* ``PIPELINE_DATA_G`` /
  ``PIPELINE_STATUS_G`` /
  ``ARB_DOUT_PIPE_G`` /
  ``DATAFIFO_PIPE_G`` /
  ``STATUSFIFO_PIPE_G``         — pipeline stages on the FPGA-side buses
  (relevant when the FPGA receiver is placed near a GT hard block)

Per-column and per-event hit patterns are set via the ``hitLen`` array
inside the testbench body. See :ref:`how_to_run_benchmarking` for how the
``hitsToVhd.py`` helper can be used to generate random patterns.