AMD Vitis Templates

https://github.com/xilinx/vitis_templates
Admin
AMD Vitis Templates provide a collection of examples showcasing Vitis™ tools capabilities for AI...
Tokens:6,842
Snippets:32
Trust Score:9.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Vitis Kernel AXI Master Interface Configuration

Source: https://github.com/xilinx/vitis_templates/blob/2024.2/vadd/README.rst

Configures AXI master interfaces for kernel arguments to access global memory. 'm_axi' specifies the interface type, 'port' indicates the argument name, and 'bundle' assigns it to a memory interface group.

```cpp
#pragma HLS INTERFACE m_axi port = in1 bundle = gmem0
#pragma HLS INTERFACE m_axi port = in2 bundle = gmem1
#pragma HLS INTERFACE m_axi port = out bundle = gmem0
```

--------------------------------

### Execute PL Kernels (mm2s, s2mm) for Data Movement with XRT

Source: https://context7.com/xilinx/vitis_templates/llms.txt

This C++ snippet demonstrates how to open, configure, start, and wait for the completion of PL kernels (mm2s and s2mm) using XRT APIs. It includes setting kernel arguments and synchronizing execution for data movement between DDR and AIE. Dependencies include the XRT library.

```cpp
#include <xrt/xrt_device.h>
#include <xrt/xrt_kernel.h>
#include <xrt/xrt_run.h>
#include <iostream>
#include <string>
#include <vector>

// Assuming dhdl, uuid, in_bohdl, sizeIn, out_bohdl, sizeOut are defined elsewhere
// Example placeholders:
xrtDeviceHandle dhdl = nullptr; // Needs to be opened
const char* uuid = "your_uuid_here";
void* in_bohdl = nullptr; // Buffer handle for input
const size_t* sizeIn = 0; // Size of input data
void* out_bohdl = nullptr; // Buffer handle for output
const size_t* sizeOut = 0; // Size of output data

// Open and configure mm2s (memory to stream) kernel
xrtKernelHandle mm2s_khdl = xrtPLKernelOpen(dhdl, uuid, "mm2s");
xrtRunHandle mm2s_rhdl = xrtRunOpen(mm2s_khdl);
int rval = xrtRunSetArg(mm2s_rhdl, 0, in_bohdl);  // Buffer object
rval = xrtRunSetArg(mm2s_rhdl, 2, sizeIn);        // Size
xrtRunStart(mm2s_rhdl);
printf("run mm2s\n");

// Open and configure s2mm (stream to memory) kernel
xrtKernelHandle s2mm_khdl = xrtPLKernelOpen(dhdl, uuid, "s2mm");
xrtRunHandle s2mm_rhdl = xrtRunOpen(s2mm_khdl);
rval = xrtRunSetArg(s2mm_rhdl, 0, out_bohdl);
rval = xrtRunSetArg(s2mm_rhdl, 2, sizeOut);
xrtRunStart(s2mm_rhdl);
printf("run s2mm\n");

// Wait for kernel completion
auto state = xrtRunWait(mm2s_rhdl);
std::cout << "mm2s completed with status(" << state << ")\n";

state = xrtRunWait(s2mm_rhdl);
std::cout << "s2mm completed with status(" << state << ")\n";

// Cleanup
xrtRunClose(s2mm_rhdl);
xrtKernelClose(s2mm_khdl);
xrtRunClose(mm2s_rhdl);
xrtKernelClose(mm2s_khdl);

```

--------------------------------

### Vitis Kernel Dataflow Task Scheduling

Source: https://github.com/xilinx/vitis_templates/blob/2024.2/vadd/README.rst

Implements vector addition using HLS Dataflow, dividing the operation into four concurrent sub-tasks: loading inputs, performing addition, and storing results. This enables higher throughput by overlapping task execution.

```cpp
#pragma HLS dataflow
    load_input(in1, in1_stream, size);
    load_input(in2, in2_stream, size);
    compute_add(in1_stream, in2_stream, out_stream, size);
    store_result(out, out_stream, size);
```

--------------------------------

### OpenCL Host App for PL Kernel Execution (C++)

Source: https://context7.com/xilinx/vitis_templates/llms.txt

