TransferBench API library

Contents

TransferBench API library#

struct ConfigOptions#
#include <TransferBench.hpp>

Configuration options for performing Transfers

Public Members

GeneralOptions general#

General options.

DataOptions data#

Data options.

GfxOptions gfx#

GFX executor options.

DmaOptions dma#

DMA executor options.

struct DataOptions#
#include <TransferBench.hpp>

Data options

Public Members

int alwaysValidate = 0#

Validate after each iteration instead of once at end.

int blockBytes = 256#

Each subexecutor works on a multiple of this many bytes.

int byteOffset = 0#

Byte-offset for memory allocations.

vector<float> fillPattern = {}#

Pattern of floats used to fill source data.

int validateDirect = 0#

Validate GPU results directly instead of copying to host.

int validateSource = 0#

Validate src GPU memory immediately after preparation.

struct DmaOptions#
#include <TransferBench.hpp>

DMA Executor options

Public Members

int useHipEvents = 1#

Use HIP events for timing DMA Executor.

int useHsaCopy = 0#

Use HSA copy instead of HIP copy to perform DMA.

struct ErrResult#
#include <TransferBench.hpp>

ErrResult consists of error type and error message

Public Functions

ErrResult() = default#
ErrResult(hipError_t err)#
ErrResult(hsa_status_t err)#
ErrResult(ErrType err)#
ErrResult(ErrType errType, const char *format, ...)#

Public Members

ErrType errType#

Error type.

std::string errMsg#

Error details.

struct ExeDevice#
#include <TransferBench.hpp>

A ExeDevice defines a specific Executor

Public Functions

inline bool operator<(ExeDevice const &other) const#

Public Members

ExeType exeType#

Executor type.

int32_t exeIndex#

Executor index.

struct ExeResult#
#include <TransferBench.hpp>

Results for a single Executor

Public Members

size_t numBytes#

Total bytes transferred by this Executor.

double avgDurationMsec#

Averaged duration for all the Transfers for this Executor.

double avgBandwidthGbPerSec#

Average bandwidth for this Executor.

double sumBandwidthGbPerSec#

Naive sum of individual Transfer average bandwidths.

vector<int> transferIdx#

Indicies of Transfers this Executor executed.

struct GeneralOptions#
#include <TransferBench.hpp>

General options

Public Members

int numIterations = 10#

Number of timed iterations to perform. If negative, run for -numIterations seconds instead.

int numSubIterations = 1#

Number of sub-iterations per iteration.

int numWarmups = 3#

Number of un-timed warmup iterations to perform.

int recordPerIteration = 0#

Record per-iteration timing information.

int useInteractive = 0#

Pause for user-input before starting transfer loop.

struct GfxOptions#
#include <TransferBench.hpp>

GFX Executor options

Public Members

int blockSize = 256#

Size of each threadblock (must be multiple of 64)

vector<uint32_t> cuMask = {}#

Bit-vector representing the CU mask.

vector<vector<int>> prefXccTable = {}#

2D table with preferred XCD to use for a specific [src][dst] GPU device

int unrollFactor = 4#

GFX-kernel unroll factor.

int useHipEvents = 1#

Use HIP events for timing GFX Executor.

int useMultiStream = 0#

Use multiple streams for GFX.

int useSingleTeam = 0#

Team all subExecutors across the data array.

int waveOrder = 0#

GFX-kernel wavefront ordering.

struct MemDevice#
#include <TransferBench.hpp>

A MemDevice indicates a memory type on a specific device

Public Functions

inline bool operator<(MemDevice const &other) const#

Public Members

MemType memType#

Memory type.

int32_t memIndex#

Device index.

struct TestResults#
#include <TransferBench.hpp>

TestResults contain timing results for a set of Transfers as a group as well as per Executor and per Transfer timing information

Public Members

int numTimedIterations#

Number of iterations executed.

size_t totalBytesTransferred#

Total bytes transferred per iteration.

double avgTotalDurationMsec#

Wall-time (msec) to finish all Transfers (averaged across all timed iterations)

double avgTotalBandwidthGbPerSec#

Bandwidth based on all Transfers and average wall time.

double overheadMsec#

Difference between total wall time and slowest executor.

map<ExeDevice, ExeResult> exeResults#

Per Executor results.

vector<TransferResult> tfrResults#

Per Transfer results.

vector<ErrResult> errResults#

List of any errors/warnings that occurred.

struct Transfer#
#include <TransferBench.hpp>

A Transfer adds together data from zero or more sources then writes the sum to zero or more desintations

Public Members

size_t numBytes = (1 << 26)#

Number of bytes to Transfer.

vector<MemDevice> srcs = {}#

List of source memory devices.

vector<MemDevice> dsts = {}#

List of destination memory devices.

ExeDevice exeDevice = {}#

Executor to use.

int32_t exeDstIndex = -1#

Destination executor index (for RDMA executor only)

int32_t exeSubIndex = -1#

Executor subindex.

int numSubExecs = 0#

Number of subExecutors to use for this Transfer.

struct TransferResult#
#include <TransferBench.hpp>

