3.5.1 User Guide

Block partitioning aggregates consecutive elements of the original array into partitions. The number of partitions (blocks) is defined by the factor argument.

#pragma HLS memory partition variable(array2d) type(block) dim(1) factor(2)
int array2d[10][20];

For example, in the above code snippet array2d is specified to partition dimension 1 with factor 2. The result is two int[5][20] partitions where the first partitions has elements 0, 1, 2, 3, 4, and the second has elements 5, 6, 7, 8, 9 of dimension 1.

Cyclic partitioning interleaves elements from the original array into partitions. The number of interleaved partitions is defined by the factor argument. The array is partitioned cyclically by arbitrating the elements between the partitions, putting one element into each partition before coming back to the first one until the array is fully partitioned.

#pragma HLS memory partition variable(array2d) type(cyclic) dim(2) factor(2)
int array2d[10][10];

For example, in the above code snippet array2d is specified to partition dimension 2 with factor 2. The result is two int[10][5] partitions where the first partition has elements 0, 2, 4, 6, 8, and the second has elements 1, 3, 5, 7, 9 of dimension 2.

Complete partitioning deconstructs the array into individual elements along the specified dimension. For a multi-dimensional array, each element of the specified dimension will correspond to a partition with the rest of the dimensions preserved. For a one-dimensional array, individual elements are mapped to registers. If dim(0) is specified, complete partitioning is applied across all dimensions resulting in scalar elements.

Example

#pragma HLS memory partition variable(_array)
int _array[8];
int _result = 0;
//...

    for (i = 0; i < 8; i++) {
        _result += _array[i];
    }

The example above shows the same example that was shown for access-based partitioning, however, the loop is not unrolled in this case. Access-based partitioning will try to partition the array but will only find one load instruction in the loop that accesses the entire array. This preventing access-based partitioning as all eight accesses come from the same load instruction.

User-specified partitioning can be used to force partitioning of this array with a predefined structure. In the example above, the memory partition pragma specifies the array to be partitioned completely into eight individual elements.

Info: Partitioning memory: _array into 8 partitions.

The benefit in this case is that the loop does not have to be unrolled, which can be useful in cases like when the loop is pipelined and cannot be unrolled (see Loop Pipelining).

Struct-fields partitioning partitions a (array of) struct argument / variable into its individual fields such that each field is a partition. Unlike complete partitioning, if a field in the partitioned struct is an aggregate type (struct or array), the field is not further partitioned to its elements. Note that applying Struct-fields partitioning to an array-of-struct creates an array for each field in the struct. Unaccessed partitions (fields) are discarded, but the unaccessed elements in an aggreagte partition (field) are not discarded.

Example

struct Ty {
    struct SubTy {
        int a;
        int b;
    };
    char x;
    short y[2];
    SubTy z;
};

int sum(Ty array[8]) {
#pragma HLS function top
#pragma HLS memory partition argument(array) type(struct_fields)
    int result = 0;
    for (int i = 0; i < 8; i++) {
        result += array[i].x + array[i].y[0] + array[i].z.a;
    }
    return result;
}

The example above shows array, an array of struct of type Ty, is partitioned using Struct-fields partitioning. With the user-specified partitioning, SmartHLS™ outputs messages to the console stating that the argument set to be partitioned and how many partitions are created. The three partitions are array.x[8], array.y[8][2], and array.z[8], where the 8-element dimensions are inherited from the original array size.

Info: Found user specified memory: "array" on line 15 of struct_sum.cpp, with partition type: Fields, partition dimension: 0.
Info: Partitioning memory: array into 3 partitions.

The summary report from SmartHLS lists the 3 partitions created from the fields of the struct. Note that the array field Ty.y has one partition, and similarly the struct field Ty.z

Note that the fifo read() and write() calls are blocking. Hence if a module attempts to read from a FIFO that is empty, it will be stalled. Similarly, if it attempts to write to a FIFO that is full, it will be stalled. If you want non-blocking behaviour, you can check if the FIFO is empty (with empty()) before calling read(), and likewise, check if the FIFO is full (with full()) before calling write() (see Streaming Library - Non-Blocking Behaviour).

With the blocking behaviour, if the depths of FIFOs are not sized properly, it can cause a deadlock. SmartHLS™ prints out messages to alert the user that a FIFO is causing stalls.

In hardware simulation, the following messages are shown.

Warning: fifo_write() has been stalled for     1000000 cycles due to FIFO being full.
Warning: fifo_read() has been stalled for     1000000 cycles due to FIFO being empty.
Warning: fifo_read() has been stalled for     1000000 cycles due to FIFO being empty.
Warning: fifo_write() has been stalled for     1000000 cycles due to FIFO being full.
Warning: fifo_read() has been stalled for     1000000 cycles due to FIFO being empty.
Warning: fifo_read() has been stalled for     1000000 cycles due to FIFO being empty.

If you continue to see these messages, you can suspect that there is a deadlock. In this case, we recommend making sure there is no blocking read from an empty FIFO or blocking write to a full FIFO, and potentially increasing the depth of the FIFOs.

As mentioned above, non-blocking FIFO behaviour can be created with the use of empty() and full() functions. Non-blocking FIFO read and write can be achieved as shown below.

if (!fifo_a.empty())
    unsigned data_in = fifo_a.read();

if (!fifo_b.full())
    fifo_b.write(data_out);

The C++ Arbitrary Precision Integer Library provides some utilities for printing ap_[u]int types. The to_string(base, signedness) function takes an optional base argument (one of 2, 10, and 16) which defaults to 16, as well as an optional signedness argument which determines if the data should be printed as signed or unsigned, which defaults to false. The output stream operator << is also overloaded to put arbitrary precision integer types in the output stream as if they were called with the default to_string arguments.

Some example code using these utilities is shown below.

#include "hls/ap_int.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    ap_uint<8> ap_u = 21;
    ap_int<8> ap = -22;

    // prints: 0x15
    std::cout << "ap_u = 0x" << ap_u << std::endl;

    // prints: -22
    std::cout << "ap.to_string(10,true) = " << ap.to_string(10, true)
              << std::endl;

    // prints: 234
    std::cout << "ap.to_string(10) = " << ap.to_string(10) << std::endl;

    // prints 00010101
    printf("ap_u.to_string(2) = %s\n", ap_u.to_string(2).c_str());

The ap_[u]int types can be constructed and assigned to from other arbitrary precision integers, C++ integral types, ap_[u]fixpt types, as well as concatenations and bit selections. They can also be initialized from a hexadecimal string describing the exact bits.

Some examples of initializing arbitrary precision integer types are show below.

#include "hls/ap_fixpt.hpp"
#include "hls/ap_int.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    // Initialized to -7
    ap_int<4> int1 = -7;
    std::cout << "int1 = " << int1 << std::endl;

    // Initialized to 15
    // The bits below the decimal are truncated.
    ap_uint<4> int2 = ap_ufixpt<5, 4, AP_RND, AP_SAT>(15.5);
    std::cout << "int2 = " << int2 << std::endl;

    // Initialized to 132
    // Could also write "0x84"
    // The 0x is optional
    ap_uint<8> int3("84");
    std::cout << "int3 = " << int3 << std::endl;

    // Initialized to 4
    // Bit selections are zero extended to match widths
    ap_int<4> int4 = int3(2, 0);
    std::cout << "int4 = " << int4 << std::endl;

    // Initialized to 128
    // ap_uint types are zero extended to match widths
    // ap_int types are sign extended to match widths
    ap_int<16> int5 = ap_uint<8>("80");
    std::cout << "int5 = " << int5 << std::endl;

    // Initialized to 2
    // The value 4098 (= 4096 + 2) is wrapped to 2
    ap_uint<12> int6 = 4098;
    std::cout << "int6 = " << int6 << std::endl;

The C++ Arbitrary Precision Integer library supports all standard arithmetic, logical bitwise, shifts, and comparison operations. Note that for shifting that >> and << are logical, and the .ashr(x) function implements arithmetic right shift. The output types of an operation are wider than their operands as necessary to hold the result. Operands of ap_int, and ap_uint type, as well as operands of different widths can be mixed freely. By default ap_int will be self-extended to the appropriate width for an operation, while ap_uint will be zero-extended. When mixing ap_int and ap_uint in an arithmetic operation the resulting type will always be ap_int. Some of this behaviour is demonstrated in the example below.

#include "hls/ap_fixpt.hpp"
#include "hls/ap_int.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    ap_int<8> a = 7;
    ap_int<12> b = 100;
    ap_uint<7> c = 3;

    // Multiply expands to the sum of a and b's width
    ap_int<20> d = a * b;
    std::cout << "d = " << d << std::endl;

    // Add result in max of widths + 1
    ap_int<13> e = a + b;
    std::cout << "e = " << e << std::endl;

    // Logical bitwise ops result in max of widths
    ap_int<12> f = a & b;
    std::cout << "f = " << f << std::endl;

    // Mixing ap_int and ap_uint results in ap_int
    ap_int<9> g = a + c;
    std::cout << "g = " << g << std::endl;

    // ap_(u)int types can be mixed freely with integral types
    ap_int<33> h = -1 - a;
    std::cout << "h = " << h << std::endl;

The ap_[u]int types support several explicit conversion functions which allow the value to be interpreted in different ways. The to_uint64() function will return a 64 bit unsigned long long with the same bits as the original ap_[u]int, zero extending and wrapping as necessary. Assigning an ap_[u]int wider than 64 bits to an unsigned long long would also wrap to match widths, without needing to call to_uint64(). The to_int64() function will return a 64 bit signed long long and will sign extend as necessary.

An arbitrary precision integer data type can be casted to an arbitrary precision fixed-point data type with the to_fixpt<I_W>() and to_ufixpt<I_W>() functions (returns ap_fixpt<W, I_W> and ap_ufixpt<W, I_W> types respectively), with the same bits as the original ap_[u]int<W>. For more on the ap_[u]fixpt template, please refer to the C++ Arbitrary Precision Fixed Point Library section.

An example demonstrating these functions is shown below.