Executes Programmable Logic (PL) kernels using OpenCL APIs. It handles device discovery, buffer management, kernel execution, and result verification. Requires the OpenCL SDK and a compiled .xclbin file.

```cpp
#include <CL/cl.h>
#include <vector>
#include <iostream>

#define DATA_SIZE 4096

int main(int argc, char* argv[]) {
    std::string xclbinFilename = argv[1];
    size_t size_in_bytes = DATA_SIZE * sizeof(int);

    std::vector<cl::Device> devices;
    cl_int err;
    cl::Context context;
    cl::CommandQueue q;
    cl::Kernel krnl_vector_add;

    // Find Xilinx platform and device
    std::vector<cl::Platform> platforms;
    cl::Platform::get(&platforms);
    bool found_device = false;

    for (size_t i = 0; i < platforms.size(); i++) {
        cl::Platform platform = platforms[i];
        std::string platformName = platform.getInfo<CL_PLATFORM_NAME>();
        if (platformName == "Xilinx") {
            devices.clear();
            platform.getDevices(CL_DEVICE_TYPE_ACCELERATOR, &devices);
            if (devices.size()) {
                found_device = true;
                break;
            }
        }
    }

    // Load and program xclbin
    std::ifstream bin_file(xclbinFilename, std::ifstream::binary);
    bin_file.seekg(0, bin_file.end);
    unsigned nb = bin_file.tellg();
    bin_file.seekg(0, bin_file.beg);
    char* buf = new char[nb];
    bin_file.read(buf, nb);

    cl::Program::Binaries bins;
    bins.push_back({buf, nb});

    auto device = devices[0];
    context = cl::Context(device, nullptr, nullptr, nullptr, &err);
    q = cl::CommandQueue(context, device, CL_QUEUE_PROFILING_ENABLE, &err);
    cl::Program program(context, {device}, bins, nullptr, &err);
    krnl_vector_add = cl::Kernel(program, "krnl_vadd", &err);

    // Allocate device buffers
    cl::Buffer buffer_a(context, CL_MEM_READ_ONLY, size_in_bytes, NULL, &err);
    cl::Buffer buffer_b(context, CL_MEM_READ_ONLY, size_in_bytes, NULL, &err);
    cl::Buffer buffer_result(context, CL_MEM_WRITE_ONLY, size_in_bytes, NULL, &err);

    // Set kernel arguments
    krnl_vector_add.setArg(0, buffer_a);
    krnl_vector_add.setArg(1, buffer_b);
    krnl_vector_add.setArg(2, buffer_result);
    krnl_vector_add.setArg(3, DATA_SIZE);

    // Map buffers and initialize data
    int* ptr_a = (int*)q.enqueueMapBuffer(buffer_a, CL_TRUE, CL_MAP_WRITE, 
                                          0, size_in_bytes, NULL, NULL, &err);
    int* ptr_b = (int*)q.enqueueMapBuffer(buffer_b, CL_TRUE, CL_MAP_WRITE, 
                                          0, size_in_bytes, NULL, NULL, &err);
    int* ptr_result = (int*)q.enqueueMapBuffer(buffer_result, CL_TRUE, CL_MAP_READ, 
                                               0, size_in_bytes, NULL, NULL, &err);

    for (int i = 0; i < DATA_SIZE; i++) {
        ptr_a[i] = rand() % DATA_SIZE;
        ptr_b[i] = rand() % DATA_SIZE;
    }

    // Execute kernel
    q.enqueueMigrateMemObjects({buffer_a, buffer_b}, 0);
    q.enqueueTask(krnl_vector_add);
    q.enqueueMigrateMemObjects({buffer_result}, CL_MIGRATE_MEM_OBJECT_HOST);
    q.finish();

    // Verify results
    int match = 0;
    for (int i = 0; i < DATA_SIZE; i++) {
        int host_result = ptr_a[i] + ptr_b[i];
        if (ptr_result[i] != host_result) {
            printf("ERROR: Test failed! i=%d golden=%d hardware=%d\n", 
                   i, host_result, ptr_result[i]);
            match = 1;
            break;
        }
    }

    // Cleanup
    q.enqueueUnmapMemObject(buffer_a, ptr_a);
    q.enqueueUnmapMemObject(buffer_b, ptr_b);
    q.enqueueUnmapMemObject(buffer_result, ptr_result);
    q.finish();

    std::cout << "TEST " << (match ? "FAILED" : "PASSED") << std::endl;
    return (match ? EXIT_FAILURE : EXIT_SUCCESS);
}

```