Results for a single Transfer

Public Members

size_t numBytes#

Number of bytes transferred by this Transfer.

double avgDurationMsec#

Duration for this Transfer, averaged over all timed iterations.

double avgBandwidthGbPerSec#

Bandwidth for this Transfer based on averaged duration.

vector<double> perIterMsec#

Duration for each individual iteration.

vector<set<pair<int, int>>> perIterCUs#

GFX-Executor only. XCC:CU used per iteration.

namespace std#

STL namespace.

namespace TransferBench#

Enums

enum ExeType#

Enumeration of supported Executor types

Note

The Executor is the device used to perform a Transfer

Note

IBVerbs executor is currently not implemented yet

Values:

enumerator EXE_CPU#

CPU executor (subExecutor = CPU thread)

enumerator EXE_GPU_GFX#

GPU kernel-based executor (subExecutor = threadblock/CU)

enumerator EXE_GPU_DMA#

GPU SDMA executor (subExecutor = not supported)

enumerator EXE_IBV#

IBVerbs executor (subExecutor = queue pair)

enum MemType#

Enumeration of supported memory types

Note

These are possible types of memory to be used as sources/destinations

Values:

enumerator MEM_CPU#

Coarse-grained pinned CPU memory.

enumerator MEM_GPU#

Coarse-grained global GPU memory.

enumerator MEM_CPU_FINE#

Fine-grained pinned CPU memory.

enumerator MEM_GPU_FINE#

Fine-grained global GPU memory.

enumerator MEM_CPU_UNPINNED#

Unpinned CPU memory.

enumerator MEM_NULL#

NULL memory - used for empty.

enumerator MEM_MANAGED#

Managed memory.

enum ErrType#

Enumeration of possible error types

Values:

enumerator ERR_NONE#

No errors.

enumerator ERR_WARN#

Warning - results may not be accurate.

enumerator ERR_FATAL#

Fatal error - results are invalid.

enum IntAttribute#

Enumeration of implementation attributes

Values:

enumerator ATR_GFX_MAX_BLOCKSIZE#

Maximum blocksize for GFX executor.

enumerator ATR_GFX_MAX_UNROLL#

Maximum unroll factor for GFX executor.

enum StrAttribute#

Values:

enumerator ATR_SRC_PREP_DESCRIPTION#

Description of how source memory is prepared.

Functions

inline bool IsCpuExeType(ExeType e)#
inline bool IsGpuExeType(ExeType e)#
inline bool IsCpuMemType(MemType m)#
inline bool IsGpuMemType(MemType m)#
bool RunTransfers(ConfigOptions const &config, vector<Transfer> const &transfers, TestResults &results)#

Run a set of Transfers

Parameters:
  • config[in] Configuration options

  • transfers[in] Set of Transfers to execute

  • results[out] Timing results

Returns:

true if and only if Transfers were run successfully without any fatal errors

int GetIntAttribute(IntAttribute attribute)#

Query attributes (integer)

Note

This allows querying of implementation information such as limits

Parameters:

attribute[in] Attribute to query

Returns:

Value of the attribute

std::string GetStrAttribute(StrAttribute attribute)#

Query attributes (string)

Note

This allows query of implementation details such as limits

Parameters:

attrtibute[in] Attribute to query

Returns:

Value of the attribute

int GetNumExecutors(ExeType exeType)#

Returns information about number of available available Executors

Parameters:

exeType[in] Executor type to query

Returns:

Number of detected Executors of exeType

int GetNumExecutorSubIndices(ExeDevice exeDevice)#

Returns the number of possible Executor subindices

Note

For CPU, this is 0

Note

For GFX, this refers to the number of XCDs

Note

For DMA, this refers to the number of DMA engines

Parameters:

exeDevice[in] The specific Executor to query

Returns:

Number of detected executor subindices

int GetNumSubExecutors(ExeDevice exeDevice)#

Returns number of subExecutors for a given ExeDevice

Parameters:

exeDevice[in] The specific Executor to query

Returns:

Number of detected subExecutors for the given ExePair

int GetClosestCpuNumaToGpu(int gpuIndex)#

Returns the index of the NUMA node closest to the given GPU

Parameters:

gpuIndex[in] Index of the GPU to query

Returns:

NUMA node index closest to GPU gpuIndex, or -1 if unable to detect

ErrResult ParseTransfers(std::string str, std::vector<Transfer> &transfers)#

Helper function to parse a line containing Transfers into a vector of Transfers

Parameters:
  • str[in] String containing description of Transfers

  • transfers[out] List of Transfers described by ‘str’

Returns:

Information about any error that may have occured

Variables

constexpr char VERSION[] = "1.58"#
char const ExeTypeStr[5] = "CGDI"#
char const MemTypeStr[8] = "CGBFUNM"#
file TransferBench.hpp

Defines

GetHwId(hwId)#
GetXccId(val)#
ERR_CHECK(cmd)#
ERR_APPEND(cmd, list)#
dir /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-transferbench/checkouts/latest/src/header
dir /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-transferbench/checkouts/latest/src