{"id":51004151,"url":"https://github.com/slaclab/pix2pgp","last_synced_at":"2026-06-20T18:04:07.572Z","repository":{"id":361895089,"uuid":"800946049","full_name":"slaclab/pix2pgp","owner":"slaclab","description":"A portable readout framework for sparse-readout Detector/Front-End ASICs","archived":false,"fork":false,"pushed_at":"2026-06-11T18:52:17.000Z","size":4854,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-06-11T19:22:58.457Z","etag":null,"topics":["asic-design","firmware","fpga","gateware","python","vhdl"],"latest_commit_sha":null,"homepage":"","language":"VHDL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slaclab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-15T09:54:25.000Z","updated_at":"2026-06-04T23:27:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/slaclab/pix2pgp","commit_stats":null,"previous_names":["slaclab/pix2pgp"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/slaclab/pix2pgp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpix2pgp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpix2pgp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpix2pgp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpix2pgp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slaclab","download_url":"https://codeload.github.com/slaclab/pix2pgp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slaclab%2Fpix2pgp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34580071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asic-design","firmware","fpga","gateware","python","vhdl"],"created_at":"2026-06-20T18:04:06.891Z","updated_at":"2026-06-20T18:04:07.565Z","avatar_url":"https://github.com/slaclab.png","language":"VHDL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pix2PGP\n\n[DOE Code](https://www.osti.gov/doecode/biblio/182066)\n\nCopyright Notice:\n            \nCOPYRIGHT © 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.\n\nUsage Restrictions:\n\nNeither 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.\n\n## Introduction\n\nPix2PGP 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.\n\nFor more info:\n\n* [Confluence Page](https://confluence.slac.stanford.edu/x/nIkaGg)\n\nAs of `v2.7.8`, Pix2PGP supports the following ASIC variants:\n\n* [SparkPix-S](https://confluence.slac.stanford.edu/x/CZp8F)\n* [SparkPix-T](https://confluence.slac.stanford.edu/x/yCczIg)\n* [Thriglav](https://confluence.slac.stanford.edu/spaces/ppareg/pages/401976050/Thriglav+-+Accelerate+3D-LGAD+SLAC+FNAL)\n* [SparkPix-Sv2](https://confluence.slac.stanford.edu/x/CZp8F)\n\n\n## Cloning\n\n```\n$ git clone --recurse-submodules https://github.com/slaclab/pix2pgp.git\n```\n\nNote 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.\n\nSLAC users can refer to [this Confluence Page](https://confluence.slac.stanford.edu/x/XYU8J) on how to set up their Github Token.\n\n## Repository Description\nThe repository is consisted of three main directories:\n* `gateware/`: Contains ASIC-specific files (ASIC top-level and package VHDL files), and the shared RTL VHDL files\n* `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\n* `software/`: Contains auxiliary scripts for testbench-generated data file parsing and benchmarking\n\n## How To Import the RTL Sources to Your Project\nFirst of all, one should add this repo as a submodule to their base project ($ git clone --recurse-submodules https://github.com/slaclab/pix2pgp.git)\n\n### Manual Import of Source Files\nIf 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\n\nNote 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.\n\n### Cadence Genus Ruckus Support\nTo 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:\n```\n# Load RUCKUS environment and library\nsource -quiet $::env(RUCKUS_DIR)/vivado_proc.tcl\n\n# Load surf source code\nloadRuckusTcl $::env(TOP_DIR)/submodules/surf\n\n# Load SparkPix-S source code\nloadRuckusTcl $::env(TOP_DIR)/submodules/pix2pgp/gateware/asics/SparkPixS\n\n# Analyze source code loaded into ruckus for Cadence Genus\nAnalyzeSrcFileLists\n```\n### Synopsys Ruckus Support\nTo 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:\n```\n# Load RUCKUS environment and library\nsource $::env(RUCKUS_QUIET_FLAG) $::env(RUCKUS_PROC_TCL)\n\n# Load the surf library\nloadRuckusTcl \"$::env(TOP_DIR)/submodules/surf\"\nAnalyzeSrcFileLists -vhdlLib \"surf\"\n\n# Load ruckus library (ruckus.BuildInfoPkg.vhd only)\nGenBuildString $::env(SYN_DIR)\nAnalyzeSrcFileLists -vhdlLib \"ruckus\"\n\n# Load SparkPix-S source code\nloadRuckusTcl $::env(TOP_DIR)/submodules/pix2pgp/gateware/asics/SparkPixS\nAnalyzeSrcFileLists -vhdlLib \"pix2pgp\" -vhdlTop $::env(PROJECT)\n```\n\n## How to Decode the Pix2Pgp Data Frames in Your Project\nThe 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.\n\n### Example Decoding Script\nThe 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.\n\n### Rogue/Pyrogue Stream Class Example\nProvided 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.\n\nAn 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:\n\n```\nimport os\nimport sys\nimport rogue\nrogue.Version.minVersion('6.1.0')\nimport pyrogue as pr\nimport pyrogue.utilities.fileio\nimport pickle\nimport pix2pgp\n\ndataFilePath='data.dat'\n\ndataReader = rogue.utilities.fileio.StreamReader()\n\ndataProcessor = pix2pgp.Pix2PgpSparseProcessor(\n                    rawData  = False,\n                    maxAsics = 4,\n                    verbose  = 1,\n                    asicType = 'SparkPixS'\n                )\n\ndataProcessor \u003c\u003c dataReader\n\ndataReader.open(dataFilePath)\n\ndataReader.closeWait()\n\ndataDict = {'asicId'        : dataProcessor.asicId,\n            'asicLaneValid' : dataProcessor.asicLaneValid,\n            'asicHits'      : dataProcessor.asicHits,\n            'asicTrgCnt'    : dataProcessor.asicTrgCnt}\n\nwith open('pickleData.pkl', 'wb') as f:\n    pickle.dump(dataDict, f)\n```\n\n## GHDL Support\n\n### How to perform simple VHDL syntax checking using GHDL\nNavigate to `firmware/ghdl` and execute: `$ make build ASIC=SparkPixS`.\n\n### How to simulate the design using GHDL\nNavigate to `firmware/ghdl` and execute: `$ make tb ASIC=SparkPixS GHDL_STOP_TIME=50us`. This will run the GHDL simulator for 50us.\n\n## How to simulate using VCS\n1. Go to the relevant `firmware/targets/` directory; e.g. `Pix2PgpSparkPixSEmu` if you want to simulate SparkPix-S\n2. Set the environment; as of `v2.5.2` simulation was done with `Vivado 2025.2` and `VCS X-2025.06`\n3. Run `make clean \u0026\u0026 make vcs` and then follow the prompts on the terminal to invoke the VCS simulator\n4. Observe the simulator's console; a report should be printed-out upon completion of the testbench loop\n5. 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\n\n## How to add a new ASIC\nA complete How-To is included in the `README.md` file located under `gateware/asics`.\n\n## How to benchmark total throughput and data transmission latency\nA complete How-To is included in the `README.md` file located under `software/scripts/benchmarking`.\n\n### Contact\nChristos Bakalis: cbakalis@slac.stanford.edu\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslaclab%2Fpix2pgp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslaclab%2Fpix2pgp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslaclab%2Fpix2pgp/lists"}