--------------------------------

### XRT Device and Buffer Management for FPGA Execution (C++)

Source: https://context7.com/xilinx/vitis_templates/llms.txt

Manages FPGA devices and memory buffers using XRT APIs for hardware execution. This code opens a device, loads an xclbin, allocates input and output buffers, maps them to host memory, and performs data transfers. It includes cleanup steps. Dependencies: experimental/xrt_kernel.h, adf/adf_api/XRTConfig.h.

```cpp
#include "experimental/xrt_kernel.h"
#include "adf/adf_api/XRTConfig.h"

// Open device and load xclbin
xuid_t uuid;
auto dhdl = xrtDeviceOpen(0);
auto xclbin = load_xclbin(dhdl, xclbinFilename);
xrtDeviceGetXclbinUUID(dhdl, uuid);

// Calculate buffer sizes
int sizeIn = INPUT_SIZE * itr;
int sizeOut = OUTPUT_SIZE * itr;
size_t input_size_in_bytes = sizeIn * sizeof(int);
size_t output_size_in_bytes = sizeOut * sizeof(int);

// Allocate input buffer and map to host memory
xrtBufferHandle in_bohdl = xrtBOAlloc(dhdl, input_size_in_bytes, 0, 0);
auto in_bomapped = reinterpret_cast<short int*>(xrtBOMap(in_bohdl));
memcpy(in_bomapped, cint16input, input_size_in_bytes);
printf("Input memory virtual addr 0x%llx\n", in_bomapped);

// Allocate output buffer
xrtBufferHandle out_bohdl = xrtBOAlloc(dhdl, output_size_in_bytes, 0, 0);
auto out_bomapped = reinterpret_cast<int*>(xrtBOMap(out_bohdl));
printf("Output memory virtual addr 0x%llx\n", out_bomapped);

// Cleanup when done
xrtBOFree(in_bohdl);
xrtBOFree(out_bohdl);
xrtDeviceClose(dhdl);

```

--------------------------------

### C++ HLS Dataflow Kernel for Load-Compute-Store Pattern

Source: https://context7.com/xilinx/vitis_templates/llms.txt

This C++ code implements an HLS kernel demonstrating the load-compute-store pattern using `hls::stream` for parallel data processing. It includes functions for loading input data, performing computation (addition in this case), and storing the results. The `#pragma HLS dataflow` directive enables concurrent execution of these functions. Dependencies include `<stdint.h>` and `<hls_stream.h>`.

```cpp
#include <stdint.h>
#include <hls_stream.h>

#define DATA_SIZE 4096

static void load_input(uint32_t* in, hls::stream<uint32_t>& inStream, int size) {
mem_rd:
    for (int i = 0; i < size; i++) {
#pragma HLS LOOP_TRIPCOUNT min = DATA_SIZE max = DATA_SIZE
        inStream << in[i];
    }
}

static void compute_add(hls::stream<uint32_t>& in1_stream,
                        hls::stream<uint32_t>& in2_stream,
                        hls::stream<uint32_t>& out_stream,
                        int size) {
execute:
    for (int i = 0; i < size; i++) {
#pragma HLS LOOP_TRIPCOUNT min = DATA_SIZE max = DATA_SIZE
        out_stream << (in1_stream.read() + in2_stream.read());
    }
}

static void store_result(uint32_t* out, hls::stream<uint32_t>& out_stream, int size) {
mem_wr:
    for (int i = 0; i < size; i++) {
#pragma HLS LOOP_TRIPCOUNT min = DATA_SIZE max = DATA_SIZE
        out[i] = out_stream.read();
    }
}

extern "C" {
void krnl_vadd(uint32_t* in1, uint32_t* in2, uint32_t* out, int size) {
#pragma HLS INTERFACE m_axi port = in1 bundle = gmem0
#pragma HLS INTERFACE m_axi port = in2 bundle = gmem1
#pragma HLS INTERFACE m_axi port = out bundle = gmem0

    static hls::stream<uint32_t> in1_stream("input_stream_1");
    static hls::stream<uint32_t> in2_stream("input_stream_2");
    static hls::stream<uint32_t> out_stream("output_stream");

#pragma HLS dataflow
    // Dataflow pragma enables parallel execution
    load_input(in1, in1_stream, size);
    load_input(in2, in2_stream, size);
    compute_add(in1_stream, in2_stream, out_stream, size);
    store_result(out, out_stream, size);
}
}

```

