Firmware¶

Version 0.9.3¶

Note

Software version 0.9.4 or higher must be used with this FW release.

Created on 18th January 2024.

Readout: Add support for instantiating SLink blocks in multiple quads
Payload simulation: Fix error encountered in Vivado 2024.2 (use of newly reserved keyword)

Version 0.9.2¶

Created on 18th December 2024.

Update to IPbus FW v1.14.1
Serenity S1: Add support for instantiating readout links (SLinks).

Version 0.9.1¶

Created on 4th December 2024.

Update to v1.14 of IPbus firmware
Serenity Z1: Update CI builds to Vivado 2022.2
Serenity Z1: Re-introduce BC0 workaround for TTC stream bitflips
Serenity S1: Resolve timing failures for builds with lpGBT, and add corresponding example design
Serenity S1: Add ability to reset C2C link

Version 0.9.0¶

Created on 3rd October 2024.

Add support for new boards: Apollo CM Rev 2 & Serenity S1
Updated to IPBB version dev/2024b
Info: Add site ID register (to distinguish FW loaded on each site of boards with two FPGAs)
TCDS: Add support for instantiating TCDS2 relay (e.g. for 2nd FPGA on Apollo)
CSP: Change to format 1 of the link ID 1 control word (tx engine)
CSP: Use clearer name for CSP values in mgt_kind_t type
- CSP16 and CSP25 rather than GTH16, GTY16 and GTH25
lpGBT: Use QPLL rather than CPLLs
lpGBT: Fix CDC bug in IC-EC mux
SLink: Rename test pattern generator entity (for clarity)
Payload testbench: Update logic to avoid segfault in Vivado 2023.2
Payload testbench: Update clock period to ensure that auxiliary clocks are in sync with LHC clock
Declare CLOCK_DELAY_GROUP to minimise skew between 40MHz and payload clocks
Add workaround for reorder_files bug in Vivado 2023.2

Migration guide: 0.8.x to 0.9.0¶

If you instantiate CSP firmware in your design, update the link fields in your emp_project_decl REGION_CONF constant as follows:
- GTH16 → CSP16
- GTY16 → CSP16
- GTY25 → CSP25

Version 0.8.2¶

Created on 13th Feb 2024.

lpGBT: Add simple combinatorial mux for driving IC frames over the EC channel.
Disable PCIe AXI clock workaround from Vivado 2023.2 (since XDMA bug was resolved in the corresponding XDMA IP core version).
Add assertion for availability of ref clock - so that there’s a clear error message if one tries to instantiate link firmware in regions without the requisite ref clock type.
CI: Update to IPBB 2023a.
CI: Update gendecoders command to use check committed address decoder files in BE-only jobs.

Version 0.8.1¶

Created on 30th July 2023.

Backend links: Updated TX core to prevent filler word being inserted between orbit tag and first valid word of packet.
Backend links: Updated RX core to pass through all 32 bits from link ID word 1, to support new format for that word (required for use with APx).

Version 0.8.0¶

Created on 4th July 2023.

Backend links: Updated encoding and improved robustness (as part of tests with APx) - notably:
- Reversed bit ordering in scrambler
- Added error injection capabilities
- Aded new status registers and widened some existing counters (incl. in alignment monitoring block)
- Re-wrote index correction mechanism entities to improve robustness
Simulation testbench: Fixed phase relation of 40MHz, payload clock and payload reset so that now matches phase relation in synthesised firmware.
Frontend links: Added support for lpGBT v1

Version 0.7.5¶

Created on 9th February 2023.

Added build for Apollo Rev2 (VU13P-1)
Fixed bugs in UDP-based simulation.
SLink: Updated to newer version of IP core & protocol
SLink: Fixed reset latency bug in CRC block.

Version 0.7.4¶

Created on 13th January 2023.

Testbench (for payload testing): Fixed buffer file formatting bug

Version 0.7.3¶

Created on 14th October 2022.

Backend links: Updated constraints to work in designs with TX- or RX-only RX CSP cores
CI: Updated to IPBB 2022f

Version 0.7.2¶

Created on 23rd October 2022.

Added emp_slink_types to package .dep files for various boards

Version 0.7.1¶

Fixed Vivado 2022.1 errors in TCDS2 ‘false path’ constraints

Version 0.7.0¶

Created on 13th October 2022.

