cl_uram_example

URAM CL Example

Table of Contents

1. Overview
2. Functional Description
3. Implementation Options
4. Running This Design

Overview

This simple URAM example builds a Custom Logic (CL) that will enable the instance to "peek" and "poke" registers in the Custom Logic (CL). These registers will be in the memory space behind AppPF BAR0, which is the ocl_cl_ AXI-lite bus on the Shell to CL interface.

This example demonstrates a basic use-case of the URAMs and the different implementations available.

All of the unused interfaces between the AWS Shell and the CL are tied to fixed values. It is recommended that the developer use similar values for every unused interface in the developer's CL.

Please read here for general instructions to build the CL, register an AFI, and start using it on an F1 instance.

Functional Description

The cl_uram_example demonstrates basic Shell-to-CL connectivity, memory-mapped register instantiations and URAM implementation options. The cl_uram_example implements a single register in the FPGA AppPF BAR0 memory space connected to the OCL AXI-L interface. The register is:

1. URAM Register (offset 0x500)

Please refer to the FPGA PCIe memory space overview

The URAM Register is a 32-bit read/write register. (3 bits of control and 29 bits of data)

Table 1: ctrl_uram.vhd ports

Signal Name	Interface	Signal Type	Description
clk	Clock	I	Clock.
rstn	Reset	I	Active-Low reset.
data_in	Data	I	Data and control. [31] Find: Active high - Allow to find data in the URAM. [30] Add: Active high - Allow to add data in the URAM. [29] Del: Active high - Allow to delete data in the URAM. [28:0] Data.
find_ok	Status	O	Indicates the status of the find. '1' = The 28 bits data is present in the URAM.
find_ko	Status	O	Indicates the status of the find. '1' = The 28 bits data is not present in the URAM.
busy	Status	O	Indicates the status of the controller.

Unused interfaces

The cl_uram_example does not use most of AWS Shell interface, hence the unused signals are tied off. At the beginning of cl_uram_example.sv file, there is a specific include command for an interface-specific .inc file, to handle the tie-off's for every unused interface.

Implementation Options

Availability of 100% of URAM sites on F1 FPGAs across the entire CL region has now been enabled rather than the previous support for 50%. To utilize up to 100% of URAM, cascading as well as output register inference must be disabled. This option is included in the 1.3.0 HDK build scripts alongside the existing solutions which limits URAM usage to 50% or 75% but does allow a cascade height of 2 or 3 and output register inference. The table below outlines the options available:

URAM Options	Max Cascade Height	URAMs Limitations
2	Max Cascade = 2	Top 2 URAMs Prohibited (50% of URAMs ~ 400 URAMs available)
3	Max Cascade = 3	Top 1 URAM Prohibited (75% of URAMs ~ 600 URAMs available)
4	No Cascade	All URAMs Enabled (100% of URAMs ~ 800 URAMs available)

Please note that the options start from 2 to 4 included

Running This Design

Hardware - HDK Flow

You can run this design like the other examples designs by:

• source hdk\_setup.sh
• cd hdk/cl/examples/cl_uram_example
• export CL_DIR=$(pwd)
• cd $CL\_DIR/build/scripts
• Running the .tar file generation using:
  • Option 2:
    • ./aws_build_dcp_from_cl.sh -uram_option 2
  • Option 3:
    • ./aws_build_dcp_from_cl.sh -uram_option 3
  • Option 4 (default option):
    • ./aws_build_dcp_from_cl.sh -uram_option 4

Software

You can generate the software by:

source sdk_setup.sh
cd hdk/cl/examples/cl_uram_example/software/runtime
make

How to use it?

This software allows you to read from and write into the URAMs. Do not forget to run it in sudo mode:

• sudo ./uram_example

You have 3 commands available:

• find: Command which allows you to find a 29 bits hexadecimal data inside the URAM
• add : Command which allows you to add a 29 bits hexadecimal data inside the URAM
• del : Command which allows to find and delete a 29 bits hexadecimal data inside the URAM

(e.g. add DEADBEEF) (Please note that you do not need the "0x" in front of the 32 bits hexadecimal value)

HW/SW co-simulation

This example also has HW/SW co-simulation support. You can run co-simulation test as below.

How to use it?

To run co-simulation with Vivado simulator

source hdk_setup.sh
cd hdk/cl/examples/cl_uram_example/verif/scripts
make C_TEST=test_uram_example

To run co-simulation with VCS simulator

source hdk_setup.sh
cd hdk/cl/examples/cl_uram_example/verif/scripts
make C_TEST=test_uram_example VCS=1

To run co-simulation with IES simulator

source hdk_setup.sh
cd hdk/cl/examples/cl_uram_example/verif/scripts
make C_TEST=test_uram_example IES=1

To run co-simulation with QUESTA simulator

source hdk_setup.sh
cd hdk/cl/examples/cl_uram_example/verif/scripts
make C_TEST=test_uram_example QUESTA=1