AI Engine Options - 2025.2 English - UG1702

The following options apply to the AI Engine compilation process.

constraints

Specifies one or more constraint JSON files for location and bounding box, etc.

constraints=constraints.json

enable-partition

The Vitis command line option to create an AI Engine partition. The partition is within the AI Engine array and specifies the starting column, the number of columns and the partition's name.

enable-partition=<START_COLUMN>:<NUM_OF_COLUMN>:<PARTITION_NAME>

Note: For more details regarding the use of this setting, see Compiling AI Engine Graph for Independent Partitions in the AI Engine Tools and Flows User Guide (UG1076) .

heapsize

Heap size (in bytes) that the AI Engine uses.

In an AI Engine, the size of the heap determines the maximum amount of dynamically allocated memory at any given time.

The heap size for each AI Engine is measured in bytes. The default size is 1024 bytes.

The stack, heap, and sync buffer allocate up to the tile data memory. The sync buffer is a memory of size 32 bytes. It stores graph run iteration information. Before changing the heap size to a different value, ensure that the sum of the stack, heap, and sync buffer sizes does not exceed the tile data memory. For example, this size is 32768 bytes in an AI Engine device.

This option is also useful for allocating remaining file-scoped data not explicitly connecting to the user graph.

heapsize=512

pl-freq

Specifies the interface frequency (in MHz) for all PL kernels and PLIOs. The default frequency is a quarter of the AI Engine clock frequency. The maximum frequency is half of the AI Engine clock frequency. You can provide the PL frequency specific to the interface in the graph. You can override this value at v++ --link time.

 pl-freq=500

Note: AMD recommend setting port frequency explicitly to avoid ambiguity. This is specifically important when using Vitis Subsystem design flow.

pl-register-threshold

Specifies the frequency threshold in MHz for registered AI Engine-PL crossings. The default frequency is one-eighth of the AI Engine clock frequency.

 pl-register-threshold=300

Note: For more details regarding the use of this setting, see AI Engine Kernel and Graph Programming Guide (UG1079).

Important: The system ignores values above a quarter of the AI Engine array and uses a quarter instead.

stacksize

Stack size (in bytes) used by each AI Engine tile. The default stack size is set to 1024 bytes. Used as a standard compiler calling convention including stack-allocated local variables and register spilling.

The stack is a region of memory used by programs to store temporary data during execution. In the case of an AI Engine, every tile relies on a specific amount of stack memory to run the kernel mapped to it. The amount of memory allocated as stack space is measured by the number of bytes assigned to each tile. This size of the stack is an essential consideration when designing and optimizing the performance of the AI Engine.

By default, the stack size for each tile is set at 1024 bytes. This value takes into account factors like stack-allocated local variables and register spilling. The factors are due to a register no longer having room for data, so it is "spilled" onto the stack temporarily to free up register space. It is essential to optimize the stack size for each tile to prevent potential issues that could arise. These issues include memory overflows that can lead to errors and other performance problems.

Tip: The system allocates up to 32768 bytes of data memory to the stack, heap, and sync buffer (32 bytes). Before changing the stack size, ensure the sum of the stack, heap, and sync buffer sizes does not exceed 32768 bytes.

stacksize=512