Select a Protocol — PGP2b vs PGP3 vs PGP4 vs HTSP

Each board+target chooses one protocol layer from firmware/common/<proto>/. Use this table to pick the right one.

Decision Matrix

Protocol	Line rates	Lanes / VCs	Forward error correction	When to choose
PGP2b	1.25, 2.5, 3.125 Gbps	up to 8 / 4 VC	No	Legacy detectors; existing PGP2b firmware ecosystems.
PGP3	6.25, 10.3125 Gbps	up to 8 / 4 VC	Optional (PGP3 RS-FEC)	Mid-rate links; broad camera/detector support.
PGP4	6.25, 10.3125, 12.5, 15.46875, 25 Gbps	up to 8 / 4 VC	Optional (PGP4 RS-FEC; required at 25 Gbps)	Default for new designs unless 100G is needed.
HTSP	100 Gbps (4 × 25 GbE lanes per QSFP)	1 / N	802.3 RS-FEC (KP-FEC)	When you need ≥100 Gbps aggregate, e.g. detector farms.

Where to Find the Layer

For each protocol, the RTL lives under:

firmware/common/<proto>/
    hardware/<Board>/core/Hardware.vhd       # board adapter
    shared/rtl/PgpLaneRx.vhd                  # RX VC path
    shared/rtl/PgpLaneTx.vhd                  # TX VC path
    shared/rtl/gtyUs+/PgpGtyLane.vhd          # GTY UltraScale+ lane
    shared/rtl/gthUs/PgpLane.vhd              # GTH UltraScale lane

Replace pgp4 with pgp2b / pgp3 / htsp (HTSP uses an HtspWrapper + HtspRxFifo / HtspTxFifo instead of PgpLane*).

Switching Protocols on an Existing Board

Suppose XilinxVariumC1100Pgp4_6Gbps works and you want a PGP3 variant.

1. Clone the target directory:

   cp -r firmware/targets/XilinxVariumC1100/XilinxVariumC1100Pgp4_6Gbps \
         firmware/targets/XilinxVariumC1100/XilinxVariumC1100Pgp3_6Gbps
   

2. Edit the new top-level VHDL. Find the Hardware entity instantiation and re-target the library:

   -- before
   U_Hardware : entity work.Hardware  -- from common/pgp4/hardware/<Board>/core/
   
   -- after — same entity name, but bound to the pgp3 library
   -- Achieved by changing the ruckus.tcl loadRuckusTcl line below.
   

3. Edit the new ruckus.tcl:

   # before
   loadRuckusTcl $::env(PROJ_DIR)/../../../common/pgp4/hardware/XilinxVariumC1100
   
   # after
   loadRuckusTcl $::env(PROJ_DIR)/../../../common/pgp3/hardware/XilinxVariumC1100
   

   Confirm that firmware/common/pgp3/hardware/XilinxVariumC1100/ exists for that board+protocol pair — not every board ships every protocol.

4. Update RATE_G to a PGP3-supported value (PGP3 does not support line rates above 10.3125 Gbps).

5. Build and verify with Run the PGP Test Suite.

HTSP Differs

HTSP uses 100 GbE-style framing rather than the PGP virtual-channel model. The Hardware adapter instantiates HtspWrapper instead of PgpLaneWrapper; the software path uses software/scripts/HtspTesting.py instead of PgpTesting.py. See Protocol Variants for the architectural differences.