Mapping Kernel Ports to Memory - Mapping Kernel Ports to Memory - 2026.1 English - UG1701

During the link phase, the tool connects the memory ports of the kernels to memory resources such as DDR, LPDDR, and PLRAM.

By default, all kernel memory interfaces connect to the same global memory bank (or gmem). As a result, only one kernel interface can transfer data to or from the memory bank at one time, which limits application performance due to memory access contention.

Explicitly specify which global memory bank each kernel argument (or interface) connects to. Correct kernel-to-memory connectivity maximizes bandwidth, optimizes data transfers, and improves overall performance. Even if the design contains only one compute unit, mapping its input and output arguments to different global memory banks can improve performance by enabling simultaneous access to input and output data.

The following block diagram illustrates how a kernel connects to two separate global memory banks. The input pointer interface connects to DDR bank 0, and the output pointer interface connects to DDR bank 1.

Figure 1. Global Memory Two Banks Example

Start by assigning the kernel arguments to separate bundles to increase the available interface ports, then assign the arguments to separate memory banks. The following example uses the interfaces described in HW Interfaces in the Data Center Acceleration using Vitis (UG1700).

1. In the C/C++ kernel code, assign arguments to separate bundles using the INTERFACE pragma before compiling:

   void cnn( int *pixel, // Input pixel
     int *weights, // Input Weight Matrix
     int *out, // Output pixel
     ... // Other input or Output ports
   		   
   #pragma HLS INTERFACE m_axi port=pixel offset=slave bundle=gmem
   #pragma HLS INTERFACE m_axi port=weights offset=slave bundle=gmem1
   #pragma HLS INTERFACE m_axi port=out offset=slave bundle=gmem
   

   In this example, the cnn kernel has three arguments: pixel, weights, and out. Using the bundle attribute of the INTERFACE pragma, each argument maps to a specific interface. The pixel and out arguments both map to the same interface named gmem. The weights argument maps to a different interface named gmem1. The kernel therefore has two distinct interfaces (gmem and gmem1), which can connect to different memory banks.
   Important: Specify bundle= names using all lowercase characters to assign them to a specific memory bank using the --connectivity.sp option.
2. Use the --connectivity.sp option, or include it in a config file, as described in --connectivity Options .
   For example, for the cnn kernel shown above, the connectivity.sp option in the config file is as follows:

   [connectivity]
   #sp=<compute_unit_name>.<argument>:<bank name> 
   sp=cnn_1.pixel:DDR[0]          
   sp=cnn_1.weights:PLRAM[0]
   sp=cnn_1.out:DDR[0]
   #sp=<aie_instance>.<gmio_port>:<memory_sp_tag_name>[bank_number]
   sp=ai_engine_0.my_gmio:LPDDR[0]
   

   Where:

   • <compute_unit_name> is an instance name of the CU as determined by the connectivity.nk option, described in Creating Multiple Instances of a Kernel, or is simply <kernel_name>_1 if multiple CUs are not specified.
   • <argument> is the name of the kernel argument. You can also specify the kernel interface name as defined by the HLS INTERFACE pragma for C/C++ kernels, including m_axi_ and the bundle name. In the cnn kernel above, the ports are m_axi_gmem and m_axi_gmem1.
     Tip: For RTL kernels, the interface name comes from the kernel.xml file.
   • <bank_name> is denoted as DDR[0], DDR[1], DDR[2], and DDR[3] for a platform with four DDR banks.

     Some platforms also support LPDDR, PLRAM, or HBM memory. Use LPDDR[0], PLRAM[0], or HBM[0] accordingly. Use the platforminfo utility to list the global memory banks available for a specified platform. Refer to platforminfo Utility in the Vitis Reference Guide (UG1702) for more information.

     On platforms that include both DDR and HBM memory banks, kernels must use separate AXI interfaces to access the different memories. DDR and PLRAM access can share a single port.

     Note: The SP tag name is declared in the Vivado block design as part of the platform properties. You can customize SP tag names to identify specific memory controllers.
     Tip: Assigning kernel interfaces to specific memory banks might also require you to specify the SLR placement for the kernel.

Use the Device Hardware Transaction view in Vitis Analyzer to observe DDR bank communication and analyze DDR usage.

Figure 2. Device Hardware Transaction View Transactions on DDR Bank