Pix2PGP

DOE Code

Copyright Notice:

COPYRIGHT © SLAC National Accelerator Laboratory. All rights reserved. This work is supported [in part] by the U.S. Department of Energy, Office of Basic Energy Sciences under contract DE-AC02-76SF00515.

Usage Restrictions:

Neither the name of the Leland Stanford Junior University, SLAC National Accelerator Laboratory, U.S. Department of Energy nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Introduction

Pix2PGP is a configurable readout core for Detector/Front-End ASICs that feature a sparsified readout scheme. It features ASIC RTL for event building within the detection device, FPGA firmware for merging of the multiple ASIC data streams into a single AXI-Stream frame, and Python software for decoding/unpacking of the aforementioned FPGA-originating frame.

For more info:

• Confluence Page

As of v2.7.8, Pix2PGP supports the following ASIC variants:

• SparkPix-S
• SparkPix-T
• Thriglav
• SparkPix-Sv2

Cloning

$ git clone --recurse-submodules https://github.com/slaclab/pix2pgp.git

Note the use of https://github.com instead of git@github.com:; please configure your client accordingly for HTTPS git repo management (via Github Tokens). If one includes pix2pgp as a submodule to their project, it has to be done via HTTPS.

SLAC users can refer to this Confluence Page on how to set up their Github Token.

Repository Description

The repository is consisted of three main directories:

• gateware/: Contains ASIC-specific files (ASIC top-level and package VHDL files), and the shared RTL VHDL files
• firmware/: Contains the FPGA receiver firmware logic source code, python data decoding support files, and a directory dedicated to GHDL-based quick syntax checking/behavioral-simulation. It also contains a targets/ directory that generates a VCS-based behavioral simulation testbench for each supported ASIC
• software/: Contains auxiliary scripts for testbench-generated data file parsing and benchmarking

How To Import the RTL Sources to Your Project

First of all, one should add this repo as a submodule to their base project ($ git clone --recurse-submodules https://github.com/slaclab/pix2pgp.git)

Manual Import of Source Files

If one wants to include the files manually, it is advised to run $ make ASIC=SparkPixS build within firmware/ghdl/Makefile to generate a complete list of source files. Please read the printed-out warnings to deduce which files you need to import. The $(ASIC) argument needs to be changed accordingly

Note that the Makefile contains specific commands to print-out a full list of the required files for both ASIC RTL Synthesis and ASIC+FPGA Behavioral Simulation cases.

Cadence Genus Ruckus Support

To automatically import the ASIC RTL gateware under Cadence Genus via the ruckus framework, one should invoke the ruckus.tcl script located within the associated directory, via a TCL script of their own. For example, for SparkPixS, this is what the script should look like:

# Load RUCKUS environment and library
source -quiet $::env(RUCKUS_DIR)/vivado_proc.tcl

# Load surf source code
loadRuckusTcl $::env(TOP_DIR)/submodules/surf

# Load SparkPix-S source code
loadRuckusTcl $::env(TOP_DIR)/submodules/pix2pgp/gateware/asics/SparkPixS

# Analyze source code loaded into ruckus for Cadence Genus
AnalyzeSrcFileLists

Synopsys Ruckus Support

To automatically import the ASIC RTL gateware under the Synopsys tools via the ruckus framework, one should invoke the ruckus.tcl script located within the associated directory, via a TCL script of their own. For example, for SparkPixS, this is what the script should look like:

# Load RUCKUS environment and library
source $::env(RUCKUS_QUIET_FLAG) $::env(RUCKUS_PROC_TCL)

# Load the surf library
loadRuckusTcl "$::env(TOP_DIR)/submodules/surf"
AnalyzeSrcFileLists -vhdlLib "surf"

# Load ruckus library (ruckus.BuildInfoPkg.vhd only)
GenBuildString $::env(SYN_DIR)
AnalyzeSrcFileLists -vhdlLib "ruckus"

# Load SparkPix-S source code
loadRuckusTcl $::env(TOP_DIR)/submodules/pix2pgp/gateware/asics/SparkPixS
AnalyzeSrcFileLists -vhdlLib "pix2pgp" -vhdlTop $::env(PROJECT)

How to Decode the Pix2Pgp Data Frames in Your Project

The user needs to import the python files located within firmware/python/pix2pgp. AsicData is the main class that decodes the Pix2Pgp frames. Pix2PgpSparseProcessor is a rogue-based wrapper for that class, the usage of which is explained below.

Example Decoding Script

The script software/scripts/axiDataParser.py can be used as a template to decode data generated by Pix2Pgp. The data format that the script expects are typically generated by VHDL testbenches that write data in hexadecimal format, one byte per line, as a result of a testbench-generated AXI-Stream. The data generated by the VCS testbenches mentioned below can be decoded by this script.

Rogue/Pyrogue Stream Class Example

Provided that the user is running under the rogue environment, they can use the python class Pix2PgpSparseProcessor located under firmware/python/pix2pgp to parse in data that are treated by rogue as a stream. The class in question can also be used as a template, in case the user wishes to store more Pix2Pgp data types in their project.

An example usage can be found below, where a binary data file generated by Pix2Pgp is processed by the Pix2PgpSparseProcessor class, and the native data containers provided by the class are stored in a .pkl file for offline analysis:

import os
import sys
import rogue
rogue.Version.minVersion('6.1.0')
import pyrogue as pr
import pyrogue.utilities.fileio
import pickle
import pix2pgp

dataFilePath='data.dat'

dataReader = rogue.utilities.fileio.StreamReader()

dataProcessor = pix2pgp.Pix2PgpSparseProcessor(
                    rawData  = False,
                    maxAsics = 4,
                    verbose  = 1,
                    asicType = 'SparkPixS'
                )

dataProcessor << dataReader

dataReader.open(dataFilePath)

dataReader.closeWait()

dataDict = {'asicId'        : dataProcessor.asicId,
            'asicLaneValid' : dataProcessor.asicLaneValid,
            'asicHits'      : dataProcessor.asicHits,
            'asicTrgCnt'    : dataProcessor.asicTrgCnt}

with open('pickleData.pkl', 'wb') as f:
    pickle.dump(dataDict, f)

GHDL Support

How to perform simple VHDL syntax checking using GHDL

Navigate to firmware/ghdl and execute: $ make build ASIC=SparkPixS.

How to simulate the design using GHDL

Navigate to firmware/ghdl and execute: $ make tb ASIC=SparkPixS GHDL_STOP_TIME=50us. This will run the GHDL simulator for 50us.

How to simulate using VCS

1. Go to the relevant firmware/targets/ directory; e.g. Pix2PgpSparkPixSEmu if you want to simulate SparkPix-S
2. Set the environment; as of v2.5.2 simulation was done with Vivado 2025.2 and VCS X-2025.06
3. Run make clean && make vcs and then follow the prompts on the terminal to invoke the VCS simulator
4. Observe the simulator's console; a report should be printed-out upon completion of the testbench loop
5. The user can decode the data dump generated by the testbench by running software/scripts/axiDataParser.py with the corresponding verbosity and ASIC-type flags

How to add a new ASIC

A complete How-To is included in the README.md file located under gateware/asics.

How to benchmark total throughput and data transmission latency

A complete How-To is included in the README.md file located under software/scripts/benchmarking.

Contact

Christos Bakalis: cbakalis@slac.stanford.edu