#include "hls/ap_int.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    // zero extend 16 bit -32768 to 64 bit 32768
    unsigned long long A = ap_int<16>(-32768).to_uint64();
    std::cout << "A = " << A << std::endl;

    // wrap from 65 bit 2**64 + 1 to 64 bit 1
    unsigned long long B = ap_uint<65>("10000000000000001").to_uint64();
    std::cout << "B = " << B << std::endl;

    // interpret 8 bit uint as 8 bit ufixpt with four bits above decimal
    // by value 248 becomes 15.5 (== 248 / 2**4)
    ap_ufixpt<8, 4> C = ap_uint<8>(248).to_ufixpt<4>();
    std::cout << "C = " << C << std::endl;

    // interpret 4 bit int as 4 bit fixpt with leading bit 8 bits above decimal
    // by value -8 becomes -128 (== -8 * 2**4)
    ap_fixpt<4, 8> D = ap_int<4>(-8).to_fixpt<8>();
    std::cout << "D = " << D << std::endl;

    // interpret 6 bit int as 6 bit ufixpt with 6 bits above decimal
    // by value 8 becomes 8
    ap_ufixpt<6, 6> E = ap_int<6>(8).to_ufixpt<6>();
    std::cout << "E = " << E << std::endl;

#include "hls/ap_int.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    ap_uint<8> Aa(0xBC);
    std::cout << "Aa = " << Aa << std::endl;
    ap_int<4> Bb = Aa(7, 4); // Bb initialized as 0xB; "Aa(7, 4)" is equivalent
                             // to "Aa.range(7, 4)"
    std::cout << "Bb = " << Bb << std::endl;
    ap_int<4> Cc = Aa[2]; // Cc initialized as 0x1
                          // Aa[2] is zero extended to match widths
    std::cout << "Cc = " << Cc << std::endl;

    Aa(3, 0) =
        0xA; // Aa becomes 0xBA; "Aa(3, 0) is equivalent to "Aa.range(3, 0)"
    std::cout << "Aa = " << Aa << std::endl;

    Aa.byte(1, 4) = 0xC; // Aa becomes 0xCA;
    std::cout << "Aa = " << Aa << std::endl;

    Aa.bytes(3, 2, 2) = 0xD; // AA becomes 0xDA
    std::cout << "Aa = " << Aa << std::endl;

On C++ arbitrary precision types num(a, b) (or num.range(a, b)) will select and create a reference to the underlying arbitrary precision value. The operator num[a] selects and creates a reference to a single bit. This reference can be assigned to, and used to access the underlying data. The arbitrary precision num.byte(n, s = 8) function selects and creates a reference to the n-th byte of the number which can be assigned to and used to access the underlying data. Similarly, the num.bytes(m, n, s = 8) function selects and creates a reference to a range of bytes from the m-th to the n-th byte (inclusive) of the number. In both functions, the last argument is an optional argument which defines the number of bits per byte, and defaults to 8.

#include "hls/ap_int.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    ap_uint<4> AA(0xA);
    std::cout << "AA = " << AA << std::endl;
    ap_uint<8> BB(0xCB);
    std::cout << "BB = " << BB << std::endl;
    ap_uint<8> AB((AA, BB(3, 0))); // AB initialized as 0xAB
    std::cout << "AB = " << AB << std::endl;
    ap_uint<12> ABC(
        (AA, ap_uint<4>(0xB), BB(7, 4))); // ABC initialized as 0xABC
    std::cout << "ABC = " << ABC << std::endl;

Putting any C++ arbitrary precision types in a comma separated list will generate a concatenation. The concatenation can currently be used to create arbitrary precision types (zero extending or truncating to match widths), but can not be assigned to.

The Arbitrary Precision Fixed Point Library provides some utilities for printing ap_[u]fixpt types in software, demonstrated below. The to_fixpt_string(base, signedness) function takes an optional base argument which is one of 2, 10, or 16, and defaults to 10, as well as an optional signedness argument which determines if the data should be treated as signed or unsigned. The signedness argument defaults to false for ap_ufixpt, and true for ap_fixpt.

The output stream operator << can be used to put a fixed point number into an output stream as if it were called with the default to_fixpt_string arguments.

The to_double() function can be useful for printing, but it can lose precision over a wide fixed point. It can be used in hardware, but this is expensive, and should be avoided when possible.

#include "hls/ap_fixpt.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    ap_ufixpt<8, 4> fixed = 12.75;
    ap_fixpt<8, 4> s_fixed("CC");

    // prints: -52 * 2^-4
    // Read -52 * 0.0625 = -3.25
    std::cout << s_fixed << std::endl;

    // prints: 11001100 * 2^-4
    // Read unsigned 11001100 * 2^-4 = 204 * 0.0625
    // = 12.75
    printf("%s\n", fixed.to_fixpt_string(2).c_str());

    // prints: CC * 2^-4
    // Read signed CC * 2^-4 = -52 * 0.0625
    // = -3.25
    std::cout << s_fixed.to_fixpt_string(16, false) << std::endl;

    // prints: -3.25
    printf("%.2f\n", s_fixed.to_double());

(gdb) print x
$2 = 0.49999999906867743 [0xfffffff8] <W:34,IW:1>

The ap_[u]fixpt types can be constructed and assigned from other fixed points, the ap_[u]int types, C++ integer and floating point types, as well as concatenations and bit selections. They can also be initialized from a hexadecimal string describing the exact bits. Note that construction and assignment will always trigger the quantization and overflow handling of the ap_[u]fixpt being constructed or assigned to, except when copying from the exact same type, or initializing from a hexadecimal string. For logical assignments of bits, bit selection assignments can be used, as well as the from_raw_bits function, or the ap_[u]int to_fixpt<I_W>() functions in the case of ap_[u]int types.

#include "hls/ap_int.hpp"
#include "hls/ap_fixpt.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    // Initialized to -13.75
    ap_fixpt<8, 4> fixed1 = -13.75;
    std::cout << "fixed1 = " << fixed1 << std::endl;
    // Initialized to 135
    ap_ufixpt<8, 8> fixed2 = 135;
    std::cout << "fixed2 = " << fixed2 << std::endl;
    // Initialized to -112
    // Could also write "0x9"
    // 0x is optional
    ap_fixpt<4, 8> fixed3("9");
    std::cout << "fixed3 = " << fixed3 << std::endl;
    // Initialized to 14
    ap_ufixpt<10, 4> fixed4 = ap_uint<16>(14);
    std::cout << "fixed4 = " << fixed4 << std::endl;
    // Initialized to -1 (AP_SAT triggered)
    ap_fixpt<4, 1, AP_TRN, AP_SAT> fixed5 = -4;
    std::cout << "fixed5 = " << fixed5 << std::endl;
    // Initialized to 1.5 (AP_RND triggered)
    ap_ufixpt<4, 3, AP_RND> fixed6 = 1.25;
    std::cout << "fixed6 = " << fixed6 << std::endl;
    // Initialized to 15.75 from a logical string of bits
    ap_ufixpt<8, 4> fixed7;
    fixed7(7, 0) = ap_uint<8>("FC");
    std::cout << "fixed7 = " << fixed7 << std::endl;
    // Assign an existing ap_uint variable to an ap_ufixpt variable
    ap_uint<8> ap_uint_var = 15;
    ap_ufixpt<8, 4> fixed8;
    fixed8(7, 0) = ap_uint_var;
    std::cout << "fixed8 = " << fixed8 << std::endl;
    // Initialize to 13 from a logical string of bits
    ap_fixpt<6, 5> fixed9;
    fixed9.from_raw_bits(ap_uint<6>(26));
    std::cout << "fixed9 = " << fixed9 << std::endl;
    // Initialize to -32 from a logical string of bits
    // (First convert ap_uint<4> to ap_fixpt<4, 6> logically,
    // then perform fixed point assignment)
    ap_fixpt<1, 6> fixed10 = ap_uint<4>("8").to_fixpt<6>();
    std::cout << "fixed10 = " << fixed10 << std::endl;
    // Initialize to 32 from a logical string of bits
    // (First convert ap_int<4> to ap_ufixpt<4, 6> logically,
    // then perform fixed point assignment)
    ap_ufixpt<1, 6> fixed11 = ap_int<4>("8").to_ufixpt<6>();
    std::cout << "fixed11 = " << fixed1 << std::endl;

The Arbitrary Precision Fixed Point library supports all standard arithmetic, logical bitwise, shifts, and comparison operations. During arithmetic intermediate results are kept in a wide enough type to hold all of the possible resulting values. Operands are shifted to line up decimal points, and sign or zero-extended to match widths before an operation is performed. For fixed point arithmetic, whenever the result of a calculation can be negative the intermediate type is an ap_fixpt instead of ap_ufixpt regardless of whether any of the operands were ap_fixpt. Overflow and quantization handling only happen when the result is assigned to a fixed point type.

Fixed point types can be mixed freely with other arbitrary precision and c++ numeric types for arithmetic, logical bitwise, and comparison operations, with some caveats for floating point types.

#include "hls/ap_fixpt.hpp"
#include <iostream>
#include <stdio.h>

using namespace hls;

    //...
    ap_ufixpt<65, 14> a = 32.5714285713620483875274658203125;
    ap_ufixpt<15, 15> b = 7;
    ap_fixpt<8, 4> c = -3.125;

    // the resulting type is wide enough to hold all
    // 51 fractional bits of a, and 15 integer bits of b
    // the width, and integer width are increased by 1 to hold
    // all possible results of the addition
    ap_ufixpt<67, 16> d = a + b; // 39.5714285713620483875274658203125
    std::cout << "d = " << d << std::endl;
    // the resulting type is a signed fixed point
    // with width, and integer width that are the sum
    // of the two operands' widths
    ap_fixpt<23, 19> e = b * c; // -21.875
    std::cout << "e = " << e << std::endl;
    // Assignment triggers the AP_TRN_ZERO quantization mode
    ap_fixpt<8, 7, AP_TRN_ZERO> f = e; // -21.5
    std::cout << "f = " << f << std::endl;
    // Mask out bits above the decimal
    f &= 0xFF; // -22
    std::cout << "f = " << f << std::endl;
    // Assignment triggers the AP_SAT overflow mode,
    // and saturates the negative result to 0
    ap_ufixpt<8, 4, AP_TRN, AP_SAT> g = b * d; // 0
    std::cout << "g = " << g << std::endl;