--------------------------------

### System Connectivity Configuration (Tcl/INI)

Source: https://context7.com/xilinx/vitis_templates/llms.txt

Defines stream connections between Processing System (PS), Programmable Logic (PL), and AI Engine components using system configuration files. This is crucial for complete system integration.

```shell
[connectivity]
stream_connect=mm2s_1.s:ai_engine_0.DataIn1
stream_connect=ai_engine_0.Data_clip_in0:polar_clip_1.input
stream_connect=polar_clip_1.output:ai_engine_0.Data_clip_out0
stream_connect=ai_engine_0.DataOut1:s2mm_1.s

```

--------------------------------

### Buffer Placement Constraints and Memory Mapping in Vitis

Source: https://context7.com/xilinx/vitis_templates/llms.txt

This C++ snippet defines an AIE graph that specifies exact memory locations for input buffers and kernels using AXI memory addresses. It demonstrates how to use `adf::location<adf::buffer>` and `adf::address` to control data placement for optimized locality and performance. Dependencies include the ADF library.

```cpp
#include <adf.h>
#include "kernels.h"

using namespace adf;

class mygraph : public adf::graph {
  private:
    adf::kernel superkernel;
  public:
    input_plio  datain[2];
    output_plio dataout;

    mygraph() {
      // Create PLIO ports
      datain[0] = input_plio::create(plio_32_bits, "data/data0.txt");
      datain[1] = input_plio::create(plio_32_bits, "data/weights0.txt");
      dataout   = output_plio::create(plio_32_bits, "data/result0.txt");

      // Create kernel and place on specific tile
      superkernel = adf::kernel::create(super_kernel);
      adf::source(superkernel) = "src/kernels/super_kernel.cc";
      adf::runtime<ratio>(superkernel) = 0.9;
      adf::location<adf::kernel>(superkernel) = adf::tile(0,0);

      // Connect input with memory address constraints
      adf::connect(datain[0].out[0], superkernel.in[0]);
      adf::location<adf::buffer>(superkernel.in[0]) = {
        adf::address(0, 0, 0x4000), adf::address(0, 0, 0x6000)
      };
      adf::dimensions(superkernel.in[0]) = { 8 };

      // Connect weights with specific memory locations
      adf::connect(datain[1].out[0], superkernel.in[1]);
      adf::location<adf::buffer>(superkernel.in[1]) = {
        adf::address(0, 0, 0x5000), adf::address(0, 0, 0x7000)
      };
      adf::dimensions(superkernel.in[1]) = { 8 };

      // Connect output with memory constraints
      adf::connect(superkernel.out[0], dataout.in[0]);
      adf::location<adf::buffer>(superkernel.out[0]) = {
        adf::address(0, 0, 0x0), adf::address(0, 0, 0x2000)
      };
      adf::dimensions(superkernel.out[0]) = { 16 };
    }
};

```

--------------------------------

### Control AIE Graph Execution with XRT

Source: https://context7.com/xilinx/vitis_templates/llms.txt

This C++ snippet shows how to control the execution of an AIE graph using XRT's graph APIs. It covers opening the graph, running it for a specified number of iterations, waiting for completion, and closing the graph. It also includes a basic verification loop. Dependencies include the XRT library and the ADF library.

