https://github.com/slaclab/pix2pgp
A portable readout framework for sparse-readout Detector/Front-End ASICs
https://github.com/slaclab/pix2pgp
asic-design firmware fpga gateware python vhdl
Last synced: 7 days ago
JSON representation
A portable readout framework for sparse-readout Detector/Front-End ASICs
- Host: GitHub
- URL: https://github.com/slaclab/pix2pgp
- Owner: slaclab
- License: other
- Created: 2024-05-15T09:54:25.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2026-06-11T18:52:17.000Z (16 days ago)
- Last Synced: 2026-06-11T19:22:58.457Z (16 days ago)
- Topics: asic-design, firmware, fpga, gateware, python, vhdl
- Language: VHDL
- Homepage:
- Size: 4.63 MB
- Stars: 1
- Watchers: 6
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Pix2PGP
[DOE Code](https://www.osti.gov/doecode/biblio/182066)
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](https://confluence.slac.stanford.edu/x/nIkaGg)
As of `v2.7.8`, Pix2PGP supports the following ASIC variants:
* [SparkPix-S](https://confluence.slac.stanford.edu/x/CZp8F)
* [SparkPix-T](https://confluence.slac.stanford.edu/x/yCczIg)
* [Thriglav](https://confluence.slac.stanford.edu/spaces/ppareg/pages/401976050/Thriglav+-+Accelerate+3D-LGAD+SLAC+FNAL)
* [SparkPix-Sv2](https://confluence.slac.stanford.edu/x/CZp8F)
## 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](https://confluence.slac.stanford.edu/x/XYU8J) 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](https://slaclab.github.io/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