We will use a more complete example to further demonstrate how to use DoubleBuffer and SharedBuffer in a multi-threaded dataflow design, and how the buffer classes enable parallelism between the dataflow threads.

Say we have a continuous input stream, every 2048 elements in the stream is considered as a segment. We are going to sort each 2048-element segment of the input stream and write the sorted segments to an output stream.

As we know, no algorithm can sort with an O(n) runtime performance. That is, a sorting algorithm needs to visit each element more than once, and hence the sorting algorithm cannot process the data stream at line rate and cannot work on the streaming FIFO interfaces directly. A dataflow design in this case can be composed of three stages, 1) store each 2048-element segment of input stream into a buffer, 2) sort the elements in the buffer, and 3) stream out the sorted elements. The three processing stages form a dataflow design, where the output produced by the earlier stage is consumed by the next stage.

For better throughput, we can overlap the three processing stages with multi-threading, and use DoubleBuffer or SharedBuffer to synchronize the accesses to the shared buffer between upstream and downstream threads. Compared to SharedBuffer, each DoubleBuffer contains two copies of storage instead of one, which reduces the delay that a processing stage waits for the buffer to become available.

The code below describes the design in C++:

#include <hls/data_buffer.hpp>
#include <hls/streaming.hpp>
#include <stdio.h>

#define N 2048

using hls::DoubleBuffer;
using hls::FIFO;
using hls::ref;
using hls::thread;

// Reads input stream into array.
void StreamToBuffer(FIFO<int> &in_fifo, DoubleBuffer<int[N]> &in_buffer) {
    auto &buf_array = in_buffer.producer(); // Obtain the reference to buffer.
    while (1) {
        in_buffer.producer_acquire(); // Acquire buffer to write output data.

#pragma HLS loop pipeline
        for (int i = 0; i < N; i++)
            buf_array[i] = in_fifo.read();

        in_buffer.producer_release(); // Release buffer to downstream.
    }
}

// Forward declare the MergeSortArray function. Implementation is shown below.
void MergeSortArray(int in[N], int out[N]);

// Performs merge sort whenever the input and output buffers become available.
void MergeSort(DoubleBuffer<int[N]> &in_buffer, DoubleBuffer<int[N]> &out_buffer) {
    auto &in = in_buffer.consumer();   // Obtain the reference to input buffer.
    auto &out = out_buffer.producer(); // Obtain the reference to output buffer.

    while (1) {
        in_buffer.consumer_acquire();  // Acquire input buffer from upstream.
        out_buffer.producer_acquire(); // Acquire buffer for output.

        MergeSortArray(in, out);

        out_buffer.producer_release(); // Release output buffer to downstream.
        in_buffer.consumer_release();  // Release input buffer back to upstream.
    }
}

// Writes array into output stream.
void BufferToStream(DoubleBuffer<int[N]> &out_buffer, FIFO<int> &out_fifo) {
    auto &buf_array = out_buffer.consumer(); // Obtain the reference to buffer.
    while (1) {
        out_buffer.consumer_acquire(); // Acquire buffer to read data from upstream.

#pragma HLS loop pipeline
        for (int i = 0; i < N; i++)
            out_fifo.write(buf_array[i]);

        out_buffer.consumer_release(); // Release buffer back to upstream.
    }
}

// Top-level function implementing a pipeline that sorts data stream.
void MergeSortPipeline(FIFO<int> &in_fifo, FIFO<int> &out_fifo) {
    // Create two buffers as the intermediate storage for the three threads/functions.
    DoubleBuffer<int[N]> in_buffer, out_buffer;

    thread<void>(StreamToBuffer, ref(in_fifo), ref(in_buffer));
    thread<void>(MergeSort, ref(in_buffer), ref(out_buffer));
    thread<void>(BufferToStream, ref(out_buffer), ref(out_fifo));
}

• The StreamToBuffer, MergeSort, and BufferToStream functions correspond to the blue function blocks in the above diagram.
  • StreamToBuffer reads in_fifo stream and writes to in_buffer, MergeSort reads in_buffer and writes to out_buffer, BufferToStream reads out_buffer and writes to out_fifo stream,each function calls the corresponding producer or consumer side methods to access the shared DoubleBuffer, as described in the above section.
  The MergeSortPipeline function implements the dataflow pipeline,
• • the in_fifo and out_fifo arguments correspond to the input and output streams of the pipeline,the intermediate DoubleBuffer are instantiated: in_buffer and out_buffer, corresponding to the gray buffer blocks in the above diagram,the three processing functions are then invoked as parallel threads, and the input and output data are passed by reference to the threads (also see Supported HLS Thread APIs).
  Since we want the pipeline to continuously process the data stream, the three processing threads are made free-running. To achieve this,
• • in each of the three processing functions, wrap the operations inside an infinite while (1) loop; each loop iteration processes one segment of data,the three threads forked in MergeSortPipeline function are never joined and left constantly running.
• Now we have three free-running threads, each can start processing a new segment of data whenever the input/output storage becomes available to acquire via the <producer|consumer>_acquire() methods.

In this design, each of the input and output buffers has two copies of storage for the 2048-element segment. By having two copies of storage in a double buffer, the upstream producer can write a new batch of output to one copy of storage, while the downstream consumer simultaneously processes the previous batch stored in the other copy of storage as input.

The figure below illustrates how DoubleBuffer allows to overlap the executions of upstream and downstream threads.

At time a, Str2Buf starts to receive input stream and store every 2048 input elements to storage A of input buffer (annotated as "in/A" in the figure).

• At time b, when Str2Buf finishes storing the first segment,
  • Sort starts working on the input stored in storage A of input buffer, and saves sorted result into storage A of output buffer,meanwhile Str2Buf can start storing the second segment to storage B of input buffer.
  At time c, when Sort finishes sorting the first segment,
• • output buffer's storage A is released for Buf2Str to send sorted segment to output stream,input buffer's storage A is freed up for Str2Buf to store the next segment (segment 3),and by this time, Str2Buf has finished storing segment 2 into input buffer's storage B, so Sort can immediately start working on segment 2.
  • • We assume Sort takes more time than Str2Buf.
  From this point on, the dataflow pipeline enters steady state -- whenever Sort finishes (e.g., at time c, d, and e),
• • one input storage is released to the upstream Str2Buf to store a new input segment,one output storage is released to the downstream Buf2Str to stream out the sorted segment,the Sort stage itself can work on the next segment immediately, the throughput of the dataflow pipeline is determined by the most time-consuming stage, i.e., Sort in this case.

The above C++ code can be easily changed to use SharedBuffer, by simply replacing all DoubleBuffer type with SharedBuffer type. When using SharedBuffer, each buffer has only one copy of storage, which can only be accessed by one function at a time. So two adjacent upstream and downstream functions cannot be both active simultaneously. The figure below shows the timeline when using SharedBuffer:

Notice at time b, when Str2Buf finishes writing a segment to input buffer, Str2Buf cannot immediately start writing the next segment as in the DoubleBuffer case. Str2Buf needs to wait until Sort finishes sorting at time c and releases the only input buffer storage, in order to start storing the next segment. Similarly, when Sort is running and has the output buffer acquired, the downstream Buf2Str has to wait.

In short, when Sort is running, its upstream Str2Buf and downstream Buf2Str have no available buffers to continue processing and have to wait; when Sort finishes, Str2Buf and Buf2Str can be both active (e.g., from time c to d), because they do not access common buffers.

In this case, the throughput of the dataflow pipeline is determined by the latency of Sort plus Str2Buf (or Buf2Str, whichever is longer).

For completeness, the code below implements the merge sort algorithm (MergeSortArray) and a main function injecting input and checking output to/from the dataflow pipeline. Note that,

• The MergeOnePass function merges the multiple pairs of halves from one array into another array. The MergeSortArray calls MergeOnePass repeatedly with a doubling partition size, and alternates the input and output array arguments between calls to reuse memory. The two arrays are the storage inside the input and output buffers. As you can see, the sort function, being the consumer of the input buffer, can also write to the buffer; and being the producer of the output buffer, can also read from the buffer. Since free-running threads (that are continuously running and never joined) are not supported by SW/HW Co-Simulation (limitation listed in Simulate HLS Hardware (SW/HW Co-Simulation)), we make the main function as the top-level to generate hardware for the entire program, so that the Simulate Hardware (shls sim) feature can run directly without a custom testbench.

// One pass of merge with partition_size -- merging multiple pairs of halves
// across the whole array.
// For each pair, merges the two haves in[l .. m] and in[m + 1 .. r] into out[l
// .. r], where m = l + partition_size - 1, r = l + 2 * partition_size - 1
// Assume the array size is a power of 2.
void MergeOnePass(int in[N], int out[N], int partition_size) {
    for (unsigned left_idx = 0; left_idx < N; left_idx += 2 * partition_size) {
        int m = left_idx + partition_size - 1, r = m + partition_size;
        // Indices in the input and output arrays.
        int i = left_idx, j = m + 1;

#pragma HLS loop pipeline
        for (int k = left_idx; k < left_idx + 2 * partition_size; k++) {
            bool copy_i = (i > m) ? false : (j > r) ? true : in[i] < in[j];
            if (copy_i) {
                out[k] = in[i];
                i++;
            } else {
                out[k] = in[j];
                j++;
            }
        }
    }
}

// Merge sort is done in multiple steps, each step merges on two partitions with
// twice bigger the size of previous step.
void MergeSortArray(int in[N], int out[N]) {
    // Each MergeOnePass merges from halves in array 'in' to 'out', then
    // alternates to merge halves in array 'out' to 'in'.
    // We can reuse the memory by alternating the in and out arrays.
    MergeOnePass(in, out, 1);
    MergeOnePass(out, in, 2);
    MergeOnePass(in, out, 4);
    MergeOnePass(out, in, 8);
    MergeOnePass(in, out, 16);
    MergeOnePass(out, in, 32);
    MergeOnePass(in, out, 64);
    MergeOnePass(out, in, 128);
    MergeOnePass(in, out, 256);
    MergeOnePass(out, in, 512);
    MergeOnePass(in, out, 1024);
}