```cpp
#include <xrt/xrt_device.h>
#include <xrt/xrt_graph.h>
#include <iostream>
#include <vector>

// Assuming dhdl, uuid, sizeOut, golden, out_bomapped are defined elsewhere
// Example placeholders:
xrtDeviceHandle dhdl = nullptr; // Needs to be opened
const char* uuid = "your_uuid_here";
size_t sizeOut = 0;
std::vector<int> golden;
int* out_bomapped = nullptr; // Mapped buffer for output

long itr = 10; // NO_OF_ITERATIONS

// Open AIE graph
printf("xrtGraphOpen\n");
xrtGraphHandle ghdl = xrtGraphOpen(dhdl, uuid, "clipgraph");

// Run graph for specified iterations
printf("xrtGraphRun\n");
xrtGraphRun(ghdl, itr);

// Wait for graph completion and close
xrtGraphEnd(ghdl, 0);
printf("xrtGraphEnd..\n");
xrtGraphClose(ghdl);

// Verify results
int errCnt = 0;
for (int i = 0; i < sizeOut; i++) {
    if (out_bomapped[i] != golden[i]) {
        printf("ERROR: Test failed! Error found in sample %d: golden: %d, hardware: %d\n",
               i, golden[i], out_bomapped[i]);
        errCnt++;
    }
}

std::cout << "TEST " << (errCnt ? "FAILED" : "PASSED") << std::endl;

```

--------------------------------

### Runtime Parameter Updates with Asynchronous RTP in Vitis

Source: https://context7.com/xilinx/vitis_templates/llms.txt

This C++ snippet defines an AIE graph that utilizes asynchronous runtime parameters (RTP) for dynamic updates. It demonstrates connecting input/output PLIOs and controlling kernel parameters via `rtpInput` and `rtpOutput` ports, enabling runtime modifications without recompilation. Dependencies include the ADF library.

```cpp
#include <adf.h>
#include "kernels.h"

using namespace adf;

class rtpGraph : public adf::graph {
private:
    kernel k1;

public:
    input_plio streamInput;
    input_port rtpInput;
    output_plio streamOutput;
    inout_port rtpOutput;

    rtpGraph()
    {
        streamInput = input_plio::create(plio_32_bits,"data/input.txt");
        streamOutput = output_plio::create(plio_32_bits,"data/output.txt");

        k1 = kernel::create(multiply);
        source(k1) = "src/multiply.cpp";
        runtime<ratio>(k1) = 0.1;

        // Stream connection for data
        connect<stream>(streamInput.out[0], k1.in[0]);
        connect<stream>(k1.out[0], streamOutput.in[0]);

        // Parameter connections (async keyword for runtime updates)
        connect<parameter>(rtpInput, async(k1.in[1]));
        connect<parameter>(k1.inout[0], rtpOutput);
    }
};

// Usage in main:
// rtpGraph mygraph;
// mygraph.init();
// mygraph.update(mygraph.rtpInput, newValue);
// mygraph.run(iterations);
// mygraph.read(mygraph.rtpOutput, &readValue);
// mygraph.end();

```

--------------------------------

### AIE Kernel Implementation with Input/Output Buffers (C++)

Source: https://context7.com/xilinx/vitis_templates/llms.txt

Implements an AIE kernel function using adf::input_buffer and adf::output_buffer for window-based data access. It processes complex integer data, performing a specific computation on each element. Dependencies include adf.h and include.h.

```cpp
#include <adf.h>
#include "include.h"

void simple(adf::input_buffer<cint16> & in, adf::output_buffer<cint16> & out) {
  cint16 c1, c2;
  cint16* inItr = in.data();
  cint16* outItr = out.data();

  // Process NUM_SAMPLES complex values
  for (unsigned i=0; i<NUM_SAMPLES; i++) {
    c1 = *inItr++;
    // Perform computation: real = real+imag, imag = real-imag
    c2.real = c1.real + c1.imag;
    c2.imag = c1.real - c1.imag;
    *outItr++ = c2;
  }
}

```

--------------------------------

### C++ Template for Relocatable Graph Design in Vitis

Source: https://context7.com/xilinx/vitis_templates/llms.txt

This C++ template defines a reusable graph structure in Vitis, allowing parameterized placement of kernels and buffers within an AIE array. It utilizes adf::graph and adf::kernel to define the graph and its components, with dynamic PLIO port creation and relative placement strategies. Dependencies include the 'adf.h' header and 'kernels.h'.

