.. _how_to_decode_data:

============================================
How to Decode Pix2PGP Data with the Parser
============================================

The ``software/scripts/axiDataParser.py`` script decodes AXI-Stream data
generated by the VHDL testbenches. It expects a text file containing the
AXI-Stream in hexadecimal format — one byte per line — which is the format
produced by the VCS testbenches described in :ref:`how_to_vcs_simulation`.

Usage
=====

.. code-block:: bash

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

* ``--asicType`` — selects the ASIC-specific decoder class (must match one
  of the entries in ``asicTypeDict``: ``SparkPixS``, ``SparkPixT``,
  ``Thriglav``, ``SparkPixSv2``, or the user's own custom ASIC)
* ``--verbose``  — enables per-event printouts
* ``--rawData``  — decode raw data words without unpacking them into ADC /
  row / ToA / ToT (useful when developing a new ASIC integration)

Under the Hood
==============

The parser is a thin wrapper around the ``AsicData`` class exported by the
``pix2pgp`` Python package. The class hierarchy is:

* ``AsicParameters`` — per-ASIC constants (``numOfLanes``, ``numOfCols``,
  ``wordLen``)
* ``Pix2PgpHeaderFormat`` — decodes the ASIC lane frame header
* ``Pix2PgpColMetadataFormat`` — decodes the per-column metadata word
* ``SparseDataFormat`` — decodes individual hit words (ADC / row / ToA /
  ToT depending on the ASIC)
* ``Pix2PgpFpgaRxDataFormat`` — decodes the consolidated FPGA-side frame
  (preamble, header, per-lane lengths, trailer)
* ``LaneData`` / ``AsicData`` — event containers

All classes are defined under ``firmware/python/pix2pgp/``.