Walkthrough1: creating your own repository from scratch

[edit this page]

This page describes how to create your own payload/algorithm repository with the necessary components to build the firmware for a “null algorithm” which transfers the data from the input to the output buffers. You should also verify that you are not using a pre-existing algorithm repository.

Step 1: Creating a payload repository

You should either (1) create a repo sub-directory for your payload or (2) checkout one from an existing git repository.

Create Repo SubdirectoryCheckout Existing Repo

1. If you don’t already have a git repo, then create a new subdirectory in the src directory (you can use a different name than my-algo-repo):

mkdir src/my-algo-repo

3. Whether you checked out a git repo, or just created a plain directory, you should now ensure that within the new ‘source’ directory, there is a subdirectory in which you can place the new files that you will create in the next few steps. For the rest of the instructions on this page, we assume this directory is named an-algo, but in practice you can give it any other name. This directory itself must have a subdirectory firmware; the firmware directory should have at least two subdirectories: cfg and hdl. Therefore the minimal directory structure needed for the next few steps is:

   src
   └── my-algo-repo
       └── an-algo
           └── firmware
               ├── cfg
               └── hdl
   

   If this directly structure doesn’t already exist, it can be created with the following commands:

   mkdir -p src/my-algo-repo/an-algo/firmware/cfg
   mkdir -p src/my-algo-repo/an-algo/firmware/hdl
   

Step 2: Create the “payload” entity

In order to include your custom “physics algorithm” payload in the standard EMP framework designs, you need to instantiate your payload firmware in an entity named emp_payload, with the input and output ports specified in the Payload firmware: Interface page.

Rather than writing the emp_payload entity from scratch, if you have not integrated custom payloads into the EMP framework before, it is easiest to start from the source code for the ‘null algo’ entity, which can be found in the IPBB work area at src/emp-fwk/components/payload/firmware/hdl/emp_payload.vhd. The implementation of emp_payload in that file just feeds the data from each input channel into the corresponding output channel after delaying it by several clocks cycles.

Copy this file into the hdl directory that you created in the last step:

cp src/emp-fwk/components/payload/firmware/hdl/emp_payload.vhd src/my-algo-repo/an-algo/firmware/hdl/

Step 3: Create a top-level IPBB dependency file

In order to build your firmware, you will need to have a top-level IPBB dependency file, that will directly/indirectly specify all of the files required to create a bitfile; in this step, this file will just reference the emp_payload file that you created in step 3.

Create a file named top.dep in src/my-algo-repo/an-algo/firmware/cfg, with the contents src emp_payload.vhd:

echo 'src emp_payload.vhd' >> src/my-algo-repo/an-algo/firmware/cfg/top.dep

Reference the default payload address table from your new depfile:

echo 'addrtab -c emp-fwk:components/payload emp_payload.xml' >> src/my-algo-repo/an-algo/firmware/cfg/top.dep

Add default constraints to the payload area:

echo 'src -c emp-fwk:components/payload ../ucf/emp_simple_payload.tcl' >> src/my-algo-repo/an-algo/firmware/cfg/top.dep

Step 4: Choose a board

The emp-fwk repo contains top-level designs for several boards, including: the MPUltra; the HiTech Global K800; the Xilinx VCU118; Serenity KU115 and KU15P daughter cards.

Add one of the dependency file commands from the following table to the end of your top-level depfile (src/my-algo-repo/an-algo/firmware/cfg/top.dep) in order to include the EMP framework source code files for the appropriate board.

Board	Dependency file command
HTG K800	include -c emp-fwk:boards/k800
MPUltra	include -c emp-fwk:boards/mpultra
VCU118	include -c emp-fwk:boards/vcu118
Serenity KU115 SO1	include -c emp-fwk:boards/serenity/dc_ku115 dc_ku115_so1.dep
Serenity KU115 TM1/BM1	include -c emp-fwk:boards/serenity/dc_ku115 dc_ku115_am1.dep
Serenity KU15P SM1 v1	include -c emp-fwk:boards/serenity/dc_ku15p dc_ku15p_sm1_v1.dep
Serenity KU15P SM1 v2	include -c emp-fwk:boards/serenity/dc_ku15p dc_ku15p_sm1_v2.dep
Serenity KU15P SO1 v1	include -c emp-fwk:boards/serenity/dc_ku15p dc_ku15p_so1_v1.dep
Serenity KU15P SO2 v0	include -c emp-fwk:boards/serenity/dc_ku15p dc_ku15p_so2_v0.dep
Serenity VU7P SO1 v1.0	include -c emp-fwk:boards/serenity/dc_vu7p dc_vu7p_so1_v1_0.dep
Serenity VU7P SO1 v1.1	include -c emp-fwk:boards/serenity/dc_vu7p dc_vu7p_so1_v1_1.dep
Serenity VU9P SO1 v1.1	include -c emp-fwk:boards/serenity/dc_vu9p dc_vu9p_so1_v1_1.dep
Serenity VU9P FO2	include -c emp-fwk:boards/serenity/dc_vu9p dc_vu9p_fo2.dep
Serenity VU9P SO2	include -c emp-fwk:boards/serenity/dc_vu9p dc_vu9p_so2.dep
Serenity VU13P FO2	include -c emp-fwk:boards/serenity/dc_vu13p dc_vu13p_fo2.dep
Serenity VU13P SO2	include -c emp-fwk:boards/serenity/dc_vu13p dc_vu13p_so2.dep

E.g. for the KU15P SM1 v2 or KU115 SO1 boards on the SERENITY choose one of the following:

KU15P SO1 v1 boardKU15P SM1 v2KU115 SO1VU7P SO1 v1.0