```cpp
#include <adf.h>
#include "kernels.h"

#define NUMCORES 2

template <int COLS, int ROWS, int STARTCOL, int STARTROW>
class indep_nodes_graph : public adf.graph {
 private:
  adf::kernel kr[NUMCORES];

 public:
   adf::input_plio datain[NUMCORES];
   adf::output_plio dataout[NUMCORES];

 indep_nodes_graph() {
  // Create PLIO ports with dynamic filenames
  for (int i=0; i<NUMCORES; i++) {
    datain[i]  = adf::input_plio::create(adf::plio_32_bits,
                   "data/input_core" + std::to_string(i) + ".txt");
    dataout[i] = adf::output_plio::create(adf::plio_32_bits,
                   "data/output_core" + std::to_string(i) + ".txt");
  }

  // Create kernels with relative placement
  for (int i = 0; i < COLS; i++) {
    for (int j = 0; j < ROWS; j++) {
      int k = i*ROWS + j;
      kr[k] = adf::kernel::create(kernel_1);
      adf::source(kr[k]) = "kernels/kernel.cc";
      adf::runtime<ratio>(kr[k]) = 0.9;

      // Place kernel at offset from start position
      adf::location<adf::kernel>(kr[k]) = adf::tile(STARTCOL+i, STARTROW+j);

      // Place buffers with specific addresses
      adf::location<adf::buffer>(kr[k].in[0]) = {
        adf::address(STARTCOL+i, STARTROW+j, 0x0),
        adf::address(STARTCOL+i, STARTROW+j, 0x2000)
      };

      // Relative buffer location to kernel
      adf::location<adf::kernel>(kr[k]) = adf::location<adf::buffer>(kr[k].out[0]);

      // Place stack in specific memory bank
      adf::location<adf::stack>(kr[k]) = adf::bank(STARTCOL+i, STARTROW+j, 2);
    }
  }

  // Connect PLIO to kernels
  for (int i=0; i<NUMCORES; i++) {
    adf::connect(datain[i].out[0], kr[i].in[0]);
    adf::connect(kr[i].out[0], dataout[i].in[0]);
    adf::dimensions(kr[i].in[0]) = { 16 };
    adf::dimensions(kr[i].out[0]) = { 16 };
  }
 }
};

// Instantiate graph at specific location:
// indep_nodes_graph<1, 2, 25, 0> graph_instance;

```

--------------------------------

### AIE Graph Definition using Window Communication (C++)

Source: https://context7.com/xilinx/vitis_templates/llms.txt

Defines an AIE dataflow graph by inheriting from adf::graph. It connects kernels and PLIO ports, specifying data dimensions and kernel sources. Window-based communication uses buffers for data transfer. Dependencies include adf.h and kernels.h.

```cpp
#include <adf.h>
#include "kernels.h"

using namespace adf;

class simpleGraph : public adf::graph {
private:
  kernel first;
  kernel second;
public:
  input_plio  in;
  output_plio out;

  simpleGraph(){
    // Create PLIO ports for 32-bit data
    in  = input_plio::create(plio_32_bits, "data/input.txt");
    out = output_plio::create(plio_32_bits, "data/output.txt");

    // Create kernel instances
    first = kernel::create(simple);
    second = kernel::create(simple);

    // Connect kernels in a chain
    adf::connect(in.out[0], first.in[0]);
    connect(first.out[0], second.in[0]);
    connect(second.out[0], out.in[0]);

    // Set data dimensions
    dimensions(first.in[0]) = { NUM_SAMPLES };
    dimensions(first.out[0]) = { NUM_SAMPLES };
    dimensions(second.in[0]) = { NUM_SAMPLES };
    dimensions(second.out[0]) = { NUM_SAMPLES };

    // Specify kernel source files
    source(first) = "kernels/kernels.cc";
    source(second) = "kernels/kernels.cc";

    // Set runtime constraints (percentage of time kernel is active)
    runtime<ratio>(first) = 0.1;
    runtime<ratio>(second) = 0.1;
  }
};

```
Tokens:
Raw