#define TEST_ITERATIONS 10
int main() {
#pragma HLS function top
    FIFO<int> in_fifo(TEST_ITERATIONS * N), out_fifo(TEST_ITERATIONS * N);
    for (int i = 0; i < TEST_ITERATIONS * N; i++)
        in_fifo.write(TEST_ITERATIONS * N - 1);

    MergeSortPipeline(in_fifo, out_fifo);

    unsigned err_cnt = 0;
    for (int n = 0; n < TEST_ITERATIONS; n++) {
        int last = out_fifo.read();
        for (int i = 1; i < N; i++) {
            int cur = out_fifo.read();
            if (last > cur) {
                printf("i: %d, last (%d) > cur (%d)\n", i, last, cur);
                err_cnt += 1;
            }
            last = cur;
        }
    }

    if (err_cnt)
        printf("FAIL. err_cnt = %d\n", err_cnt);
    else
        printf("PASS. err_cnt = %d\n", err_cnt);
    return err_cnt;
}

The LineBuffer class implements the line buffer structure that is commonly seen in image convolution (filtering) operations, where a filter kernel is "slided" over an input image and is applied on a local window (e.g., a square) of pixels at every sliding location. As the filter is slided across the image, the line buffer is fed with a new pixel at every new sliding location while retaining the pixels of the previous image rows that can be covered for the sliding window. The public interface of the LineBuffer class is shown below,

template <typename PixelType, unsigned ImageWidth, unsigned WindowSize>
class LineBuffer {
  public:
    PixelType window[WindowSize][WindowSize];
    void ShiftInPixel(PixelType input_pixel);
};

Below shows an example usage of the LineBuffer class:

• Instantiate the line buffer in your C++ code, with template arguments being the pixel data type, input image width, and sliding window size. The window maintained by the line buffer assumes a square WindowSize x WindowSize window. If you are instantiating the line buffer inside a pipelined function (accepting a new pixel in every function call), you will need to add 'static' to make the line buffer static.

  static hls::LineBuffer<unsigned char, ImageWidth, WindowSize> line_buffer;

• Shift in a new pixel by calling the ShiftInPixel method:

  line_buffer.ShiftInPixel(input_pixel);

• Then your filter can access any pixels in the window by:

  line_buffer.window[i][j]

The figure below illustrates how the line buffer window is being updated after each call of ShiftInPixel. You will notice that the window can contain out-of-bound pixels at certain sliding locations.

For more details about when/why to use the LineBuffer class, see Inferring a Line Buffer.

template <typename PixelType, unsigned ImageWidth, unsigned WindowSize,
          bool SB_WRITE_BACK = false, bool DB_OVERRIDE = false,
          PixelType DB_DEFAULT = PixelType()>
class LineBuffer_ECC{
  public:
    PixelType window[WindowSize][WindowSize];
    void ShiftInPixel(PixelType input_pixel);
    int sb_count();
    int db_count();
    int reset_counters();
    void scrub();
};

The HLS module can also be controlled via an AXI4 target interface in a memory-mapped manner. When axi_target interface type is specified in the pragma, a module control register and a return value register will be created and made accessible behind the HLS module’s AXI4 target interface. The AXI4 target interface’s associated ports are named as axi4target_*. Writing a value of 1 to the module control register will start the HLS module. When reading from the module control register, a value of 1 means the HLS module is still running; a value of 0 means the HLS module is idle (or has finished running). When the HLS module finishes, the return value of the top-level function (if not void type) can be retrieved by reading the return value register. The memory-mapped address offsets of these registers can be found in the AXI4 Target Interface Address Map section of the SmartHLS Report. In addition, driver functions are generated for convenient module control from an attached processor (see Module Control Driver Functions ).

Note that to use AXI4 target interface for module control, the top-level function's return type must be a C primitive data type (e.g., char, unsigned int, double, and etc; cannot be a struct or ap_int type). Using AXI4 target interface for module control is not suitable for designs with pipeline functions.

A scalar argument with a simple interface type becomes an input port of the top-level RTL module. Valid argument values should be provided on these input ports when the HLS module starts (i.e., when start signal is asserted, or when the MyTopFunc_start() driver function is called). If the input port can be held valid and unchanged throughout the whole iteration of the execution, a stable option can be specified using the following pragma to inform SmartHLS™ and potentially save register usage in the generated module.

As shown in the table below, each scalar argument corresponds to an input port of the top-level module.

When a scalar argument's interface type is configured to axi_target, a register corresponding to the scalar argument will be made accessible behind the HLS module's AXI4 target interface. Typically, a write operation to the AXI4 target interface is performed to update the scalar argument value before starting the HLS module. The register value stays unchanged until next write to the register, so no need to update the scalar argument register again if a new invocation of the HLS module uses the same value for the scalar argument as the last invocation. The scalar argument registers are also readable via the AXI4 target interface. The corresponding memory-mapped address offset of the scalar argument register can be found in the AXI4 Target Interface Address Map section of the SmartHLS Report. In addition, SmartHLS™ generates driver functions for convenient write and read to the scalar argument (see API Driver Functions for AXI4 Target).

Note that to use AXI4 target interface for a scalar argument, the argument type needs to be a C primitive data type (e.g., char, unsigned int, double, and etc; cannot be a struct or ap_int type).

The memory interface can be used for any pointer arguments or global variables (including array and struct types). The memory interface can be connected to an external RAM module that stores the corresponding data so that the HLS module can access the data in the external RAM. The pragma below specifies the memory interface type for a given argument or global variable,

// For top-level function arguments:
// Add at the beginning of the function definition
#pragma HLS interface argument(<ARGUMENT_NAME>) type(memory) num_elements(<NUM_ARRAY_ELEMENTS>)

// For shared global variables:
// Add before the variable definition
#pragma HLS interface variable(<ARGUMENT_NAME>) type(memory) num_elements(<NUM_ARRAY_ELEMENTS>)

The num_elements option is only available for array type arguments. The array size can be specified or overridden (over the declared size in C++) by specifying the num_elements option.

When AXI4 initiator is used for a pointer argument (not available for global variable), the HLS module will include an AXI4 initiator interface, with the associated ports named as axi4initiator_*. The "memory" referenced by the pointer argument is considered external to the HLS module. All memory accesses to the pointer argument will be translated into read or write AXI4 transactions through the AXI4 initiator interface. The pragma below specifies the AXI4 initiator interface type for a pointer argument (including array, struct, class types),

#pragma HLS interface argument(<ARGUMENT_NAME>) type(axi_initiator) \
                      ptr_addr_interface(<simple|axi_target>) \
                      num_elements(<NUM_ARRAY_ELEMENTS>) \
                      max_burst_len(<AXI4I_MAX_BURST_LENGTH>) \
                      max_outstanding_reads(<AXI4I_MAX_OUTSTANDING_READS>) \
                      max_outstanding_writes(<AXI4I_MAX_OUTSTANDING_WRITE>)

Typically the AXI4 initiator interface is connected to the AXI4 target (or AXI4 slave) interface of a memory block like DDR. The external logic would need to inform the HLS module where in the memory block to access the data referenced by the pointer argument. This is the same concept as a pointer argument of a software function that runs on a processor --- consider invoking a function void foo(int *ptr_arg) in software, the ptr_arg is essentially the address in processor memory for function foo to access. Hence each argument using AXI4 initiator interface is associated with a pointer address interface for specifying the base address in the connected memory block that the HLS module will access. The pointer address interface can be configured via the ptr_addr_interface option with two modes, simple and axi_target.

