uGT firmware

Firmware for the CMS Global Trigger (uGT).

This repository contains the algorithm part of the CMS uGT firmware. It has been written for the Imperial MP7, a Virtex-7 based AMC module.

Documentaion of uGT firmware.

The uGT is versioned with the following scheme:

• Major version: Changes in firmware structure, changes that require significant interventions at P5.
• Minor version: New features for trigger decisions.
• Rev version: Bug fixes, change/add scripts.

In addition there are versions (with similar schemes) for the following firmware parts of uGT:

• Framework (frame.vhd)
• Global Trigger Logic (gtl_module.vhd)
• Final Decision Logic (fdl_module.vhd)

Following software tool versions used to create L1Menu and menu depended VHDL files:

utm	TME	VHDL Producer
0.13.0	0.17.1	2.20.2

Following dependencies exist for uGT firmware:

Repo	Tag
MP7	v3.2.2_Vivado2021+_ugt_v4
IPBB	dev/2023a
IPB_FW	v1.4

Setup environment

First make sure to checkout the branch or tag to work with.

git clone https://github.com/cms-l1-globaltrigger/mp7_ugt_legacy.git
cd mp7_ugt_legacy
git checkout <branch/tag>

If not already done create a Python virtual environment and install all required dependencies including IPBB and lxml.

python3 -m venv env
. env/bin/activate
pip install -U pip
pip install -r scripts/requirements.txt

A template file for setting up the required environment variables is available setup_env_sim_synth_tpl.sh. Copy this file to e.g. setup_env_sim_synth.sh, edit the values for the variables and source the script.

. setup_env_sim_synth.sh

Example for setup_env_sim_synth.sh

## Simulation (Questasim)
export MODELSIM_ROOT=/opt/mentor
export MODELSIM_PATH=${MODELSIM_ROOT}/questasim/bin
export PATH=${MODELSIM_PATH}:${PATH}
export MTI_VCO_MODE=64
export [email protected]
export UGT_GITLAB_USER_NAME=hbergaue
export UGT_QUESTASIMLIBS_DIR=/opt/mentor
export UGT_QUESTASIM_SIM_PATH=${MODELSIM_ROOT}
export UGT_VIVADO_QUESTASIMLIBS_VERSION=2021.2
export UGT_QUESTASIM_LIBS_PATH=${UGT_QUESTASIMLIBS_DIR}/questasimlibs_vivado_${UGT_VIVADO_QUESTASIMLIBS_VERSION}
export UGT_BLK_MEM_GEN_VERSION_SIM=blk_mem_gen_v8_4_5

## Synthesis (Vivado)
export VIVADO_BASE_DIR=/opt/xilinx/Vivado
export UGT_VIVADO_BASE_DIR=${VIVADO_BASE_DIR}
export UGT_VIVADO_VERSION=2021.2
export UGT_BLK_MEM_GEN_VERSION_SYNTH=blk_mem_gen_v8_4_5
source ${VIVADO_BASE_DIR}/${UGT_VIVADO_VERSION}/settings64.sh

Simulation

Simulation of VHDL module gtl_fdl_wrapper.vhd with Questa simulator for 6 ugt modules.

• This is a description running script simulation.py in ugt-fwtools with ugt-simulate for simulation.
• If Questasim libraries for a certain Vivado version do not exist, they have to be created for the selected Questasim version with script ugt-fwtools with ugt-compile-simlib:

ugt-compile-simlib \
 --vivado <vivado_version (e.g. 2021.2)> \
 --questasim <path to Questasim (e.g. /opt/mentor/10.7c/questasim)> \
 --output <output directory for generated libraries>

Following table shows which Questasim libraries for a certain Vivado version have been created and tested (version of IP 'blk_mem_gen' in libraries is relevant for Global Trigger logic):

Vivado	blk_mem_gen	10.7c	2021.1_2
2019.2	v8.4.4	ok	X
2020.2	v8.4.4	X	ok
2021.1	v8.4.4	X	ok
2021.2	v8.4.5	X	ok

Workflow

Be sure that setup of environment is done (see chapter above).

Run simulation using Questa.

Remarks:

• MIF files (for mass over deltaR) are located in mp7_ugt_legacy/firmware/sim for simulation.

Running script simulation.py in ugt-fwtools with ugt-simulate.

Note: inspect for default values and other arguments

cd ../ugt-fwtools
python3 -m venv env
. env/bin/activate
ugt-simulate <xml_file> --tv <testvector_file> --ugttag <ugt tag or branch> [--mp7_repo_tag <MP7 repo tag - default is v3.2.2_Vivado2021+_ugt_v4>] [--ignored]

Example