Added support for lpGBT and GBT links
Added support for SLink readout links
BE MGT links: Updated from Hermes to CSP protocol, including support for back-to-back packets
- As part of this, added last and start_of_orbit fields to lword type. On input links, start and last will now be high on the first and last clock cycle of each packet, and start_of_orbit will be high on the first clock cycle of the packet that contains data from the BX0 collision. valid is still high inside packets, and low for any filler words in spaces between packets. These fields have the same meaning on output links. A more detailed description of these can be found in the … page.
Added ability to suppress data on input channels during configuration of buffers and links, then enable all inputs in synchronised manner.
- When inputs are suppressed, start_of_orbit, start and last will all be low, strobe will be high, and the value of data is undefined.
- When inputs are enabled at the end of buffer/MGT configuration, the software writes to the ‘input enable’ register, and then for each input channel the suppression stops in the next orbit when start_of_orbit is high.
BE MGT links: Added support for setting value of MGT Tx driver settings.
Datapath: Fixed bug that caused region-local BC0 to be many clock cycles later than BC0 in TTC block.
TTC interfaces: Added more monitoring counters
TTC interfaces: Moved source select and ‘has interface’ registers off 40MHz clock, so that they still work if external TTC clock stops or TTC configuration fails.

Migration guide: 0.6.x to 0.7.0¶

Add use work.emp_slink_types.all; to the top of your emp_project_decl VHDL file, and add the following SLINK_CONF constant to the emp_project_decl package:
```
constant SLINK_CONF : slink_conf_array_t := (
  others      => kNoSlink
  );
```
You can keep this others => kNoSlink value unless you need to use SLink links, or are otherwise explictly testing readout firmware and hence need the SLink firmware to be instantiated.

Add use work.emp_slink_types.all; to the top of your emp_payload VHDL file, and add the following three new emp_payload ports:

clk40        : in std_logic;
slink_q      : out slink_input_data_quad_array(SLINK_MAX_QUADS-1 downto 0);
backpressure : in std_logic_vector(SLINK_MAX_QUADS-1 downto 0)

Also, note that the format of the buffer data files has changed in order to support new lword fields. The new format is summarised in the Buffer data files page.

Version 0.7.0, alpha pre-release¶

Note

This tag should only be used if you need to instantiate lpGBT links in your design.

Created on 27th March 2022.

First implementation of lpGBT and GBT links included in framework.

Version 0.6.8¶

Created on 26th March 2022.

Resolved bug in frequency of XDMA clocks in Vivado 2021.2 (likely affects all Vivado versions since 2020.2.2). This Vivado bug led to paths for those clocks being timed in with half of the frequency that actually exists in hardware - as a result, errors appear in the reset butler command for all TTC sources.
BE links: Resolved error with setting USER_CLOCK_ROOT in Vivado 2019.2

Version 0.6.7¶

Created on 14th March 2022.

Clocking: Declare the 40MHz ‘internal’ clocks (input to MMCM) from different sources as logically exclusive, so that Vivado doesn’t time those in.
TTC: Add signal property to ensure that ttc/tcds2_interface_stat is not renamed in optimisation.
Refactored CI (merged package & publish steps into main build job)
Serenity KU15P SO2: Added example design with 240MHz payload clock.

Version 0.6.6¶

Created on 2nd March 2022.

Serenity CPLL-based PCIe designs: Add workaround for ‘double requested freq’ Vivado bug encountered from 2020.2.2.
BE links: Set USER_CLOCK_ROOT for MGT clocks (for some builds, Vivado used an inappropriate clock region)
BE links: Permanently power down RX/TX MGTs in regions where only one direction requested (to improve Vivado power estimates).
TTC: Increase TTC_DEL constant, to support 240MHz payload clock on VU13P
Serenity VU7P: Add BE MGT links to more regions in example design.

Version 0.6.5¶

Created on 6th February 2022.

Apollo: Updated build to use v1.2.2 tag of the Apollo CM_FPGA_FW repo (for consistency with current Zynq configuration on boards in TIF).

Version 0.6.4¶

Note

Firmware built using this release (and other v0.6.x firmware releases) must be controlled using either v0.6.5 of the software or higher.

Created on 23rd January 2022.

TCDS2 interface: Combine BC0 signals from the two channels (as a simple protection against bitflips in TTC path from DTH to Serenity).
TCDS2 interface: Invert RX p & n signals within emp_ttc, to compensate for inversion in tcds2_interface_with_mgt
Serenity VU9P SO2/FO2, VU13P SO2/FO2 and KU15P SO2 daughter cards: Switch from 5G to 10G TCDS interface.
Backend links (Hermes) engine: Connect MGT power enable ports to corresponding control bus registers (i.e. from this release, MGTs are initially powered off on programming the FPGA, and the MGT power for individual quads is enabled as needed, by the software).
CI: Change Serenity KU15P SO2 from minimal to ‘full’ build.