• For simple: the HLS module will have a simple input port with the same name as the pointer argument. The external logic should set the base pointer address on the input port before the HLS module starts.
• For axi_target: the HLS module will create a register behind the AXI4 target interface. The external logic should use AXI4 write transaction to set the base pointer address via the AXI4 target interface. The address offset of the register can be found in the AXI4 Target Interface Address Map section of the SmartHLS Report. A driver function will be generated to set the register (see ref:AXI4 Initiator Argument's Pointer Address Driver Functions).
• The default ptr_addr_interface is simple; but when the default-to-axi_target interface pragma is used, the default ptr_addr_interface becomes axi_target.

To illustrate further about pointer address, consider the following example,

void incr(char *ptr) {
    #pragma HLS interface argument(ptr) type(axi_initiator) ptr_addr_interface(axi_target)
    for (int i = 0; i < 10; i++) {
        *ptr = *ptr + 3;
        ptr++;  // Increment the pointer by 1 byte.
    }
}

In this example, when we start the incr hardware block, we need to pass the base pointer address using the AXI4 target interface, as specified by the ptr_addr_interface(axi_target). Assuming we write a base address of 0xFFFF0000 to the AXI4 target interface, then this module will read the data, increment by 3, and write back new data, for each of the ten char from memory address 0xFFFF0000 to 0xFFFF0009.

The num_elements option is only available for array type arguments. The array size can be specified or overridden (over the declared size in C++) by specifying the num_elements option. This option is needed by the Simulate HLS Hardware (SW/HW Co-Simulation) feature to know the size of the external memory to be modelled in the simulation testbench; this option does not affect the HLS-generated RTL/circuit.

By default, each read or write to an AXI4 initiator pointer argument in the C++ will become a non-burst AXI4 transaction. However, when the read or write is inside a loop, SmartHLS can detect when a burst transaction can be used instead, and SmartHLS will combine the reads or writes that occur over multiple loop iterations into an AXI4 burst transaction. In order to use a loop to infer an AXI4 burst transfer, the loop should have the following properties:

• The loop should be pipelined (see Loop Pipelining).
• The loop bound should be known before the loop executes.
• The loop should have no more than 1 read and no more than 1 write to AXI4 initiator pointer arguments.
• The addressing for the reads and writes should be incrementing by 1 word per loop iteration.
• The reads and writes should not be inside conditional statements.

#define NUM_ELEMENTS 1000

void init_array(int *out_array) {
#pragma HLS function top
// In the interface argument, set the max burst length to 64
#pragma HLS interface argument(out_array) type(axi_initiator)                  \
    ptr_addr_interface(axi_target) num_elements(NUM_ELEMENTS)                  \
        max_burst_len(64)

// Burstable
#pragma HLS loop pipeline
    for (unsigned idx = 0; idx < NUM_ELEMENTS; ++idx) {
        out_array[idx] = idx;
    }
}

#define NUM_ELEMENTS 1000

void init_array(int *out_array) {
#pragma HLS function top
// In the interface argument, set the max burst length to 64
#pragma HLS interface argument(out_array) type(axi_initiator)                  \
    ptr_addr_interface(axi_target) num_elements(NUM_ELEMENTS)                  \
        max_burst_len(64)

// Not burstable - two writes per iteration
#pragma HLS loop pipeline
    for (unsigned idx = 0; idx < NUM_ELEMENTS / 2; ++idx) {
        out_array[idx] = idx;
        out_array[idx * 2] = idx + 1;
    }

// Not burstable - address is not incrementing by one
#pragma HLS loop pipeline
    for (unsigned idx = 0; idx < NUM_ELEMENTS / 2; ++idx) {
        out_array[idx * 2] = idx + 1;
    }

// Not burstable - write is inside conditional code
#pragma HLS loop pipeline
    for (unsigned idx = 0; idx < NUM_ELEMENTS; ++idx) {
        if (idx % 10)
            out_array[idx] = idx;
    }

}

SmartHLS also supports allowing multiple AXI4 Initiator burst requests to be left outstanding without stalling the accelerator. By sending more burst requests in advance, the AXI4 target can have more time to respond, potentially reducing the time the SmartHLS accelerator needs to wait. Using this feature infers internal FIFOs in the design, of size max_ouststanding_<reads/writes> * addr_size for the ARADDR and AWADDR channels and max_outstanding_<reads/writes> * max_burst_len * word_size for RDATA and WDATA channels. The max_burst_len and max_outstanding_<reads/writes> can be set separately for input and output AXI4 Initiator arguments, allowing the user to optimize their read and write burst transactions separately. An example of how to use the interface pragmas to specify this behaviour is shown below. In this example, addr_size depends on the AXI4 interface address width (SmartHLS will generate an interface with address width 64), and word_size depends on the argument type (in this case since the argument is an int pointer, the word size is 32.

#define NUM_ELEMENTS 10000
#define USE_OPTIMIZED 1

// Use AXI initiator to copy from one external memory to another.
void copy_array(unsigned *in_array, unsigned *out_array, unsigned num_elements) {
#ifndef USE_OPTIMIZED
#pragma HLS function top
#pragma HLS interface default type(axi_target)
#pragma HLS interface argument(in_array) type(axi_initiator)                   \
    num_elements(NUM_ELEMENTS)
#pragma HLS interface argument(out_array) type(axi_initiator)                  \
    num_elements(NUM_ELEMENTS)
#endif
    for (unsigned idx = 0; idx < num_elements; ++idx) {
        out_array[idx] = in_array[idx];

The values specified for these interface pragmas can be tuned to optimize the throughput of the AXI4 Initiator interface. For more information on how to pick these values to improve performance, see Optimizing AXI4 Initiator Performance. For more information on the semantics of the interface pragmas themselves, see the relevant Pragma Guide section: AXI4 Initiator Interface for Pointer Argument . If finer control of the burst transfer is required, consider Implementing A Custom AXI4 Master/Slave Using hls::FIFO.

In contrast to the memory interface and AXI4 initiator interface, when the AXI4 target (or the legacy AXI4 slave below) interface is used, the "memories" for storing the data is inside the SmartHLS-generated RTL module rather than outside. The logic outside of SmartHLS module is responsible for initializing and/or retrieving the memory content before and/or after the execution of SmartHLS module. For example, when a int32_t array[128] argument is configured to use AXI4 target interface, the HLS module will include a 32-bit wide, 128-element deep on-chip buffer for the array argument. If the argument is an input to the top-level function, initialization of the on-chip buffer should be performed before the HLS module starts execution. If the argument is an output, the external logic can retrieve the output value from the on-chip buffer after HLS module's execution. An argument can be both input and output to the top-level function, in which case the data initialization and retrieval are done before and after the execution. The memory-mapped address offset and size of the on-chip buffer can be found in the AXI4 Target Interface Address Map section of the SmartHLS Report. Driver functions will be also generated to facilitate data transfer to/from the on-chip buffer from software (see Pointer Argument Driver Functions)

The pragma below specifies an AXI4 target interface for a pointer argument (including array, struct, class types),

// The axi_target interface type can only be used for function arguments, not for global variables.
// Add at the beginning of the function definition
#pragma HLS interface argument(<ARGUMENT_NAME>) type(axi_target) \
                      num_elements(<NUM_ARRAY_ELEMENTS>) dma(true|false) requires_copy_in(true|false)

The num_elements option is only available for array type arguments. The array size can be specified or overridden (over the declared size in C++) by specifying the num_elements option.

The dma and requires_copy_in options are to configure the behaviour of the top-level driver function, and do not affect the HLS-generated hardware. See Top-level Driver Options in Pointer Arguments' AXI4 Target Interface Pragma for details about how these two options affect the top-level driver functions.

When accessing the on-chip buffer via the AXI4 target interface, incremental burst transfer can be used for better transfer throughput. However, an AXI4 transaction can not cover addresses that belong to more than one on-chip buffers (i.e., access more than one arguments in one AXI4 transfer).

Note that the AXI4 target interface can not be applied to a global variable.

The legacy AXI4 slave interface is similar to the AXI4 target interface in hardware. The legacy AXI4 slave interface can only be applied to a global variable with a struct data type, where each struct element becomes a memory-mapped register or RAM that can be accessed via the AXI4 slave interface. The pragma below specifies an AXI4 slave interface,

// For shared global variables:
// Add before the variable definition
#pragma HLS interface variable(<GLOBAL_VARIABLE_NAME>) type(axi_slave) concurrent_access(true|false)

When the concurrent_access option is set to true (default to false), the external logic can read/write the AXI4 slave interface while the SmartHLS module is running. The concurrent access will however reduce the SmartHLS module's throughput to access the memory.

After compilation, SmartHLS will generate a report file (hls_output/reports/axi_slave_memory_map.hls.rpt) to specify the address map for each struct element. Here is an example struct and its corresponding memory map.

#ifndef __SLAVE_LAYOUT_H__
#define __SLAVE_LAYOUT_H__

#include <stdint.h>

// Define the AXI slave memory layout as a struct in a header file.
struct SlaveLayout {
    uint16_t array[8];
    uint32_t a, b;
    uint64_t sum_result;
    uint32_t xor_result, or_result;
};

#endif

// Declare a 'SlaveLayout' type global variable in C++ source file (.cpp).
// Use HLS interface pragma with axi_slave type to specify an AXI4 slave interface.
#pragma HLS interface variable(global_var) type(axi_slave) concurrent_access(true)
SlaveLayout global_var;

The corresponding address map report (hls_output/reports/axi_slave_memory_map.hls.rpt) is shown below.

Address Map for AXI Slave Interface: global_var

+--------------+-----------+-------------------+----------+
| Word Address | Bit Range | Variables         | Removed? |
+--------------+-----------+-------------------+----------+
| 0            |  15 :  0  | memory.array[0]   |          |
|              |  31 : 16  | memory.array[1]   |          |
|              |  47 : 32  | memory.array[2]   |          |
|              |  63 : 48  | memory.array[3]   |          |
| 1            |  15 :  0  | memory.array[4]   |          |
|              |  31 : 16  | memory.array[5]   |          |
|              |  47 : 32  | memory.array[6]   |          |
|              |  63 : 48  | memory.array[7]   |          |
| 2            |  31 :  0  | memory.a          |          |
|              |  63 : 32  | memory.b          |          |
| 3            |  63 :  0  | memory.sum_result |          |
| 4            |  31 :  0  | memory.xor_result |          |
|              |  63 : 32  | memory.or_result  |          |
| 5            |   0 :  0  | slave_memory_ctrl |          |
+--------------+-----------+-------------------+----------+

• Note that the first column in the report shows the word-address -- multiply by 8 to get the byte-address.
• The last column will indicate the struct elements that are optimized away from compilation because the SmartHLS module does not access them.
• Notice that the last element in the table, slave_memory_ctrl, is not part of the struct definition. This is a special status control register for the SmartHLS module. Writing to the address of slave_memory_ctrl will start the SmartHLS module (if the module was not running), and reading the register can poll the status, a value of 1 indicates the SmartHLS module has finished running, and 0 otherwise. This memory-mapped control interface can be useful for an AXI4 master to control the SmartHLS-generated module's execution (e.g., a processor controlling the SmartHLS-generated module).

In addition to inferring an AXI4-stream interface as shown in the example above, hls::FIFO can also be used to implement a custom AXI4 slave or AXI4 master. The AXI4 interface protocol has 5 channels, read address (AR), read data (R), write address (AW), write data (W), and write response (B). Each channel is an AXI4 stream interface and can be described in C++ as a hls::FIFO object. For example, the read address channel has an address signal and a length signal. The AXI4 channel can be implemented as following in C++ to get the corresponding AR channel in the RTL interface.

struct RdAddrSignals { uint32_t addr;  uint8_t len; };

void MyTopFunctoin (hls::FIFO<RdAddrSignals> ar) {
  RdAddrSignals ar_sig;
  ar_sig.addr = 0x2000;
  ar_sig.len = 7;  // 8-beat burst.
  ar.write(ar_sig);
}

module MyTopFunction (
  input clock,
  input reset,
  input         ar_ready,
  output        ar_valid,
  output [31:0] ar_addr,
  output [7:0]  ar_len
);

SmartHLS™ provides a C++ library for implementing the AXI4 master interfaces. The library defines the AXI4 master interface in C++ and provides several API functions for typical operations. For advanced users hoping to have more fine-grained custom control, or additional AXI4 interface signals that are not included in the library, the library can serve as a reference implementation for customization (create your own AXI4 master library based on SmartHLS's axi_interface.hpp header file).

To create an AXI4 master interface using SmartHLS's library, include the header file:

#include <hls/axi_interface.hpp>

To add an AXI4 master interface, you will need to:

1. Create an instance of the AxiInterface class and specify the address width, data width and wstrb width through template parameters.
2. Pass the created instance by reference to the top-level function. E.g., void MyTop(AxiInterface</* ADDR: */ ap_uint<32>, /* DATA: */ ap_uint<64>, /* WSTRB: */ ap_uint<8>> &master);
3. Use the utility functions (APIs) defined in the header to control the AXI master interface.

The following are the API functions to access the AXI master interface.

/*
Send a read request starting from 'byte_addr' for 'burst_len' number of transfers.
- 'burst_len' can not be greater than 256 (max: 256) according to AXI4 specification.
- 'burst_type' is optional. The default value is 1 (incremental).
- 'transfer_size' is optional. The default value is automatically set to the full size matching T_DATA.
  - The byte size per transfer equals to 2 to the power of transfer_size.
  - e.g., if T_DATA is of an ap_uint<64> or uint64 type, the default transfer_size is 3.
*/
template <class T_ADDR, class T_DATA, class T_WSTRB>
void axi_m_read_req(AxiInterface<T_ADDR, T_DATA, T_WSTRB> &m,
                    T_ADDR byte_addr, ap_uint<9> burst_len,
                    ap_uint<2> burst_type = 1,
                    ap_uint<3> transfer_size = <SIZE_MATCHING_T_DATA>);

/*
Receive the read data (return value) for one read transfer.
- The function should be called after a read request is sent by 'axi_m_read_req'.
- For a read request with 'burst_len' number of transfers, this function
  should be called for 'burst_len' number of times to receive all read data.
*/
template <class T_ADDR, class T_DATA, class T_WSTRB>
T_DATA axi_m_read_data(AxiInterface<T_ADDR, T_DATA, T_WSTRB> &m);

/*
Send a write request starting from 'byte_addr' for 'burst_len' number of transfers.
- 'burst_len' can not be greater than 256 (max: 256) according to AXI4 specification.
- 'burst_type' is optional. The default value is 1 (incremental).
- 'transfer_size' is optional. The default value is automatically set to the full size matching T_DATA.
  - The byte size per transfer equals to 2 to the power of transfer_size.
  - e.g., if T_DATA is of an ap_uint<64> or uint64 type, the default transfer_size is 3.
*/
template <class T_ADDR, class T_DATA, class T_WSTRB>
void axi_m_write_req(AxiInterface<T_ADDR, T_DATA, T_WSTRB> &m,
                     T_ADDR byte_addr, ap_uint<9> burst_len,
                     ap_uint<2> burst_type = 1,
                     ap_uint<3> transfer_size = <SIZE_MATCHING_T_DATA>);

/*
Send the write data 'val' for one write transfer.
- The function should be called after a write request is sent by 'axi_m_write_req'.
- For a write request with 'burst_len' number of transfers, this function
  should be called for 'burst_len' number of times to send all write data.
  - 'strb' acts as the byte-enable with each bit corresponds to a byte of the data.
  - 'last' should be set to 1 if and only if the current function call
    corresponds to the last transfer of the current write request.
*/
template <class T_ADDR, class T_DATA, class T_WSTRB>
void axi_m_write_data(AxiInterface<T_ADDR, T_DATA, T_WSTRB> &m,
                      T_DATA val, T_WSTRB strb, bool last);

/*
Receive the response acknowledgement for the last write request from the slave.
- The function should be called after all write data are sent by 'axi_m_write_data'.
- A return value of 0 means 'OK'; otherwise indicates an error.
*/
template <class T_ADDR, class T_DATA, class T_WSTRB>
ap_uint<2> axi_m_write_resp(AxiInterface<T_ADDR, T_DATA, T_WSTRB> &m);

The read and write operations are independent and therefore can be executed in parallel at the same time.

Same as the AXI4 slave interface, this AXI4 master interface library only supports the AXI4-lite protocol with additional support for bursting.

#include <hls/axi_interface.hpp>
#include <hls/ap_int.hpp>
#include <stdio.h>

using namespace hls;

void simple_master(AxiInterface<ap_uint<32>, ap_uint<64>, ap_uint<8>> &master) {
#pragma HLS function top
    ap_uint<9> remaining = AXIM_MAX_BURST_LEN;
    ap_uint<32> r_addr = 0;
    ap_uint<32> w_addr = AXIM_MAX_BURST_LEN * 8;

#pragma HLS loop pipeline
    for (; remaining != 0; --remaining) {
        bool is_last = remaining == 1;

        if (remaining == AXIM_MAX_BURST_LEN) {
            // Request to read data in burst.
            axi_m_read_req<ap_uint<32>, ap_uint<64>, ap_uint<8>>(
                master, r_addr, AXIM_MAX_BURST_LEN);

            // Request to write data in burst.
            axi_m_write_req<ap_uint<32>, ap_uint<64>, ap_uint<8>>(
                master, w_addr, AXIM_MAX_BURST_LEN);
        }

        // Write back the data we read + 1.
        ap_uint<64> data = axi_m_read_data<ap_uint<32>, ap_uint<64>>(master);
        axi_m_write_data<ap_uint<32>, ap_uint<64>, ap_uint<8>>(master, data + 1,
                                                               0xFF, is_last);
    }
    // After the last write, read the response code.
    ap_uint<2> bresp = axi_m_write_resp(master);
}

int main() {
    AxiInterface<ap_uint<32>, ap_uint<64>, ap_uint<8>> axi_if(
        AXIM_MAX_BURST_LEN);

    // Prepare the data to be read by the AXI master.
    for (int i = 0; i < AXIM_MAX_BURST_LEN; i++) {
        RdDataSignals<ap_uint<64>> r_sig;
        r_sig.data = i;
        r_sig.resp = 0;
        r_sig.last = i == AXIM_MAX_BURST_LEN - 1;
        axi_if.r.write(r_sig);
    }

    // Prepare the write response for the write from AXI master.
    WrRespSignals b_sig;
    axi_if.b.write(b_sig);

    // Run the top-level function that will be synthesize to hardware.
    simple_master(axi_if);

    bool failed = false;

    // Clear the write and read request.
    ap_uint<32> r_addr = axi_if.ar.read().addr;
    ap_uint<32> w_addr = axi_if.aw.read().addr;

    // Check that the read and write addresses were as expected.
    failed |= r_addr != 0;
    failed |= w_addr != AXIM_MAX_BURST_LEN * 8;

    // Read all of write data.
    for (int i = 0; i < AXIM_MAX_BURST_LEN; ++i) {
        // Check that write data is i + 1.
        failed |= axi_if.w.read().data != i + 1;
    }

    // Now that all FIFOs have been cleared, the AXI interface could be prepared
    // for more calls to the kernel..

    if (!failed)
        printf("PASS!\n");
    else
        printf("FAILED!\n");

    return failed;
}

For a pointer argument, the top-level driver functions will use 'memcpy' or DMA transfer functions based on the dma(<true|false>) option of the argument's interface pragma. If the option is not specified, the top-level driver functions will use 'memcpy' transfer by default.

SmartHLS™ determines the input and/or output direction for a pointer argument based on the read and write accesses of the pointer argument in the C++ implementation. That is,

• If the pointer argument is only being read in the C++ code, then the direction is input and the top-level driver functions will only transfer the data into the HLS module's corresponding buffer before starting the HLS module;

• If the pointer argument is write-only, then its direction is output and the top-level driver functions will only transfer the data back from the HLS module's corresponding buffer after the HLS module finishes execution;

• If the pointer argument is both read and written by the C++ code, then its direction is inout and data transfer happens before and after the HLS module execution.

However, there can be cases where the direction analysis is not accurate and requires user intervention to specify a requires_copy_in option in the interface pragma,

SmartHLS™ comes with a pre-built bitstream for PolarFire® SoC Icicle Kit and PolarFire Video Kit, containing a base SoC design. The base SoC design can be programmed to a board in order to cross-compile and test user software on Linux running on the board for the Icicle Kit, and baremetal for the MiV_RV32 on the PolarFire FPGA. . To program this base SoC, navigate to the SmartHLS tab, and select RISC-V SoC Features > Base SoC with no SoC Accelerators > Program board with prebuilt bitstream.

In the same sub-menu, there is an option to cross-compile the project software into a binary for RISC-V (Cross-compile software for RISC-V), as well as an option to move this binary to an attached Icicle Kit and run it (Run software without accelerators). In order to run software on an attached Icicle Kit, some preliminary setup steps are required, see Icicle Kit Setup Instructions.

SmartHLS™ is also capable of taking the hardware accelerators it generates, and integrating them with the Microprocessor Sub-System (MSS) on a PolarFire® SoC FPGA (currently only supports PolarFire SoC Icicle Kit to create a reference SoC design in SmartDesign. This is done by taking the base SoC project, adding hardware accelerators as SmartDesign HDL+ cores, and connecting the components using an AXI4 interconnect. To generate this reference SoC design, navigate to the SmartHLS tab, and select RISC-V SoC Features > Reference SoC with HLS Accelerator(s) > Generate Libero Design. For more information on the architecture of this reference SoC, see SmartHLS™ Reference SoC.

In the same sub-menu, there are also options to run synthesis and place and route for the reference SoC, which can be used to check timing and resource usage of each accelerator as well as the whole SoC. There are also options to generate a bitstream and program it to an attached Icicle Kit. Finally, the Run software with accelerators option combines the input software with the generated accelerator drivers, and creates a software binary that can run on Linux in the Icicle MSS and drive the SmartHLS™ accelerators on the fabric. In order to run software on an attached Icicle Kit, some preliminary steps are required, see Icicle Kit Setup Instructions. For an example on how to do this with the MiV_RV32 on the PolarFire® Video Kit, see PolarFire Video Kit Setup Instructions.

In general, when profiling an application there are overheads in the form of storage (for profiling timestamp samples) and runtime caused by timestamp acquisition. SmartHLS™ tries to minimize this by instantiating a simple 48-bit cycle counter in the FPGA fabric to read the timestamps from and store them in CPU memory. In this context a timestamp sample is the value read from the 48-bit cycle counter at a point in time. Obtaining a timestamp this way is as fast as a memory-mapped register read to the cycle counter and the timestamp samples do not use on-chip memory for storage. SmartHLS also automatically instruments the autogenerated driver API functions to read the timestamps. The figure below shows these three aspects of the profiler architecture: the storage, the instrumented software API driver and the cycle counter. In this case foo() and bar() are the functions to be profiled after being compiled to hardware modules.

The profiling process is very simple, it does not require the user to manually change the C++ code, just set a few configuration parameters for the profiler. The process has 3 steps:

1. Enable hardware counter and software driver API instrumentation
2. Run the application
3. Collect and visualize the results

The first step is to tell SmartHLS™ that we need the soc cycle counter hardware module to be instantiated as part of the SmartHLS subsystem and to instrument the API software driver to collect the timestamps. This is done by adding the following line in the config.tcl file.

set_parameter SOC_PROFILER_COUNTER 1

This is an example of the instrumented code added to the software API driver:

void foo_start() {
#ifdef HLS_PROFILER_ENABLE
    // Add the "start" event to the profiler
    foo_prof.timestamp_start();
#endif
    // Run accelerator
    ...
}

Note that the timestamp collection only happens if the HLS_PROFLIER_ENABLED constant is defined during the software compilation process. This flag can be defined in the Makefile (or Makefile.user for IDE projects) like this:

USER_CXX_FLAG+=-DHLS_PROFILER_ENABLE
USER_CXX_FLAG+=-DHLS_PROFILER_SAMPLES=500

HLS_PROFILER_SAMPLES is an optional software compile parameter used to specify the maximum number of samples to store - in this example we store up to 500 samples. If not specified the default value is set to 100 samples. If the hardware module runs for more than the maximum number of samples it will not cause a buffer overflow, the profiling would stop once the sample is full and some sample data would be lost. When this happens a warning message will be printed to the standard output suggesting to increase the sample buffer capacity.

After an application with profiling enabled completes its execution on the FPGA board, the profiler will generate one .prof file per top level module in the SmartHLS project, plus one more .prof file for the main() function. These files follow this naming convention: hls_<functionName>.prof. All the *.prof files must be copied from the board to the local host computer into the hls_output/files directory in order to analyze and visualize them. This copying will be done automatically if you use the shls command from the command-line or the SmartHLS GUI to launch/run the application on the board, otherwise, those files will have to be copied over manually.

The second step is to compile the hardware and software, and then run the application on the board to collect the results. You can do this in the SmartHLS™ IDE by selecting RISC-V SoC Features > Reference SoC with HLS Accelerator(s) > Run software with Accelerators; or from the command-line using the following command.

shls soc_accel_proj_run

This will go through RTL generation, synthesis, place and route, FPGA programming, compiling software and running the application on the board. After this you should see the .prof files under hls_output/files on the host machine.

After the FPGA has been configured, and assuming there are no changes to the hardware, you can change the software part, compile it and rerun the executable without having to reprogram the FPGA. In the IDE, you can click the same Run software with accelerators button as above, skip the hardware part (i.e. compile software to hardware, generate SoC, place-and-route, program board etc), and run the software part (transform C++ source to invoke accelerator, and cross-compile software with accelerator drivers). You can also explicitly click the Cross-compile software with accelerator drivers button, and then Run software with accelerators (and skip all steps). Alternatively, from command-line, you could just run:

shls soc_sw_compile_accel
shls run_on_board

This will regenerate and copy again the *.prof files from the board to the host machine and visualize the results as described in the next section.

Finally, the third step in the profiling process is to parse the generated .prof files and visualize them. This can be done from the IDE by clicking on RISC-V SoC Features > Reference SoC with HLS Accelerator(s) > Run SoC Profiler Viewer; or from the command-line, simply type:

shls soc_profiler_view

Project: soc_profiler

---------------------------------
Statistics (units in [us]):


--------[ main ]--------
main start      : 0.19 us
main finish     : 11747.38 us
main Delta Time : 11747.19 us

--------[ hw_const_add ]--------
Number of samples: 10
+-------------+-------+--------+-------+-----------+
|             | min   | max    | avg   | aggregate |
+-------------+-------+--------+-------+-----------+
| Write       | 50.76 | 208.28 | 69.08 | 690.76    |
| Accelerator | 5.42  | 6.62   | 5.59  | 55.94     |
| Total       |       |        |       | 746.7     |
+-------------+-------+--------+-------+-----------+

--------[ hw_const_mult ]--------
Number of samples: 10
+-------------+------+-------+-------+-----------+
|             | min  | max   | avg   | aggregate |
+-------------+------+-------+-------+-----------+
| Write       | 3.82 | 7.74  | 4.3   | 42.98     |
| Accelerator | 4.74 | 4.83  | 4.77  | 47.7      |
| Read        | 40.3 | 52.18 | 47.31 | 473.1     |
| Total       |      |       |       | 563.78    |
+-------------+------+-------+-------+-----------+

--------[ hw_delay ]--------
Number of samples: 100
+-------------+------+---------+------+-----------+
|             | min  | max     | avg  | aggregate |
+-------------+------+---------+------+-----------+
| Write       | 0.44 | 3.25    | 0.48 | 48.36     |
| Accelerator | 2.7  | 2000.96 | 22.7 | 2270.25   |
| Read        | 0.46 | 0.88    | 0.47 | 47.03     |
| Total       |      |         |      | 2365.64   |
+-------------+------+---------+------+-----------+

--------[ hw_sum ]--------
Number of samples: 10
+-------------+-------+-------+-------+-----------+
|             | min   | max   | avg   | aggregate |
+-------------+-------+-------+-------+-----------+
| Write       | 3.62  | 6.79  | 4.09  | 40.88     |
| Accelerator | 23.12 | 23.71 | 23.21 | 232.11    |
| Read        | 0.46  | 0.68  | 0.48  | 4.81      |
| Total       |       |       |       | 277.8     |
+-------------+-------+-------+-------+-----------+

In this context, the word Write refers to the time that the CPU spent writing data to the hardware module. The word Accelerator (or Acc in the plot below) refers to the time the hardware module was active. And finally, the word Read refers to the time that the CPU spent reading data from the hardware module's on-chip buffers. The command shls soc_profiler_view will also open up a GUI that shows a plot of the runtime. The GUI has a way to zoom-in to specific region of the plot. Also, the mouse pointer can hover over specific bar on the plot and the corresponding annotated data will be displayed.

By default, the plot will display the timelines for all the hardware modules in the project by including all the *.prof files in the plot. However, a single timeline for a specific hardware module can be displayed using the SOC_PROFILER_FILENAME makefile variable and assign to it the specific .prof file to visualize. For example, to display only the time line for the hardware module hw_const_sum() you can type this:

shls soc_profiler_view  SOC_PROFILER_FILENAME=./hls_output/files/hls_hw_const_sum.prof

Note the hls_ prefix in the filename. The plot will look like this:

In some cases, such as in automated regression tests, an interactive GUI is not required or not even desired. The profiler can be run in non-interactive mode like this:

shls soc_profiler_view SOC_PROFILER_INTERACTIVE=0

In this case the summary file is still generated and printed to the terminal but the GUI plot will not be displayed. Instead an image file with .png format will be generated under hls_output/reports/hls_soc_profiler.png. Note that this non-interactive option is only available from the command-line.

The RTL Interface section shows the interfaces used by the top-level module. Below is an example of the RTL interface report table:

+----------------------------------------------------------------------------------------------------------+
| RTL Interface Generated by SmartHLS                                                                      |
+-------------+--------------------+---------------------------------+------------------+------------------+
| C++ Name    | Interface Type     | Signal Name                     | Signal Bit-width | Signal Direction |
+-------------+--------------------+---------------------------------+------------------+------------------+
|             | Clock & Reset      | clk (positive edge)             | 1                | input            |
|             |                    | reset (synchronous active high) | 1                | input            |
+-------------+--------------------+---------------------------------+------------------+------------------+
|             | Control            | finish                          | 1                | output           |
|             |                    | ready                           | 1                | output           |
|             |                    | start                           | 1                | input            |
+-------------+--------------------+---------------------------------+------------------+------------------+
| input_fifo  | Input AXI4 Stream  | input_fifo_ready                | 1                | output           |
|             |                    | input_fifo_valid                | 1                | input            |
|             |                    | input_fifo                      | 8                | input            |
+-------------+--------------------+---------------------------------+------------------+------------------+

The table shows the interface for each top-level function argument (or global variable accessed by both the SW testbench and the top-level function - see Pointer Argument and Shared Global Variable).

• The first column of the table shows the C++ source name of the argument or global variable.
• The second column shows the interface types used for this argument or global variable.
• The last three columns list the names, bit-widths, and directions for all the signals that are included in the interface. For example, the AXI4 Stream interface has three signals in this case, input_fifo for the 8-bit data, with associated valid and ready signals.

Note that the Clock & Reset and the Control interfaces are the standard module control interfaces that are always used by any SmartHLS-generated module, and hence there is no C++ name attached to them.

For more details about the RTL interface, please refer to Top-Level RTL Interface.

The scheduling result section shows trip count, iteration time, total time, and initiation interval (II) for any pipelined or unpipelined loops, or functions. The loops are grouped under their parent function in a tree structure to show the hierarchy.

As example table is as follow:

      +---------------------------------------------------------------------------------------------------------+ 
      | Function: row_cumulative_sum takes 40804 cycles                                                         | 
      +---------------------------+--------------------+------------+-------------------+-------+---------------+ 
      | Loop                      | Location In Source | Trip Count | Iteration Latency | II    | Total Latency | 
      +---------------------------+--------------------+------------+-------------------+-------+---------------+ 
      | for.loop:main.cpp:7:5     | line 7 of main.cpp | 200        | 204               | undef | 40800         | 
      | |__ for.loop:main.cpp:9:9 | line 9 of main.cpp | 199        | 3                 | 1     | 201           | 
      +---------------------------+--------------------+------------+-------------------+-------+---------------+ 

SmartHLS™ Schedule Viewer also shows the same information.

The pipeline result section reports the initiation interval, pipeline length, iteration count, and latency for each pipelined loop or function.

+--------------------+---------------------+-------------+--------------------------------+---------------------+-----------------+-----------------+---------+
| Label              | Function            | Basic Block | Location in Source Code        | Initiation Interval | Pipeline Length | Iteration Count | Latency |
+--------------------+---------------------+-------------+--------------------------------+---------------------+-----------------+-----------------+---------+
| gaussian_loop      | gaussian_filter     | while_body  | line 63 of gaussian_filter.cpp | 1                   | 7               | n/a             | n/a     |
| loop_test_checker  | test_output_checker | for_body    | line 39 of test_util.cpp       | 1                   | 3               | 262144          | 262146  |
| loop_test_injector | test_input_injector | for_body    | line 19 of test_util.cpp       | 1                   | 2               | 262144          | 262145  |
+--------------------+---------------------+-------------+--------------------------------+---------------------+-----------------+-----------------+---------+

The iteration count and latency may not be available for a pipelined function or a pipelined loop with non-deterministic loop bound. Please refer to Loop Pipelining and Function Pipelining for more details. SmartHLS's Schedule Viewer also gives more details about how individual instructions are scheduled inside each pipeline.

The memory usage section lists the memories used by the generated circuit, grouped by the type of memory architecture. Please refer to Memory Architecture section for more details about the memory architecture used by SmartHLS™.

+-------------------------------------------------------------------------------------------------------------------------+
| Local Constant Memories                                                                                                 |
+-------+--------------------------------------------------------+------+-------------+------------+-------+--------------+
| Name  | Accessing Function(s)                                  | Type | Size [Bits] | Data Width | Depth | Read Latency |
+-------+--------------------------------------------------------+------+-------------+------------+-------+--------------+
| gauss | blackscholes_hw (concurrent access through an arbiter) | ROM  | 8192        | 32         | 256   | 1            |
+-------+--------------------------------------------------------+------+-------------+------------+-------+--------------+

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Shared Local Memories                                                                                                                                               |
+-------------+-------------------------------------------------------------------------------------+---------------+-------------+------------+-------+--------------+
| Name        | Accessing Function(s)                                                               | Type          | Size [Bits] | Data Width | Depth | Read Latency |
+-------------+-------------------------------------------------------------------------------------+---------------+-------------+------------+-------+--------------+
| bdata_0     | blackscholes_hw, option_pricing (concurrent access through an arbiter)              | Register      | 32          | 32         | 1     | 0            |
| bdata_1     | blackscholes_hw, option_pricing (concurrent access through an arbiter)              | Register      | 32          | 32         | 1     | 0            |
| idata_0     | mersenne_twister_init_hw, option_pricing (concurrent access through an arbiter)     | Register      | 1           | 1          | 1     | 0            |
| idata_1     | mersenne_twister_init_hw, option_pricing (concurrent access through an arbiter)     | Register      | 32          | 32         | 1     | 0            |
| init_fifo   | mersenne_twister_generate_hw, mersenne_twister_init_hw                              | FIFO (LUTRAM) | 64          | 32         | 2     | 1            |
| random_fifo | blackscholes_hw, mersenne_twister_generate_hw                                       | FIFO (LUTRAM) | 64          | 32         | 2     | 1            |
| tdata_0     | mersenne_twister_generate_hw, option_pricing (concurrent access through an arbiter) | Register      | 32          | 32         | 1     | 0            |
| tdata_1     | mersenne_twister_generate_hw, option_pricing (concurrent access through an arbiter) | Register      | 32          | 32         | 1     | 0            |
+-------------+-------------------------------------------------------------------------------------+---------------+-------------+------------+-------+--------------+

+-------------------------------------------------------------------------------------------------------------------------------+
| Aliased Memories                                                                                                              |
+------------------------+---------------------+-----------------------+------+-------------+------------+-------+--------------+
| Name                   | Memory Controller   | Accessing Function(s) | Type | Size [Bits] | Data Width | Depth | Read Latency |
+------------------------+---------------------+-----------------------+------+-------------+------------+-------+--------------+
| foo_entry_local_array1 | memory_controller_0 | foo, foo_sub          | RAM  | 160         | 32         | 5     | 1            |
| foo_entry_local_array2 | memory_controller_0 | foo, foo_sub          | RAM  | 160         | 32         | 5     | 1            |
+------------------------+---------------------+-----------------------+------+-------------+------------+-------+--------------+

+---------------------------------------------------------------------------------------------------------+
| I/O Memories                                                                                            |
+--------+-----------------------+----------------------+-------------+------------+-------+--------------+
| Name   | Accessing Function(s) | Type                 | Size [Bits] | Data Width | Depth | Read Latency |
+--------+-----------------------+----------------------+-------------+------------+-------+--------------+
| rd_arr | kernel                | ROM                  | undef       | 16         | undef | 1            |
| rd_reg | kernel                | Register (Read-Only) | undef       | 16         | undef | 0            |
| wr_arr | kernel                | RAM                  | undef       | 16         | undef | 1            |
| wr_reg | kernel                | Register             | undef       | 16         | undef | 0            |
+--------+-----------------------+----------------------+-------------+------------+-------+--------------+

The example tables above show the accessing functions and the hardware implementation of each "memory" in the software.

• The Type column shows how a memory is implemented in hardware, which could be in RAM, ROM (read-only), register or FIFO (only applicable to hls::FIFO type variables in C++).
• The Size column reports the total size of the memory in bits, equals to Data Width * Depth.
• The Data Width refers to the bit-width of the data ports of a RAM/FIFO, or the bit-width of a register.
• The Depth field represents the depth of a RAM or FIFO, and it is always 1 for register.
• Aliased Memories have an additional column showing the name of the Memory Controller of which the memory is being placed behind. So you can see which memories are aliasing and being put behind the same memory controller to support aliased memory accesses.
• I/O Memories have Size and Depth to be undef. This is because I/O interface memories are not instantiated inside the SmartHLS-generated circuit.

This section shows the memory-mapped address offsets, sizes, and directions of all AXI4 Target interfaces. We will use the same example as in the AXI4 Initiator/Target Interface in the RTL Interface Report section to demonstrate:

#define SIZE 16

int top(int *arg1, int *arg2, int *arg3) {
#pragma HLS function top
#pragma HLS interface control          type(axi_target)
#pragma HLS interface argument(arg1)   type(axi_initiator) ptr_addr_interface(axi_target) num_elements(SIZE)
#pragma HLS interface argument(arg2)   type(axi_initiator) ptr_addr_interface(simple)     num_elements(SIZE)
#pragma HLS interface argument(arg3)   type(axi_target)                                   num_elements(SIZE)
    ...
}

====== 5. AXI4 Target Interface Address Map ======

Compatibility of HLS accelerator with reference SoC features: No.
SoC feature is only supported for PolarFire SoC Icicle Kit, and all accelerator interfaces need to be either axi_target or axi_initiator:
  - The interfaces of the following argument(s), global variable(s), and/or module control are not axi_target or axi_initiator:
    arg2 (pointer address interface).

+-----------------------------------------------------------------------------+
| Accelerator Function: top (Address Space Range: 0x80)                       |
+---------------------------------+----------------+--------------+-----------+
| Argument                        | Address Offset | Size [Bytes] | Direction |
+---------------------------------+----------------+--------------+-----------+
| Return Value                    | 0x00           | 8            | output    |
| Module Control                  | 0x08           | 4            | inout     |
| arg1 (pointer address register) | 0x10           | 4            | input**   |
| arg3                            | 0x40           | 64*          | output    |
+---------------------------------+----------------+--------------+-----------+

* On PolarFire SoC devices, it is recommended to use the PDMA engine for data transfer when the transfer size is bigger than 16KB, and use the memcpy driver functions when the transfer size is smaller than 16KB.
See memcpy and dma transfer driver functions in hls_output/accelerator_drivers/vector_add_soc_accelerator_driver.[h|cpp]

** The base pointer address of axi_initiator interface argument is an input to the accelerator. The actual direction of the argument can be different, depending on the read/write accesses through the pointer (or array/struct) argument in the C++ implementation.

Firstly, this section prints whether the top-level module is compatible with the SmartHLS-generated reference SoC (see SoC Features). For a top-level module to be compatible and thus can be integrated into the reference SoC, it needs to satisfy the following conditions:

• The project has to be an Icicle_SoC project.
• All interfaces of the top-level has to be either type(axi_target), or type(axi_initiator) ptr_addr_interface(axi_target). This includes the module control. This section will print out all the SoC incompatible interfaces. In this example, since arg2 has a simple pointer address interface, it is incompatible with the reference SoC.

If all interfaces are SoC-compatible, the report will print the default base address of the top-level module in the reference SoC instead e.g.

====== 5. AXI4 Target Interface Address Map ======

Compatibility of HLS accelerator with reference SoC features: Yes.
Default base address in reference SoC: 0x70000000.

Secondly, this section prints the table containing the memory-mapped address offset, size, and direction of all arguments using AXI4 Target.

• In this example, since top() has an int return type which is non-void, the table will show a row for Return Value, which is always at offset 0x0, of size 8, and with output direction. For top-level functions that have void return type, there will be no Return Value row in the table.
• Since the Module Control uses AXI4 Target, there will be a row for Module Control which is always at offset 0x8 (regardless of whether the return type is void or not), of size 4, and with inout direction. For top-level functions that have simple module control, there will be no Module Control row in the table.
• arg1 is type(axi_initiator) ptr_addr_interface(axi_target), so there will be a row for the AXI4 Target pointer address register.
• arg2 is type(axi_initiator) ptr_addr_interface(simple), so there will NOT be a row for it in this table because it doesn't use AXI4 Target pointer address register.
• arg3 is type(axi_target) so there will be a row for the corresponding register/on-chip buffer.
• Any arguments with other interface types will not appear in this table since they do not use AXI4 Target.