echo 'include -c emp-fwk:boards/serenity/dc_ku15p dc_ku15p_so1_v1.dep' >> src/my-algo-repo/an-algo/firmware/cfg/top.dep

The argument directly after the -c is a path to find the dependency file e.g. dc_ku115_am1.dep. Whereas ku115dc_decl.vhd is found directly within the project space.

Step 5: Create the emp_project_decl package

You need to implement a VHDL package, named emp_project_decl, that defines several configurable settings of the EMP framework, such as clock frequencies for receiving data from the I/O channels, and which firmware components are instantiated in each datapath region (e.g. input buffers, output buffers, input transceiver control logic, output transceiver control logic).

Specifically, the emp_project_decl package must define the following constants:

Name	Type	Meaning
PAYLOAD_REV	std_logic_vector(31 downto 0)	32-bit version number for the algorithm
LHC_BUNCH_COUNT	integer	Number of bunch crossings in an LHC orbit
LB_ADDR_WIDTH	integer	Address width for data words in I/O buffers
CLOCK_RATIO	integer	Ratio of frequency of I/O channel data clock to LHC clock (normally set to 6)
CLOCK_RATIO_AUX	clock_ratio_array_t	Ratio of frequency of clocks in clk_payload port (the auxiliary clocks) to LHC clock
CLOCK_COMMON_RATIO	integer	Ratio of frequency of feedback VCO in MMCM that generates clocks for ports clk_p and clk_payload to the LHC clock
REGION_CONF	region_conf_array_t	Specifies what components (buffers, formatters, transceivers) will be enabled in each datapath region.

As with the emp_payload entity, rather than writing an emp_project_decl package from scratch, if you have not integrated custom payloads into the EMP framework before, it is easiest to start from the emp_project_decl package for one of the example designs; copy the appropriate file from the table below to the src/my-algo-repo/an-algo/firmware/hdl/ directory, renaming the file to emp_project_decl.vhd (or another name if preferred).

Board	Dependency file command
HTG K800	src/emp-fwk/projects/examples/k800/firmware/hdl/emp_project_decl_full.vhd
MPUltra	src/emp-fwk/projects/examples/mpultra/firmware/hdl/emp_project_decl_full.vhd
VCU118	src/emp-fwk/projects/examples/vcu118/firmware/hdl/emp_project_decl_full.vhd
Serenity KU115	src/emp-fwk/projects/examples/serenity/dc_ku115/firmware/hdl/emp_project_decl_full.vhd
Serenity KU15P SM1	src/emp-fwk/projects/examples/serenity/dc_ku15p/firmware/hdl/sm1/emp_project_decl.vhd
Serenity KU15P SO1	src/emp-fwk/projects/examples/serenity/dc_ku15p/firmware/hdl/so1/emp_project_decl.vhd
Serenity VU7P	src/emp-fwk/projects/examples/serenity/dc_vu7p/firmware/hdl/emp_project_decl.vhd

Note that the project declaration is set with clock ratios for specific MGT speeds. This means the SM1 and SO1 designs have link speeds set to 16G for the GTH transcievers and 25G for the GTY transcievers. The VU7P has half the MGTs at 25G and half at 16G. In order to change to alternate link speeds please follow Advanced Customisation: MGT Speed.

E.g. for the Serenity KU15P or KU115 daughter cards, you would run one of the following commands and then reference the relevant “emp_project_decl” VHDL file in your top-level dependency file:

KU15P board SM1KU15P board SO1KU115 boardVU7P board

cp src/emp-fwk/projects/examples/serenity/dc_ku15p/firmware/hdl/sm1/emp_project_decl.vhd src/my-algo-repo/an-algo/firmware/hdl/.
echo 'src emp_project_decl.vhd' >> src/my-algo-repo/an-algo/firmware/cfg/top.dep

N.B. The emp_project_decl file instantiates I/O buffers in all datapath regions, and so in the future, you may want to remove the I/O buffers from certain regions by changing the value of the REGION_CONF constant.

Step 6: Create a Vivado project

Assuming that your top-level .dep file is located in source area my-algo-repo, at path an-algo/firmware/cfg/top.dep, you can create a Vivado project area (under directory proj/my_algo) by running:

ipbb proj create vivado my_algo my-algo-repo:an-algo top.dep
cd proj/my_algo

Step 7: Build the firmware

After building your project from the relevant repository, just four more commands are required to setup the project, then build and package the bitfile (make sure vivado is correctly set in your $PATH):

ipbb ipbus gendecoders
ipbb vivado generate-project
ipbb vivado synth -j4 impl -j4
ipbb vivado package

These four commands naturally have to be run for each specific code instance and project space (e.g. once in proj/my_ku115_algo and once in proj/my_ku15_algo if you have two different daughter cards on the same SERENITY carrier board).

N.B. The synthesis stage may last between ~30-60mins depending upon the machine running vivado and the complexity of the algorithm.

Make sure that you have a valid vivado licence and machine in order for the above commands to execute correctly. During the “synth” (synthesis and implementation) stage a number of checks are carried out, therefore you should make sure that the command is executed successfully before building the bitfile, packaging and transferring to the FGPA. In addition (as described in the Firmware: Build and simulation instructions) the first command requires the installation of the ipbus uHAL (Prerequisites).

The package command creates a tar-ball of the bitfile and the associated address table for interrogating using the empbutler. See Create CONNECTIONS.xml and Address Table for more information.

Next Step: Create your own algorithm - add 5 to the input buffers

The example firmware created above generates a null algorithm - all data at the inputs is directly copied to the outputs.

In order to understand things further we suggest you now create a simple algorithm that does something with the data, e.g. adds 5 to the input buffers, as described in Walkthrough2: First payload modifications and buffer manipulation - “Plus5”.