Version 0.6.3¶

Created on 30th November 2021.

Serenity Z1.2 daughter cards: Added 5G TCDS2 interface (alongside general support for 5G TCDS interfaces)
Updated channel buffer to set strobe signed high inbetween playback windwos

Version 0.6.2¶

Created on 5th November 2021.

Added design for Apollo - CM v1, VU7P
Re-wrote several Hermes link FW components, to ensure that correct techniques used for clock-domain crossing, and reduce resource usage (number of CRC blocks per link reduced from two to one)
- This resolves CRC errors observed with some links in some builds (depending on exact placement of compoonents)
Vivado 2021.1: Fixed synthesis error
Testbench: Added logic to increment TTC counter
Added more pipelining to the signals driving the payload reset ports (to resolve timing failure in some designs)
Updated DRP address table to be compatible with new C++ implementation of eyescan software

Version 0.6.1¶

Created on 20th August 2021.

Added location constraint to use SYSMON from master SLR.

Version 0.6.0¶

Note

Firmware built using this release (and other v0.6.x firmware releases) must be controlled using a 0.6.n version of the software.

Created on 9th August 2021.

Updated the aux clock configuration to support frequencies that are not a multiple of 40MHz.
- The aux clock frequencies are set by specifying divisors of the MMCM VCO frequency, via the CLOCK_AUX_DIV constant of the emp_project_decl . I.e. the frequency of each aux clock is CLOCK_COMMON_RATIO * 40MHz / CLOCK_AUX_DIV(n)
- Reminder: The frequency of the aux clocks was previously specified through the CLOCK_AUX_RATIO constant, with the frequency of each aux clock equal to CLOCK_AUX_RATIO(n) * 40MHz
VCU118: Updated assignment of EMP datapath regions to quads in order to match the region-quad mapping of the Serenity VU9P builds
- I.e. EMP region 0 is now constrained to clock region X5Y0 (previously was X5Y1), EMP region 14 is in clock region X5Y14 (previously in X0Y14), EMP region 15 is in clock region X0Y14 (previously in X0Y13), and EMP region 29 is in clock region X0Y0 (previously did not exist as there were only 28 regions).
Serenity VU9P DC designs: Fixed PCIe channel assignment.
CI: Updated to dev/2021i tag of IPBB

Migration guide: 0.5.x to 0.6.0¶

Replace the CLOCK_AUX_RATIO constant in your emp_project_decl package with CLOCK_AUX_DIV changing the type to clock_divisor_array_t, and the values to CLOCK_COMMON_RATIO / CLOCK_AUX_RATIO(n). For example, in a design with the following aux clock configuration (80, 160 and 360MHz):

constant CLOCK_COMMON_RATIO : integer             := 36;
constant CLOCK_RATIO        : integer             := 9;
constant CLOCK_AUX_RATIO    : clock_ratio_array_t := (2, 4, 9);

In migrating from 0.5.x to 0.6.0 these settings would need to be changed to:

constant CLOCK_COMMON_RATIO : integer               := 36;
constant CLOCK_RATIO        : integer               := 9;
constant CLOCK_AUX_DIV      : clock_divisor_array_t := (18, 9, 4);

VCU118 builds: Add one to each region index in the REGION_CONF constants from your emp_project_decl package

Version 0.5.8¶

Created on 7th July 2021.

Build metadata: Fixed 1-hex-char shift in git repo SHA with newer git versions.
Serenity VU7P & VU9P SO1 v1.1 DC: Update reference clock assignments to avoid using clock ping that is not physically connected.

Version 0.5.7¶

Created on 19th May 2021.

Serenity-Z VU9P SO1.1 daughter card: Fixed location constraint for PCIe channel
Added design for Serenity-Z VU7P SO1.1 daughter card
Re-organised board-specific dependency files, and removed dependency of emp_device_decl on TCDS2 repositories, in order to simplify user-created testbench depfiles.
Updated source code to resolve Vivado warnings.

Version 0.5.6¶

Created on 2nd May 2021.

Update dependency files for compatibility with dev/2021f tag of IPBB
- Note: In order to use that tag of IPBB, you will also need to use a new tag - v1.9 - of the IPbus firmware repository (the build instructions have been updated to reference this new tag).

Version 0.5.5¶

