Walkthrough2: First payload modifications and buffer manipulation - “Plus5”

[edit this page]

This page already assumes that you are familiar with building and uploading firmware to an FPGA, for example as described in the Serenity getting started guide. Setting up the EMP framework tools and creating your own repository can be found here:

We now describe how to create interrorgate/manipulate the buffers starting from a “null algorithm” and then modify the VHDL so that you add 5 to the input buffers and verify the result.

Create your own algorithm - add 5 to the input buffers

The example firmware created previously generates a null algorithm - all data at the inputs is directly copied to the outputs. In order to understand things further we will now create a simple algorithm that adds 5 to the input buffers. This should be straighforward to interrogate and verify following the section Testing payload firmware in a single FPGA.

If you look in the payload src directory you should find the emp_payload:

cd src/my-algo-repo/an-algo/firmware/hdl/
ls -la

The emp_payload.vhd is a special filename where you should create your algorithm to be included in the EMP project. Currently our emp_payload is a null algorithm which copies the input buffers to the outputs. Here we would like to modify the VHDL so that the algorithm adds 5 to the buffers. First you should copy your emp_payload.vhd to a back-up filename:

cp emp_payload.vhd emp_payload_nullalgo.vhd

Then you should edit emp_payload.vhd so that the data are handled correctly and the simple arithmetic addition of 5 is carried out. This can be an exercise or if you want to directly jump to the solution it can be downloaded - solution along with the equivalent null algorithm.

Copying emp_payload_plus5.vhd to emp_payload.vhd will provide the result and then the firmware can be built as per the previous instructions (Step 3: Build firmware or run simulation) and then loaded onto the relevant FPGA.

Log in to the the carrier card and first set-up your environment to access the empbutler (through cactus):

export LD_LIBRARY_PATH=/opt/cactus/lib:$LD_LIBRARY_PATH
export PATH=/opt/cactus/bin/emp:$PATH

Now we will create a specific connections file and address table for your FPGA so that you can talk to it through the emp butler.

Create CONNECTIONS.xml and Address Table

You need to edit the CONNECTIONS.xml file to include a reference to your top_emp.xml file in your address table. For the cmx account on the baseboard the following my_connections.xml file can be used (right-click save otherwise xml will be opened in a new browser tab). In general it is advisable to create your own working space on a carrier card which will typically have a shared user account (e.g. cmx).

NB You need to replace /path/to/ with your actual sub-folder where your addrtab is located (note also that file:// should be retained before the path)

You also need to create an address table and place it under your sub-directory.

IPBB is able to create the address table for the relevant firmware for you (here called my_algo):

ipbb vivado addrtab -d my_algo_addrtab

Finally you should copy the address table to the correct location on the main carrier card:

scp -rp my_algo_addrtab cmx@baseboard-ip.domain.com:/path/to/.

where baseboard-ip.domain.com is the ip-address of your carrier card and /path/to is the location which you chose and also is present in your my_connections.xml file along with the FPGA_ID.

In the following we assume your FPGA is named FPGA_ID (e.g. x1 or x1_a005) as in the connections file. Unique IDs are useful/necessary in the case of multiple FPGA sites or multiple address tables.

Now you can check that you can talk to the FPGA:

empbutler -c my_connections.xml do FPGA_ID info

Now try and do something other than get the FPGA info:

empbutler -c my_connections.xml do FPGA_ID reset internal

Now we inject empty data to the buffers using empbutler and capture the output:

empbutler -c my_connections.xml do FPGA_ID buffers rx PlayOnce --inject generate://empty
empbutler -c my_connections.xml do FPGA_ID buffers tx Capture
empbutler -c my_connections.xml do FPGA_ID capture

Now you can check if you have indeed been successful in your algorithm implementation, firmware build, buffer injection and capture:

geany data/rx_summary.txt

Note that tx corresponds to the outputs (post algo) and rx to the buffer inputs.

empbutler allows you to inject data onto the buffers in a variety manners. The simplest is “empty " but a pattern file or “random " can also be implemented. The use of “random " would enable the algorithm latency to be tested against the implemention in the firmware and with the +5 this should be semi-obvious.

Custom Channel List for TX/RX Probing:

In the above we captured the buffers for all inputs on the FPGA. It is also possible to be specific to a given list of channels:

empbutler -c CONNECTIONS_FILE.xml do BOARD_ID capture --rx RX_CHANNEL_LIST --tx TX_CHANNEL_LIST

More detailed information about payload testing and link manipulation can be found in the following sections: