Payload firmware: Interface

The EMP framework top-level designs instantiate an entity - named emp_payload - and connects its input/output ports to the clocking infrastructure, control bus, and input/output buffers, as described in the introduction page. Various configurable aspects of the infrastructural firmware (such as the I/O clock frequency and the depths of the I/O latency buffers) are controlled by the values of constants defined in the emp_payload_decl package. This page outlines requirements on the port map of the emp_payload entity, and lists the constants that users must define in the emp_project_decl and tb_decl packages.

emp_payload entity

If you are developing a custom “physics algorithm” payload to integrate into the EMP framework designs, this payload should be implemented in an entity named emp_payload, with the following input and output ports:

	Name	Type	Description
in	clk	std_logic	IPbus clock
in	rst	std_logic	IPbus reset
in	ipb_in	ipbus.ipb_wbus	IPbus fabric (in)
out	ipb_out	ipbus.ipb_rbus	IPbus fabric (out)
in	clk_payload	std_logic_vector(2 downto 0)	Auxiliary clocks for algorithms
in	rst_payload	std_logic_vector(2 downto 0)	Resets aligned to auxiliary clocks
in	clk_p	std_logic	Clock for main I/O data
in	rst_loc	std_logic_vector(N_REGION - 1 downto 0)	Region-local reset (clock domain: clk_p)
in	clken_loc	std_logic_vector(N_REGION - 1 downto 0)
in	ctrs	emp_ttc_decl.ttc_stuff_array	TTC counters
out	bc0	std_logic
in	d	ldata(4 * N_REGION - 1 downto 0)	Input data channels
out	q	ldata(4 * N_REGION - 1 downto 0)	Output data channels
out	gpio	std_logic_vector(29 downto 0)
out	gpio_en	std_logic_vector(29 downto 0)

emp_project_decl package

The emp_project_decl package must define the following constants:

Name	Type	Description
LHC_BUNCH_COUNT	integer	Number of LHC bunches (should be 3564)
LB_ADDR_WIDTH	integer	Address width for I/O channel latency buffers (i.e. if 10, they can store 2^10 = 1024 words). Only required for builds, not for simulation.
CLOCK_COMMON_RATIO	integer	Defines MMCM VCO frequency (multiple of 40MHz) in TTC block Must be multiple of CLOCK_RATIO and all elements of CLOCK_AUX_RATIO
CLOCK_RATIO	integer	Determines clock frequency for I/O channels (i.e. clk_p port) Frequency = CLOCK_RATIO * 40MHz
CLOCK_AUX_RATIO	clock_ratio_array_t [From emp_framework_decl]	Determines frequency of ‘auxilary’ clocks (i.e. clk_payload port) Frequency of clk_payload(i) = CLOCK_AUX_RATIO(i) * 40MHz E.g. With constant CLOCK_AUX_RATIO : clock_ratio_array_t := (2, 4, 6);, the frequencies of clk_payload(0), (1) and (2) are 240, 160 and 80MHz respectively
REGION_CONF	region_conf_array_t [From emp_device_types]	Defines whether MGT logic and buffers are instantiated in each I/O region

Examples of the emp_project_decl package for various boards can be found in the emp-fwk repository, under the projects/example directory.

tb_decl package

The tb_decl package is only required when simulating the payload firmware; it must define the following constants:

Name	Type	Description
SOURCE_FILE	string	Default path to the source file (Used if sourcefile generic not specified at runtime)
SINK_FILE	string	Default path to the sink file (Used if sinkfile generic not specified at runtime)
PLAYBACK_LENGTH	natural	Number of frames to be played from source file
CAPTURE_LENGTH	natural	Number of frames to be captured in sink file
WAIT_CYCLES_AT_START	natural	“Quiet” time at the beginning of the simulation before data from source is injected
PLAYBACK_OFFSET	natural	Index of the first frame from the source file that will be injected into the payload
CAPTURE_OFFSET	natural	Number of clock cycles before the output data is captured
PLAYBACK_LOOP	boolean	Toggles playback of data in a continuous loop (rather than only playing the data once)
STRIP_HEADER	boolean	Toggle whether the header frame - i.e. the first valid frame of the packet - is removed before injecting data into the payload
INSERT_HEADER	boolean	Toggle whether a header frame is inserted before the first valid frame

An example of the tb_decl package can be found in the emp-fwk repository, in file projects/examples/testbench/firmware/hdl/tb_decl.vhd.