ugt-simulate https://raw.githubusercontent.com/cms-l1-globaltrigger/cms-l1-menu/L1Menu_Collisions2024_v1_2_1-d1/2024/L1Menu_Collisions2024_v1_2_1-d1/xml/L1Menu_Collisions2024_v1_2_1-d1.xml \
 --tv https://raw.githubusercontent.com/cms-l1-globaltrigger/cms-l1-menu/L1Menu_Collisions2024_v1_2_1-d1/2024/L1Menu_Collisions2024_v1_2_1-d1/testvectors/TestVector_L1Menu_Collisions2024_v1_2_1_ttBar.txt \
 --ignored

Build all modules

Remarks:

• FW versions greater or equal 0x1150 are used with 2loose muon shower bit (MUS2).
• FW versions greater or equal 0x1130 are used for uGMT v6.1.0 and unpacker (with bug fix for shifted raw eta).
• FW versions greater or equal 0x1120 and lower 0x1130 are used for uGMT v6.0.0_patch1 and unpacker (with bug: shifted raw eta).

The firmware uses the ipbb build tool, and requires the ipbus system firmware. If you are going to build on a computer outside of the CERN network, then you will need to run kerberos (kinit [email protected]). These instructions assume that you have your Xilinx Vivado licensing already setup for your enviroment.

• The ugt repo mp7 ugt_legacy is a fork of svn2git ugt repo.

  • added ugt_strategy.tcl for ugt specific strategy and inserted it into top.dep.
  • added add_l1menu_blkmem_files.tcl for adding L1Menu VHDL files and inserted it into top.dep.

• Following scripts are available in ugt_fwtools for firmware sythesis, checking used FPGA resources and packing firmware files:

  • script synthesis.py for IPBB synthesis (all 6 mp7_ugt modules).
  • script checksynth.py for checking used FPGA resources.
  • script fwpacker.py for packing firmware files in a tar file.

• The MP7 firmware needs to be adapted for Global Trigger firmware.

• A script makes this changes in the following MP7 files:

  • area_constraints.tcl
  • mp7_brd_decl.vhd
  • mp7xe_690.vhd

• Additionally this script inserts L1A (port l1a) to mp7_payload.vhd.

• This script is part of simulation and synthesis workflows (ugt-simulate, ugt-synthesize).

Workflow

Make sure to setup your local bash environment (see above).

Run kerberos for outside of CERN network.

kinit <username>@CERN.CH

Run synthesis script (for all 6 modules).

Note: inspect default values for arguments using

cd ../ugt-fwtools
python3 -m venv env
. env/bin/activate
ugt-synthesize <xml_file> --ugt <ugt tag or branch> --mp7tag <MP7 repo tag - default is v3.2.2_Vivado2021+_ugt_v4> --build <build_version> -p <working_dir>
```bash

Example

```bash
ugt-synthesize https://raw.githubusercontent.com/cms-l1-globaltrigger/cms-l1-menu/L1Menu_Collisions2024_v1_2_1-d1/2024/L1Menu_Collisions2024_v1_2_1-d1/xml/L1Menu_Collisions2024_v1_2_1-d1.xml \
 --ugt v1.26.0 \
 --build 0x118f \
 -p ~/work_synth/production

After all syntheses have finished, check results:

ugt-checksynth <path of build_xxxx.cfg>

If timing errors occur (and bit files is not generated), check timing errors in file:

<project path>/proj/module_<nr>/module_<nr>/module_<nr>.runs/impl_1/top_timing_summary_postroute_physopted.rpt

Afterwards execute the following command for every module with timing errors to generate bit file:

vivado -mode batch -source <path to scripts/vivado_write_bitstream.tcl> -tclargs <project path> <module id>

After successfully created bit files, execute the following command to create tar file for HW:

ugt-fwpacker <path of build_xxxx.cfg>

Build single module

Run kerberos for outside of CERN network

kinit <username>@CERN.CH

If not already done create a Python virtual environment and install all required dependencies including IPBB and lxml.

python3 -m venv env
. env/bin/activate
pip install -U pip
pip install -r scripts/requirements.txt

Create a local working area

ipbb init <working_area_path>
cd <working_area_path>
ipbb add git https://github.com/ipbus/ipbus-firmware.git -b v1.4
ipbb add git https://:@gitlab.cern.ch:8443/hbergaue/mp7.git -b mp7fw_v3_0_0_mp7_ugt
ipbb add git https://github.com/cms-l1-globaltrigger/mp7_ugt_legacy -b <branch/tag>

Copy VHDL producer output and patched files to mp7_ugt (gtl_module.vhd, gtl_pkg.vhd, algo_mapping_rop.vhd and gt_mp7_top_pkg.vhd)

Source Vivado

Create project

ipbb proj create vivado module_<module_id> mp7:../mp7_ugt_legacy
cd proj/module_<module_id>
ipbb vivado make-project --single

Run implementation, synthesis

ipbb vivado synth
ipbb vivado impl

Generate a bitfile

ipbb vivado package
deactivate

Contact

Bernhard Arnold [[email protected]]
Herbert Bergauer (Developer) [[email protected]]
Manfred Jeitler [[email protected]]