Created on 24th April 2021.

Added designs for Serenity VU9P and VU13P daughter cards, specifically:
- VU9P SO1 v1.1 (uses the B2104 package)
- VU9P SO2 (A2577 package; symmetric I/O)
- VU9P FO2 (A2577 package; fan in & fan out)
- VU13P SO2 (A2577 package; symmetric I/O)
- VU13P FO2 (A2577 package; fan in & fan out)
Serenity DC designs: Removed an MMCM from the clock paths for the legacy TTC interface.

Version 0.5.4¶

Created on 8th April 2021.

Serenity KU15P SM1 daughter cards: Relaxed constraint on BUFG in TCDS2 interface (from LOC to clock region), in order to give Vivado more flexibility with clock routing (and thereby resolve placement errors in some designs). Also constrained the TCDS2 interface to relevant quad pblock.

Version 0.5.3¶

Created on 30th March 2021.

Updated synthesis settings to prevent Vivado from flattening hierarchy
- Up to and including version 0.5.2 of IPBB, it automatically applied this setting to prevert hierarchy flattening; we found that hierarchy flattening adversely affects timing closure in builds, and so updated the framework’s TCL scripts so that hierarchy flattening is still prevented the latest releases of IPBB.

Version 0.5.2¶

Created on 17th March

IPBB: Updated to tag dev/2021b
BE MGT (Hermes) links: Updated timing constraints so that CDCs that were erroneously being timed in are not correctly declared as false paths.
VCU118 designs: Move PCIe block in order to ease timing closure. As a result, input/output buffers should no longer be instantiated in datapath regions 4 and 5 (i.e. channels 16 to 23).
Datapath: Added register for TTC commands, to ease timing closure.
CI: Reorganised configuration

Version 0.5.1¶

Created on 25th February 2021

Fixed edge-case bug in script that collects build metadata.
Reformatted source code (to have consistent indentation etc).

Version 0.5.0¶

Created on 21st February 2021.

Note

Firmware built using this release must be controlled using version 0.5.0 of the software.

Backward-incompatible change

We have removed the CRC field from the project declaration, since only one CRC type is supported for the back-end links

When updating to this tag, you will need to remove all instances of u_crc32 from the REGION_CONF setting in your emp_project_decl packages - e.g. change:

constant REGION_CONF : region_conf_array_t := (
  0  => (gth16, u_crc16, buf, no_fmt, buf, u_crc16, gth16),
  1  => (gth16, u_crc16, buf, no_fmt, buf, u_crc16, gth16)
  );

to:

constant REGION_CONF : region_conf_array_t := (
  0  => (gth16, buf, no_fmt, buf, gth16),
  1  => (gth16, buf, no_fmt, buf, gth16)
  );

We renamed top-level address table (now top_emp.xml, was previously top_emp_slim.xml)

Main improvements

Updated back-end link firmware to implement version 2 of the Hermes protocol, with 64b/67b encoding. Notably TX channel & board IDs are now sent automatically sent on the links (in control words).
Added support for MGT margin analysis (i.e. measuring BERs with offsets, e.g. for eyescan and bathtub plots).
Integrated TCDS2 interface into the framework
- The framework also still supports the existing TTC masters (FPGA-internal and legacy-style TTC over LVDS)
- The TCDS2 interface is only instantiated in the designs for two Serenity daughter cards so far: KU15P SO2 and KU15P SM1.
- If you need it to use the TCDS2 interface on other daugther cards, please get in touch.
Added more build metadata to the framework. Specifically, the following quantities are now embedded in the bitfiles (and shown by the empbutler info command):
- Timestamp (start of synthesis)
- git repositories: SHA; branch/tag name; flag indicating whether there are any uncommitted changes
- GitLab CI variables: pipeline & job IDs

Version 0.3.6¶

Created on 25th August 2020.

Note

Firmware built using this release must be controlled using version 0.4.6 of the software.

Updated the datapath logic to specify a ‘quiet’ period at the end of the orbit, such that buffer playback stops several BX before the end of the orbit
Updated the alignment block to only use the first alignment signal rising edge from each orbit

Version 0.3.5¶

Created on 2nd July 2020.

Note

Firmware built using this release must be controlled using version 0.4.4 (or higher) of the software.

