API Class of xf::common::utils_hw

template class xf::common::utils_hw::UramArray

#include "xf_utils_hw/uram_array.hpp"

Overview

Helper class to create URAM array that can be updated every cycle with forwarding regs.

Forwarding regs keeps a history of address and values, and when acess to URAM hits the “cache”, read from URAM is skipped. This addresses the Read-After-Write dependency across iterations. The depth of the cache, specified with the _NCache variable, dependes on the latency of actual write. It is suggested to be set after initial sythesis attempts.

When element can be held in one URAM row (72-bit), this helper would try to pack multiple elements to one row. If it is beyond 72-bits, multiple URAMs will be used to ensure elements can be fetched in one cycle.

To make the cache really functional, HLS needs to be instructed to ignore inter-iteration dependencies on blocks of UramArray objects. Please refer to the test of this module for an example.

Attention

This module requires HLS 2019.1 or above.

Parameters:

_WData the width of every element.
_NData the number of elements in the array.
_NCache the number of cache.
template <
    int _WData,
    int _NData,
    int _NCache
    >
class UramArray

// fields

ap_uint <72>* blocks[details::need_num< _WData, _NData >::value_x][details::need_num< _WData, _NData >::value_y]

Methods

memSet

int memSet (const ap_uint <_WData>& d)

initialization for uram.

Parameters:

d value for initialization.

Returns:

number of block which had been initialize.

write

void write (
    int index,
    const ap_uint <_WData>& d
    )

write to uram.

Parameters:

index the index which you want to write.
d the value what you want to write.

read

ap_uint <_WData> read (int index)

read from uram.

Parameters:

index the index which you want to read.

Returns:

value you had read.

template class xf::common::utils_hw::cache

#include "cache.hpp"

Overview

cache is a URAM design for caching Read-only DDR/HBM memory spaces

This function stores history data recently loaded from DDR/HBM in the on-chip memory(URAM). It aims to reduce DDR/HBM access when the memory is accessed randomly.

Parameters:

T The type of the actual data accessed. Float and double is not supported.
ramRow The number of rows each on chip ram has
groupramPart The number of on chip ram used in cache
dataOneLine The number of actual data each 512 can contain
addrWidth The width of the address to access the memory
validRamType The ram type of the valid flag array. 0 for LUTRAM, 1 for BRAM, 2 for URAM
addrRamType The ram type of the onchip addr array. 0 for LUTRAM, 1 for BRAM, 2 for URAM
dataRamType The ram type of the onchip data array. 0 for LUTRAM, 1 for BRAM, 2 for URAM
template <
    typename T,
    int ramRow,
    int groupRamPart,
    int dataOneLine,
    int addrWidth,
    int validRamType,
    int addrRamType,
    int dataRamType
    >
class cache

Methods

initSingleOffChip

void initSingleOffChip ()

Initialization of the on chip memory when controlling single off chip memory.

initDualOffChip

void initDualOffChip ()

Initialization of the on chip memory when controlling dual off chip memory.

readOnly

readOnly overload (1)
void readOnly (
    ap_uint <512>* ddrMem,
    hls::stream <ap_uint <32>>& addrStrm,
    hls::stream <bool>& e_addrStrm,
    hls::stream <T>& dataStrm,
    hls::stream <bool>& e_dataStrm
    )

readOnly function with end flags.

Parameters:

ddrMem The pointer for the off chip memory
addrStrm The read address should be sent from this stream
e_addrStrm The end flag for the addrStrm
dataStrm The data loaded from off chip memory
e_dataStrm The end flag for the dataStrm
readOnly overload (2)
void readOnly (
    int cnt,
    ap_uint <512>* ddrMem,
    hls::stream <ap_uint <32>>& addrStrm,
    hls::stream <T>& dataStrm
    )

readOnly function without end flags.

Parameters:

cnt The number of access to the memory
ddrMem The pointer for the off chip memory
addrStrm The read address should be sent from this stream
dataStrm The data loaded from off chip memory
readOnly overload (3)
void readOnly (
    int cnt,
    ap_uint <512>* ddrMem0,
    ap_uint <512>* ddrMem1,
    hls::stream <ap_uint <32>>& addrStrm,
    hls::stream <T>& data0Strm,
    hls::stream <T>& data1Strm
    )

readOnly function that index two off-chip buffers without end flags. Both of the buffers should be indexed in exactly the same behaviour.

Parameters:

cnt The number of access to the memory
ddrMem0 The pointer for the first off chip memory
ddrMem1 The pointer for the second off chip memory
addrStrm The read address should be sent from this stream
data0Strm The data loaded from the first off chip memory
data1Strm The data loaded from the second off chip memory
readOnly overload (4)
void readOnly (
    ap_uint <512>* ddrMem0,
    ap_uint <512>* ddrMem1,
    hls::stream <ap_uint <32>>& addrStrm,
    hls::stream <bool>& e_addrStrm,
    hls::stream <T>& data0Strm,
    hls::stream <bool>& e_data0Strm,
    hls::stream <T>& data1Strm,
    hls::stream <bool>& e_data1Strm
    )

readOnly function that index two off-chip buffers without end flags. Both of the buffers should be indexed in exactly the same behaviour.

Parameters:

ddrMem0 The pointer for the first off chip memory
ddrMem1 The pointer for the second off chip memory
addrStrm The read address should be sent from this stream
e_addrStrm The end flag for the addrStrm
data0Strm The data loaded from the first off chip memory
e_data0Strm The end flag for the data0Strm
data1Strm The data loaded from the second off chip memory
e_data1Strm The end flag for the data1Strm

template class xf::common::utils_hw::Multiplexer

#include "xf_utils_hw/multiplexer.hpp"

Overview

Multiplexer is a wrapper around FIFO for sending/receiving data of different types.

Parameters:

S specifies this wrapper is on which side of the FIFO.
W specifies the width of the FIFO.
template <
    MuxSide S,
    int W
    >
class Multiplexer

Methods

get

get overload (1)
template <typename T>
T get ()

get

Parameters:

T type to receive

Returns:

one value

get overload (2)
template <typename T>
void get (T& d)

get

Parameters:

T type to receive

Returns:

one value

put

template <typename T>
void put (const T& d)

put

Parameters:

T type of data to send
d data to send

API Class of xf::common::utils_sw

class xf::common::utils_sw::ArgParser

#include "arg_parser.hpp"

Overview

// structs

template <typename T>
struct type

Methods

addFlag

void addFlag (
    const std::string opt,
    const std::string opt_full,
    const std::string info
    )

add an boolean flag. The default value is always ‘false’.

Parameters:

opt the short opt name, must start with “-“, or being “” if not used.
opt_full the full opt name, must start with “–”, pass “” if not used.
info the info to be shown in usage.

addOption

void addOption (
    const std::string opt,
    const std::string opt_full,
    const std::string info,
    const std::string def,
    bool required = false
    )

add an option with value.

Parameters:

opt the short opt name, must start with “-“.
opt_full the full opt name, must start with “–”, pass “” if not used.
info the info to be shown in usage.
def the default value string.
required if an option is required, program with exit upon failure of obtaining value, otherwise default value will be provide.

getAs

template <typename T>
T getAs (const std::string name) const

get value of option by name without leading dash. Either short or long option name can be used. Example: p.getAs<int>(“longopt”);

showUsage

void showUsage () const

print usage to stdout.