XMC BUFFER_DEPTH - 2024.2 English

Vitis Model Composer User Guide (UG1483)
Document ID
UG1483
Release Date
2024-11-13
Version
2024.2 English

The Vitis Model Composer BUFFER_DEPTH pragma provides information for properly sizing the buffers that connect the blocks in an implementation. These buffers are implemented as FIFOs in hardware. By default, Model Composer sets the depths of these buffers to 1. However, if your design has re-convergent paths (two paths converging into the same node) and the processing of data from the blocks of one path are not in lockstep with the processing of data from the other path, then a deadlock can occur. To avoid the deadlock the depth of one or more of the buffers on the paths can be increased to store the data. The following example illustrates this concept.

In the following diagram the Sum block consumes both the output signal of the flip block (red path), and the output of the Shift Right block (blue path). The flip block has been created with the xmcImportFunction command, and its source code is shown in the flip function previously described.

Figure 1. Buffer Depth Generated by Your Tool

From the code for the flip block, you can see that the block needs to read 2 full rows before producing the first output. If the BUFFER_DEPTH pragma is not specified for the block, Model Composer sets the buffer sizes to 1 for the signals in the diagram. This results in deadlock, because the flip block reads 257 pixels from the input FIFO before producing the first output. However, by default, the parallel blue path feeding the second input of Sum has only enough storage for 1 pixel.

Tip: Vitis HLS provides some capability to detect deadlocks during C/RTL co-simulation. In case a deadlock is detected, the tool prints out messages showing which FIFOs are involved in the deadlock, to help identify FIFOs that might require a BUFFER_DEPTH of more than 1.
To change the default BUFFER_DEPTH, as shown in the flip function, place the pragma in the header file before the function declaration: 
#pragma XMC BUFFER_DEPTH <depth>

Where <depth> specifies the buffer depth, and can be specified as a value or an expression.

By specifying #pragma XMC BUFFER_DEPTH 4+2*WIDTH in the flip function, Model Composer can determine that there is an imbalance in processing among the re-convergent paths, and address this imbalance by setting the buffer depth for the second input to the Sum block (blue path) to match the buffer depth of the flip block.

Tip: Determining the minimal buffer depth might require a bit of trial and error because it also depends on the timing of the reads and writes into the FIFOs in the RTL code. In the flip function example, 256 (or 2*WIDTH) was not sufficient BUFFER_DEPTH, but 260 (or 4+2*WIDTH) prevented the deadlock.