Updated BE MGT link firmware to improve timing closure, and fix high-severity ‘no clock’ warnings in the CRC error counter process
Resolved timing warnings for top-level ports
Updated to latest tag of IPbus firmware repository: version 1.8
Board-specific changes:
- Added design for Serenity VU7P daughter card
- Serenity KU15P DCs: Increased width of quad pblocks on left-hand side to match resources in pblocks on right-hand side
- Serenity SM1 v1 daughter card: Added 240MHz example design
- Updated PCIe constraints in several designs, to use consistent strategy on all boards

Version 0.3.4¶

Created on 3rd April 2020.

Updated framework to support two categories of link reference clocks - sync and async - in preparation for lpGBT links.
New board design: Serenity KU15P SO1 daughter card
Serenity daughter cards: Updated ref clocks used for BE MGT links in several datapath regions (part of preparation for lpGBT links)
All board designs: Added diagrams of the mapping of EMP datapath region indices to clock regions and Xilinx quad numbers.

Version 0.3.3¶

Created on 23rd February 2020.

Update to v1.7 tag of IPbus firmware (which fixes a Vivado 2019.2 build error in PCIe-based Ultrascale+ designs)
MGT links: Connect link clocks to frequency measurement block, and fix logic errors in signal assignment for ref clock frequency measurements.
Testbench example: Fix bug in emp_project_decl package

Version 0.3.2¶

Created on 1st December 2019.

Updated link logic to use full depth of rx alignment FIFO (512 rather than 128 words, no impact on resource usage).
Serenity KU115 daughter card: Fixed temperature grade listed in configuration files.
Serenity KU115 daughter card: Remove erroneous instantiation of MGT logic in regions without MGTs.

Version 0.3.1¶

Created on 11th October 2019.

Fixed bugs in link CRC counter reset logic
Fixed bug in link alignment logic (alignment marker signal not driven) and alignment address table.
Added pin constraints and example projects for v2 design of Serenity KU15P daughter card.
- N.B. boards/serenity/dc_ku15p directory was reorganised, so if building for the Serenity KU15P SM1 daughter card, you will need to change include -c boards/serenity/dc_ku15p in your dependency files to:
  - include -c boards/serenity/dc_ku15p dc_ku15p_sm1_v1.dep for the v1 daughter card design
  - include -c boards/serenity/dc_ku15p dc_ku15p_sm1_v2.dep for the v2 daughter card design

Version 0.3.0¶

Created on 26th September 2019.

Added 16Gbps (GTH & GTY) and 25Gbps (GTY) link firmware
Fixed datapath logic errors encountered with payload clock > 320MHz
Now using IPbus-PCIe interface from main ipbus-firmware repo (removed local implementation of that module)

Version 0.2.5¶

Created on 16th April 2019.

Renamed top-level address table (now top_emp_slim.xml)

Version 0.2.4¶

Created on 11th March 2019.

Payload-only simulation: Added ‘playback loop’ mode (input file contents played into algo continually, in a loop)

Version 0.2.3¶

Created on 22nd February 2019.

New board designs: Serenity KU15P and KU115 daughter cards
Reorganised and simplified the area constraints

Version 0.2.2¶

Created on 16th November 2018.

Resolved clash in device IDs for two designs (MPUltra and sim)
Updated Vivado and modelsim versions used for testing: 2018.2 and 10.6c
Payload-only simulation: Pattern reader updated to support ‘others’ column (allows one to specify default data values for I/O channels)

Version 0.2.1¶

Created on 30th October 2018.

Fixed bug in boundaries of payload area constraints on MPUltra
Payload-only simulation: Added several new top-level generics

Version 0.2.0¶

Created on 16th October 2018.

Differences w.r.t. v0.1.2:

Data width for payload I/O channels increased from 32 bits to 64 bits (so that at 240MHz each channel now corresponds to a 16Gbps link)
Implemented example designs for Xilinx VCU118 dev board (VU9P)
Updated testbench implementation, including support for ‘sparsely populated’ files
Name of payload entity changed from mp7_payload to emp_payload
Data types for the payload I/O channels are specified in emp_data_types package, which replaces the mp7_data_types package

Version 0.1.2¶

Created on 18th June 2018.

Differences w.r.t. v0.1.1

Introduced injection/capture testbench support.

Version 0.1.1¶

Created on 29th May 2018.

Renamed packages:
- emp_fwk_decl becomes emp_framework_decl
- emp_design_types becomes emp_device_types
- emp_design_decl becomes emp_device_decl
- emp_proj_decl becomes emp_project_decl
Fixed bug in top-level sim files (were still referencing DAQ-related firmware that was recently removed from main framework).

Version 0.1.0¶

First tag; created on 23rd May 2018.