Continuous Integration (CI) of FPGA Designs for CMS
Topical Workshop on Electronics for Particle Physics (TWEPP) 2019
Robért Glein on behalf of the CMS Collaboration, CU Boulder, September 3rd 2019
Problem: How to manage, build, and test FW designs?• Precondition: The firmware (FW) code is versioned with git
(or a similar versioning system)
• FW development• High degree of flexibility• Modular design often with various (git) submodules• Various tools for simulation (HDL), synthesis (netlist translation),
implementation (place and route), and test of FPGA designs • Time intensive (functional) verification using various methods
• Solution: Continuous integration (CI) of FW
09/03/19 Continuous Firmware Integration 2
Outline
• Problem Description and Motivation
• Continuous Integration (CI) Overview
• Command Line Interface (CLI) FW Build Systems
• Continuous Integration / Continuous Deployment (CI/CD) Tools
• Demonstration
• Conclusion
Continuous Firmware Integration09/03/19 3
Motivation of Continuous Integration for Firmware• Widely used for software• Especially useful with multiple developers working on the
same or interconnected FW• Automated check, build, simulation, and test from scratch
• Uniform build, simulation, and test environment• An error can be traced to the exact commit• Covers specified functionalities via simulation and test• No risk of human error (changed constants, submodule not
updated, specific tool not installed, …)• Manual verification (simulation and HW) of FW is minimized
• Especially if different FPGAs and/or configurations are supported
• Requires a command line interface (CLI) build system Continuous Firmware Integration09/03/19 4
Continuous Integration (CI) Overview
Continuous Firmware Integration
Code:.vhd, .v, .xci, .bd,
…
Commit
Related code:build,
library, …
Simulation:ModelSim,
Vivado
Unit test
Build:synth, impl,
bitgen
Continuous Deployment (CD):
Review, stage, deploy
09/03/19 5
HW test
Continuous Integration (CI) Overview
Continuous Firmware Integration
Code:.vhd, .v, .xci, .bd,
…
Commit
Related code:build,
library, …
Simulation:ModelSim,
Vivado
Unit test
Build:synth, impl,
bitgen
Continuous Deployment (CD):
Review, stage, deploy
09/03/19 6
HW test
• Manual code commit
•
•
Continuous Integration (CI) Overview
Continuous Firmware Integration
Code:.vhd, .v, .xci, .bd,
…
Commit
Related code:build,
library, …
Simulation:ModelSim,
Vivado
Unit test
Build:synth, impl,
bitgen
Continuous Deployment (CD):
Review, stage, deploy
09/03/19 7
HW test
• Manual code commit
• Automated simulation (unit test), build, and HW tests
•
Continuous Integration (CI) Overview
Continuous Firmware Integration
Code:.vhd, .v, .xci, .bd,
…
Commit
Related code:build,
library, …
Simulation:ModelSim,
Vivado
Unit test
Build:synth, impl,
bitgen
Continuous Deployment (CD):
Review, stage, deploy
09/03/19 8
HW test
• Manual code commit
• Automated simulation (unit test), build, and HW tests
• Manual review and automatic deployment
Outline
• Problem Description and Motivation
• Continuous Integration (CI) Overview
• Command Line Interface (CLI) FW Build Systems
• Continuous Integration / Continuous Deployment (CI/CD) Tools
• Demonstration
• Conclusion
Continuous Firmware Integration09/03/19 9
Firmware CLI Build System:Ruckus by SLAC• Well structured Makefile based CLI
• Supports incremental syn/impl feature (dcp), partial reconfiguration, and integration of HLS (all not tested by me)
• Some commands (right level of granularity):• make depend Vivado Project Creation• make sources Vivado Source Setup
• make xsim Vivado Simulation (CU contribution)• make syn Vivado Synthesis Only
• make bit Vivado Build
• make interactive Vivado Interactive (CLI)
• make gui Vivado GUI
• Project website: https://github.com/slaclab/ruckus
• Documentation: https://docs.google.com/presentation/d/1kvzXiByE8WISo40Xd573DdR7dQU4BpDQGwEgNyeJjTI/
Continuous Firmware Integration09/03/19 10
Firmware CLI Build System:Investigated Alternatives • IP Bus Builder (IPBB)
• This Python tool is based on hierarchical dependency files *.dep in cfg folders to include sources
• Includes make-project, simulation, synth, impl, bit file creation, …• https://ipbus.web.cern.ch/ipbus/doc/user/html/firmware/ipbb-
primer.html
• HDL Make • Makefile based CLI but does not support block designs
(recursively)• https://www.ohwr.org/projects/hdl-make
• Vendor tools with CLI support (e.g. TCL)
Continuous Firmware Integration09/03/19 11
Outline
• Problem Description and Motivation
• Continuous Integration (CI) Overview
• Command Line Interface (CLI) FW Build Systems
• Continuous Integration / Continuous Deployment (CI/CD) Tools
• Demonstration
• Conclusion
Continuous Firmware Integration09/03/19 12
GitLab Continuous Integration / Continuous Deployment (CI/CD)
• Documentation: https://docs.gitlab.com/ee/ci/ and https://docs.gitlab.com/ee/ci/yaml/
• Can be used without any source files in the GitLabrepository (e.g. all code located in GitHub)
Continuous Firmware Integration
Source: https://docs.gitlab.com/ee/ci/README.html
09/03/19 13
GitLab CI/CDInvestigated Alternatives
• https://about.gitlab.com/devops-tools/
• CircleCI: https://circleci.com
• Supposed to have the best GitHub integration
• After a glimpse, I did not find runner options (execute a script
on any workstation)
• Jenkins: https://jenkins.io
• Solid CI tool but not that powerful
• Travis, …
09/03/19 Continuous Firmware Integration 14
Gitlab CI/CD Runner (Executing Workstation)
• https://docs.gitlab.com/ee/ci/runners/README.html
• Run the code defined in .gitlab-ci.yml (next slide)
• Isolated (virtual) machine: Pick up jobs through the coordinator (Gitlab server)
• Types:• Shared: Similar requirements between multiple projects (e.g. Python, GCC, …)• Specific: Special requirements (e.g. HW test workstation with connected boards)• Group: Multiple projects under one group (e.g. Xilinx tools like Vivado (HLS))
• GitLab server and runner are connected via token(s)
• gitlab-runner binary runs as gitlab-runner user on the workstation and can be configured (e.g. number of parallel jobs)
• Docker support for the build environment
09/03/19 Continuous Firmware Integration 15
Gitlab CI/CD Configuration File: .gitlab-ci.yml• https://docs.gitlab.com/ee/ci/yaml/
• Highly configurable with a lot of options. Examples:
variables:VIVADO_PATH_SH: ‘/opt/Xilinx/Vivado/${VIVADO_VERSION}/settings64.sh'
stages:project-prepareproject-make
.job_template: &template_basetags:
- xilinx-toolsbefore_script:
- source $VIVADO_PATH_SH
project-prepare: # Actual job<<: *template_project_prepare # Calls *template_base (not shown)variables:
VIVADO_VERSION: "2019.1"
09/03/19 Continuous Firmware Integration 16
Gitlab CI/CD Configuration File: .gitlab-ci.yml• https://docs.gitlab.com/ee/ci/yaml/
• Highly configurable with a lot of options. Examples:
variables:VIVADO_PATH_SH: ‘/opt/Xilinx/Vivado/${VIVADO_VERSION}/settings64.sh'
stages:project-prepareproject-make
.job_template: &template_basetags:
- xilinx-toolsbefore_script:
- source $VIVADO_PATH_SH
project-prepare: # Actual job<<: *template_project_prepare # Calls *template_base (not shown)variables:
VIVADO_VERSION: "2019.1"
09/03/19 Continuous Firmware Integration 17
Gitlab CI/CD Configuration File: .gitlab-ci.yml• https://docs.gitlab.com/ee/ci/yaml/
• Highly configurable with a lot of options. Examples:
variables:VIVADO_PATH_SH: ‘/opt/Xilinx/Vivado/${VIVADO_VERSION}/settings64.sh'
stages:project-prepareproject-make
.job_template: &template_basetags:
- xilinx-toolsbefore_script:
- source $VIVADO_PATH_SH
project-prepare: # Actual job<<: *template_project_prepare # Calls *template_base (not shown)variables:
VIVADO_VERSION: "2019.1"
09/03/19 Continuous Firmware Integration 18
Gitlab CI/CD Configuration File: .gitlab-ci.yml• https://docs.gitlab.com/ee/ci/yaml/
• Highly configurable with a lot of options. Examples:
variables:VIVADO_PATH_SH: ‘/opt/Xilinx/Vivado/${VIVADO_VERSION}/settings64.sh'
stages:project-prepareproject-make
.job_template: &template_basetags:
- xilinx-toolsbefore_script:
- source $VIVADO_PATH_SH
project-prepare: # Actual job<<: *template_project_prepare # Calls *template_base (not shown)variables:
VIVADO_VERSION: "2019.1"
09/03/19 Continuous Firmware Integration 19
Gitlab CI/CD Configuration File: .gitlab-ci.yml• https://docs.gitlab.com/ee/ci/yaml/
• Highly configurable with a lot of options. Examples:
variables:VIVADO_PATH_SH: ‘/opt/Xilinx/Vivado/${VIVADO_VERSION}/settings64.sh'
stages:project-prepareproject-make
.job_template: &template_basetags:
- xilinx-toolsbefore_script:
- source $VIVADO_PATH_SH
project-prepare: # Actual job<<: *template_project_prepare # Calls *template_base (not shown)variables:
VIVADO_VERSION: "2019.1"
09/03/19 Continuous Firmware Integration 20
CI Development I
Continuous Firmware Integration
FRW Code:.vhd, .v,
.xci, .bd, …
Commit:git add –u;git ci –m;git push
Related code:
ruckus, HLS, …
Simulation:make xsim
Unit test using TextIO: Implemented in CI job call
Build:make syn;make bit
Continuous Deployment (CD):
Review, stage, deploy
Use Vivado GUI between the steps: make gui
09/03/19 21
lib Code:.vhd, .v,
.xci, .bd, …
Commit:git add –u;git ci –m;git push
Stimuli: input.txt
Simulate the
testbench Result: output.txt
Reference: golden.txt
Com
pare
chec
ksum
s
HW test:VIO (trigger)
and ILA
CI Development II:https://gitlab.cern.ch/GTT/fpga/-/jobs
• Template based CI stages/jobs
• Required SW is tagged
09/03/19 Continuous Firmware Integration 22
CI Development III:Build Including Parallel Simulations
09/03/19 Continuous Firmware Integration 23
• https://gitlab.cern.ch/GTT/fpga/blob/master/.gitlab-ci.yml(template and instantiation)
• https://gitlab.cern.ch/GTT/fpga/pipelines/1056751 (visualization)
Outline
• Problem Description and Motivation
• Continuous Integration (CI) Overview
• Command Line Interface (CLI) FW Build Systems
• Continuous Integration / Continuous Deployment (CI/CD) Tools
• Demonstration
• Conclusion
Continuous Firmware Integration09/03/19 24
CI Demonstration
• https://gitlab.cern.ch/GTT/fpga/pipelines
• Access the GitLab repository
• Rerun implementation
• Watch the CI doing its job
• Explain different CI features• Pipeline• Jobs: Log and artifacts• Charts
09/03/19 Continuous Firmware Integration 25
CI Conclusion
• Faster and reproducible results
• Easier troubleshooting (an error can be traced to the exact commit)
• Manual verification of FW is minimized• Using GitLab CI/CD
• Git-based, fully featured platform for SW and FW development• FW requires CLI build system• Support for the entire FPGA design process
• Plan, create, verify, package, release, configure, and monitor
• What happens if you do not use CI?• If you forget to test the entire chain, your algorithm embedded in the
infrastructure may cause errors (timing, not tested function, …)• Errors may be hidden and pile up until the system breaks down
Continuous Firmware Integration09/03/19 26
CI Conclusion
• Faster and reproducible results
• Easier troubleshooting (an error can be traced to the exact commit)
• Manual verification of FW is minimized• Using GitLab CI/CD
• Git-based, fully featured platform for SW and FW development• FW requires CLI build system• Support for the entire FPGA design process
• Plan, create, verify, package, release, configure, and monitor
• What happens if you do not use CI?• If you forget to test the entire chain, your algorithm embedded in the
infrastructure may cause errors (timing, not tested function, …)• Errors may be hidden and pile up until the system breaks down• DON’T LET THIS HAPPEN TO YOU! à USE CI/CD!
Continuous Firmware Integration09/03/19 27
Back Up
09/03/19 Continuous Firmware Integration 28
https://about.gitlab.com/devops-tools/(From the Gitlab perspective)
09/03/19 Continuous Firmware Integration 29
TMUX=1
Rx1, Rx2, …, Rx18 à TMUX=1Rx19, Rx20, …, Rx36 à TMUX=7Rx37, Rx38, …, Rx54 à TMUX=13
Track Stand-Alone Object (Global Track Trigger) in CMS: Overview
Continuous Firmware Integration
TSA#1 VU9P FPGA
GTYTF@25 Gbps
3009/03/19
Track Interface Rx
18x64 b
FIFOs+ optional conv.
96 b Converter
Track FIFOs2 Events
FW Modules for TMUX=13
FW Modules for TMUX=7
vld / rdy
vld / rdy
AlgorithmMET (HLS)
@ fclk,MET
Vertex (HLS)@ fclk,Vertex
Jet (Verilog)@ fclk,Jet
18x96 b
18x96 bObject Interface Tx
Converter with FIFOsvld / rdy
vld / rdy
vld / rdy
9x3 TSASer; 9x3 Muon;4xVtx PF;
2xJF&MET GT; 1 DAQ
Tack Sel.
Doxygen: Automated Generation of Code (e.g. HDL) Documentation
09/03/19 Continuous Firmware Integration 31