XRT Native Library C++ API

Buffer APIs

Configuration APIs

Custom IP APIs

Device APIs

Info APIs

Kernel APIs

Message APIs

System APIs

UUID APIs

XCLBIN APIs

XRT Native Library C API

Buffer APIs

typedef xrtDeviceHandle

opaque device handle

typedef xrtBufferHandle

opaque buffer handle

typedef xrtBufferFlags

flags for BO

Description

See xrt_mem.h for available flags

typedef xrtMemoryGroup

Memory bank group for buffer

XCL_DRIVER_DLLESPEC xrtBufferHandle xrtBOAllocUserPtr(xrtDeviceHandle dhdl, void * userptr, size_t size, xrtBufferFlags flags, xrtMemoryGroup grp)

Allocate a BO using userptr provided by the user

Parameters

xrtDeviceHandle dhdl
Device handle
void * userptr
Pointer to 4K aligned user memory
size_t size
Size of buffer
xrtBufferFlags flags
Specify type of buffer
xrtMemoryGroup grp
Specify bank information

Return

xrtBufferHandle on success or NULL

XCL_DRIVER_DLLESPEC xrtBufferHandle xrtBOAlloc(xrtDeviceHandle dhdl, size_t size, xrtBufferFlags flags, xrtMemoryGroup grp)

Allocate a BO of requested size with appropriate flags

Parameters

xrtDeviceHandle dhdl
Device handle
size_t size
Size of buffer
xrtBufferFlags flags
Specify type of buffer
xrtMemoryGroup grp
Specify bank information

Return

xrtBufferHandle on success or NULL

XCL_DRIVER_DLLESPEC xrtBufferHandle xrtBOImport(xrtDeviceHandle dhdl, xclBufferExportHandle ehdl)

Allocate a BO imported from another device

Parameters

xrtDeviceHandle dhdl
Device that imports the exported buffer
xclBufferExportHandle ehdl
Exported buffer handle, implementation specific type

Description

The exported buffer handle is acquired by using the export() method and can be passed to another process.

XCL_DRIVER_DLLESPEC xclBufferExportHandle xrtBOExport(xrtBufferHandle bhdl)

Export this buffer

Parameters

xrtBufferHandle bhdl
Buffer handle

Return

Exported buffer handle

An exported buffer can be imported on another device by this process or another process.

XCL_DRIVER_DLLESPEC xrtBufferHandle xrtBOSubAlloc(xrtBufferHandle parent, size_t size, size_t offset)

Allocate a sub buffer from a parent buffer

Parameters

xrtBufferHandle parent
Parent buffer handle
size_t size
Size of sub buffer
size_t offset
Offset into parent buffer

Return

xrtBufferHandle on success or NULL

XCL_DRIVER_DLLESPEC int xrtBOFree(xrtBufferHandle bhdl)

Free a previously allocated BO

Parameters

xrtBufferHandle bhdl
Buffer handle

Return

0 on success, or err code on error

XCL_DRIVER_DLLESPEC size_t xrtBOSize(xrtBufferHandle bhdl)

Get the size of this buffer

Parameters

xrtBufferHandle bhdl
Buffer handle

Return

Size of buffer in bytes

XCL_DRIVER_DLLESPEC uint64_t xrtBOAddress(xrtBufferHandle bhdl)

Get the physical address of this buffer

Parameters

xrtBufferHandle bhdl
Buffer handle

Return

Device address of this BO, or LLONG_MAX on error

XCL_DRIVER_DLLESPEC int xrtBOSync(xrtBufferHandle bhdl, enum xclBOSyncDirection dir, size_t size, size_t offset)

Synchronize buffer contents in requested direction

Parameters

xrtBufferHandle bhdl
Bufferhandle
enum xclBOSyncDirection dir
To device or from device
size_t size
Size of data to synchronize
size_t offset
Offset within the BO

Return

0 on success or error

Synchronize the buffer contents between host and device. Depending on the memory model this may require DMA to/from device or CPU cache flushing/invalidation

XCL_DRIVER_DLLESPEC void* xrtBOMap(xrtBufferHandle bhdl)

Memory map BO into user’s address space

Parameters

xrtBufferHandle bhdl
Buffer handle

Return

Memory mapped buffer, or NULL on error

Map the contents of the buffer object into host memory. The buffer object is unmapped when freed.

XCL_DRIVER_DLLESPEC int xrtBOWrite(xrtBufferHandle bhdl, const void * src, size_t size, size_t seek)

Copy-in user data to host backing storage of BO

Parameters

xrtBufferHandle bhdl
Buffer handle
const void * src
Source data pointer
size_t size
Size of data to copy
size_t seek
Offset within the BO

Return

0 on success or appropriate error number

Copy host buffer contents to previously allocated device memory. seek specifies how many bytes to skip at the beginning of the BO before copying-in size bytes of host buffer.

XCL_DRIVER_DLLESPEC int xrtBORead(xrtBufferHandle bhdl, void * dst, size_t size, size_t skip)

Copy-out user data from host backing storage of BO

Parameters

xrtBufferHandle bhdl
Buffer handle
void * dst
Destination data pointer
size_t size
Size of data to copy
size_t skip
Offset within the BO

Return

0 on success or appropriate error number

Copy contents of previously allocated device memory to host buffer. skip specifies how many bytes to skip from the beginning of the BO before copying-out size bytes of device buffer.

XCL_DRIVER_DLLESPEC int xrtBOCopy(xrtBufferHandle dst, xrtBufferHandle src, size_t sz, size_t dst_offset, size_t src_offset)

Deep copy BO content from another buffer

Parameters

xrtBufferHandle dst
Destination BO to copy to
xrtBufferHandle src
Source BO to copy from
size_t sz
Size of data to copy
size_t dst_offset
Offset into destination buffer to copy to
size_t src_offset
Offset into src buffer to copy from

Return

0 on success or appropriate error number

It is an error if sz is 0 bytes or sz + src/dst_offset is out of bounds.

Configuration APIs

XCL_DRIVER_DLLESPEC int xrtIniStringSet(const char * key, const char * value)

Change xrt.ini string value for specified key

Parameters

const char * key
Key to change value for
const char * value
New value for key

Return

0 on success, error if key value cannot be changed

XCL_DRIVER_DLLESPEC int xrtIniUintSet(const char * key, unsigned int value)

Change xrt.ini unsigned int value for specified key

Parameters

const char * key
Key to change value for
unsigned int value
New value for key

Return

0 on success, error if key value cannot be changed

Device and XCLBIN APIs

typedef xrtDeviceHandle

opaque device handle

XCL_DRIVER_DLLESPEC xrtDeviceHandle xrtDeviceOpen(unsigned int index)

Open a device and obtain its handle

Parameters

unsigned int index
Device index

Return

Handle representing the opened device, or nullptr on error

XCL_DRIVER_DLLESPEC xrtDeviceHandle xrtDeviceOpenByBDF(const char * bdf)

Open a device and obtain its handle

Parameters

const char * bdf
PCIe BDF identifying the device to open

Return

Handle representing the opened device, or nullptr on error

XCL_DRIVER_DLLESPEC xrtDeviceHandle xrtDeviceOpenFromXcl(xclDeviceHandle xhdl)

Open a device from a shim xclDeviceHandle

Parameters

xclDeviceHandle xhdl
Shim xclDeviceHandle

Return

Handle representing the opened device, or nullptr on error

The returned XRT device handle must be explicitly closed when nolonger needed.

XCL_DRIVER_DLLESPEC int xrtDeviceClose(xrtDeviceHandle dhdl)

Close an opened device

Parameters

xrtDeviceHandle dhdl
Handle to device previously opened with xrtDeviceOpen

Return

0 on success, error otherwise

XCL_DRIVER_DLLESPEC int xrtDeviceLoadXclbin(xrtDeviceHandle dhdl, const struct axlf * xclbin)

Load an xclbin image

Parameters

xrtDeviceHandle dhdl
Handle to device previously opened with xrtDeviceOpen
const struct axlf * xclbin
Pointer to complete axlf in memory image

Return

0 on success, error otherwise

The xclbin image can safely be deleted after calling this funciton.

XCL_DRIVER_DLLESPEC int xrtDeviceLoadXclbinFile(xrtDeviceHandle dhdl, const char * xclbin_fnm)

Read and load an xclbin file

Parameters

xrtDeviceHandle dhdl
Handle to device previously opened with xrtDeviceOpen
const char * xclbin_fnm
Full path to xclbin file

Return

0 on success, error otherwise

This function read the file from disk and loads the xclbin. Using this function allows one time allocation of data that needs to be kept in memory.

XCL_DRIVER_DLLESPEC int xrtDeviceLoadXclbinHandle(xrtDeviceHandle dhdl, xrtXclbinHandle xhdl)

load an xclbin from an xrt::xclbin handle

Parameters

xrtDeviceHandle dhdl
Handle to device previously opened with xrtDeviceOpen
xrtXclbinHandle xhdl
xrt::xclbin handle

Return

0 on success, error otherwise

This function uses the specified xrt::xclbin object created by caller. The xrt::xclbin object must contain the complete axlf structure.

XCL_DRIVER_DLLESPEC int xrtDeviceLoadXclbinUUID(xrtDeviceHandle dhdl, const xuid_t uuid)

load an xclbin from an xrt::xclbin handle

Parameters

xrtDeviceHandle dhdl
Handle to device previously opened with xrtDeviceOpen
const xuid_t uuid
uuid_t struct of xclbin id

Return

0 on success, error otherwise

This function reads the xclbin id already loaded in the system and comapres it with the input uuid. If they match, load the cached xclbin metadata into caller’s process. Otherwise returns error.

XCL_DRIVER_DLLESPEC int xrtDeviceGetXclbinUUID(xrtDeviceHandle dhdl, xuid_t out)

Get UUID of xclbin image loaded on device

Parameters

xrtDeviceHandle dhdl
Handle to device previously opened with xrtDeviceOpen
xuid_t out
Return xclbin id in this uuid_t struct

Return

0 on success or appropriate error number

Note that current UUID can be different from the UUID of the xclbin loaded by this process using load_xclbin()

typedef xrtXclbinHandle

opaque xclbin handle

XCL_DRIVER_DLLESPEC xrtXclbinHandle xrtXclbinAllocFilename(const char * filename)

Allocate a xclbin using xclbin filename

Parameters

const char * filename
path to the xclbin file

Return

xrtXclbinHandle on success or NULL with errno set

XCL_DRIVER_DLLESPEC xrtXclbinHandle xrtXclbinAllocAxlf(const struct axlf * top_axlf)

Allocate a xclbin using an axlf

Parameters

const struct axlf * top_axlf
an axlf

Return

xrtXclbinHandle on success or NULL with errno set

XCL_DRIVER_DLLESPEC xrtXclbinHandle xrtXclbinAllocRawData(const char * data, int size)

Allocate a xclbin using raw data

Parameters

const char * data
raw data buffer of xclbin
int size
size (in bytes) of raw data buffer of xclbin

Return

xrtXclbinHandle on success or NULL with errno set

XCL_DRIVER_DLLESPEC int xrtXclbinFreeHandle(xrtXclbinHandle xhdl)

Deallocate the xclbin handle

Parameters

xrtXclbinHandle xhdl
xclbin handle

Return

0 on success, -1 on error

XCL_DRIVER_DLLESPEC int xrtXclbinGetXSAName(xrtXclbinHandle xhdl, char * name, int size, int * ret_size)

Get Xilinx Support Archive (XSA) Name of xclbin handle

Parameters

xrtXclbinHandle xhdl
Xclbin handle
char * name
Return name of XSA. If the value is nullptr, the content of this value will not be populated. Otherwise, the the content of this value will be populated.
int size
size (in bytes) of name.
int * ret_size
Return size (in bytes) of XSA name. If the value is nullptr, the content of this value will not be populated. Otherwise, the the content of this value will be populated.

Return

0 on success or appropriate error number

XCL_DRIVER_DLLESPEC int xrtXclbinGetUUID(xrtXclbinHandle xhdl, xuid_t ret_uuid)

Get UUID of xclbin handle

Parameters

xrtXclbinHandle xhdl
Xclbin handle
xuid_t ret_uuid
Return xclbin id in this uuid_t struct

Return

0 on success or appropriate error number

XCL_DRIVER_DLLESPEC size_t xrtXclbinGetNumKernels(xrtXclbinHandle xhdl)

Get number of PL kernels in xclbin

Parameters

xrtXclbinHandle xhdl
Xclbin handle obtained from an xrtXclbinAlloc function

Return

The number of PL kernels in the xclbin

Kernels are extracted from embedded XML metadata in the xclbin. A kernel groups one or more compute units. A kernel has arguments from which offset, type, etc can be retrived.

XCL_DRIVER_DLLESPEC size_t xrtXclbinGetNumKernelComputeUnits(xrtXclbinHandle xhdl)

Get number of CUs in xclbin

Parameters

xrtXclbinHandle xhdl
Xclbin handle obtained from an xrtXclbinAlloc function

Return

The number of compute units

Compute units are associated with kernels. This function returns the total number of compute units as the sum of compute units over all kernels.

XCL_DRIVER_DLLESPEC int xrtXclbinGetData(xrtXclbinHandle xhdl, char * data, int size, int * ret_size)

Get the raw data of the xclbin handle

Parameters

xrtXclbinHandle xhdl
Xclbin handle
char * data
Return raw data. If the value is nullptr, the content of this value will not be populated. Otherwise, the the content of this value will be populated.
int size
Size (in bytes) of data
int * ret_size
Return size (in bytes) of XSA name. If the value is nullptr, the content of this value will not be populated. Otherwise, the the content of this value will be populated.

Return

0 on success or appropriate error number

Kernel APIs

typedef xrtKernelHandle

opaque kernel handle

Description

A kernel handle is obtained by opening a kernel. Clients pass this kernel handle to APIs that operate on a kernel.

typedef xrtRunHandle

opaque handle to a specific kernel run

Description

A run handle is obtained by running a kernel. Clients use a run handle to check or wait for kernel completion.

XCL_DRIVER_DLLESPEC xrtKernelHandle xrtPLKernelOpen(xrtDeviceHandle deviceHandle, const xuid_t xclbinId, const char * name)

Open a PL kernel and obtain its handle.

Parameters

xrtDeviceHandle deviceHandle
Handle to the device with the kernel
const xuid_t xclbinId
The uuid of the xclbin with the specified kernel.
const char * name
Name of kernel to open.

Return

Handle representing the opened kernel.

The kernel name must uniquely identify compatible kernel instances (compute units). Optionally specify which kernel instance(s) to open using “kernelname:{instancename1,instancename2,…}” syntax. The compute units are opened with shared access, meaning that other kernels and other process will have shared access to same compute units. If exclusive access is needed then open the kernel using xrtPLKernelOpenExclusve().

An xclbin with the specified kernel must have been loaded prior to calling this function. An XRT_NULL_HANDLE is returned on error and errno is set accordingly.

A kernel handle is thread safe and can be shared between threads.

XCL_DRIVER_DLLESPEC xrtKernelHandle xrtPLKernelOpenExclusive(xrtDeviceHandle deviceHandle, const xuid_t xclbinId, const char * name)

Open a PL kernel and obtain its handle.

Parameters

xrtDeviceHandle deviceHandle
Handle to the device with the kernel
const xuid_t xclbinId
The uuid of the xclbin with the specified kernel.
const char * name
Name of kernel to open.

Return

Handle representing the opened kernel.

Same as xrtPLKernelOpen(), but opens compute units with exclusive access. Fails if any compute unit is already opened with either exclusive or shared access.

XCL_DRIVER_DLLESPEC int xrtKernelClose(xrtKernelHandle kernelHandle)

Close an opened kernel

Parameters

xrtKernelHandle kernelHandle
Handle to kernel previously opened with xrtKernelOpen

Return

0 on success, -1 on error

XCL_DRIVER_DLLESPEC int xrtKernelArgGroupId(xrtKernelHandle kernelHandle, int argno)

Acquire bank group id for kernel argument

Parameters

xrtKernelHandle kernelHandle
Handle to kernel previously opened with xrtKernelOpen
int argno
Index of kernel argument

Return

Group id or negative error code on error

A valid group id is a non-negative integer. The group id is required when constructing a buffer object.

The kernel argument group id is ambigious if kernel has multiple kernel with different connectivity for specified argument. In this case the API returns error.

XCL_DRIVER_DLLESPEC uint32_t xrtKernelArgOffset(xrtKernelHandle khdl, int argno)

Get the offset of kernel argument

Parameters

xrtKernelHandle khdl
Handle to kernel previously opened with xrtKernelOpen
int argno
Index of kernel argument

Return

The kernel register offset of the argument with specified index

Use with :c:func:`xrtKernelReadRegister()` and :c:func:`xrtKernelWriteRegister()` if manually reading or writing kernel registers for explicit arguments.

XCL_DRIVER_DLLESPEC int xrtKernelReadRegister(xrtKernelHandle kernelHandle, uint32_t offset, uint32_t * datap)

Read data from kernel address range

Parameters

xrtKernelHandle kernelHandle
Handle to kernel previously opened with xrtKernelOpen
uint32_t offset
Offset in register space to read from
uint32_t * datap
Pointer to location where to write data

Return

0 on success, errcode otherwise

The kernel must be associated with exactly one kernel instance (compute unit), which must be opened for exclusive access.

XCL_DRIVER_DLLESPEC int xrtKernelWriteRegister(xrtKernelHandle kernelHandle, uint32_t offset, uint32_t data)

Write to the address range of a kernel

Parameters

xrtKernelHandle kernelHandle
Handle to kernel previously opened with xrtKernelOpen
uint32_t offset
Offset in register space to write to
uint32_t data
Data to write

Return

0 on success, errcode otherwise

The kernel must be associated with exactly one kernel instance (compute unit), which must be opened for exclusive access.

XCL_DRIVER_DLLESPEC xrtRunHandle xrtKernelRun(xrtKernelHandle kernelHandle, ...)

Start a kernel execution

Parameters

xrtKernelHandle kernelHandle
Handle to the kernel to run
...
Kernel arguments

Return

Run handle which must be closed with xrtRunClose()

A run handle is specific to one execution of a kernel. Once execution completes, the run handle can be re-used to execute the same kernel again. When no longer needed, then run handle must be closed with xrtRunClose().

XCL_DRIVER_DLLESPEC xrtRunHandle xrtRunOpen(xrtKernelHandle kernelHandle)

Open a new run handle for a kernel without starting kernel

Parameters

xrtKernelHandle kernelHandle
Handle to the kernel to associate the run handle with

Return

Run handle which must be closed with xrtRunClose()

The handle can be used repeatedly to start an execution of the associated kernel. This API allows application to manage run handles without maintaining corresponding kernel handle.

XCL_DRIVER_DLLESPEC int xrtRunSetArg(xrtRunHandle rhdl, int index, ...)

Set a specific kernel argument for this run

Parameters

xrtRunHandle rhdl
Handle to the run object to modify
int index
Index of kernel argument to set
...
The argument value to set.

Return

0 on success, -1 on error

Use this API to explicitly set specific kernel arguments prior to starting kernel execution. After setting all arguments, the kernel execution can be start with xrtRunStart()

XCL_DRIVER_DLLESPEC int xrtRunUpdateArg(xrtRunHandle rhdl, int index, ...)

Asynchronous update of kernel argument

Parameters

xrtRunHandle rhdl
Handle to the run object to modify
int index
Index of kernel argument to update
...
The argument value to update.

Return

0 on success, -1 on error

Use this API to asynchronously update a specific kernel argument of an existing run.

This API is only supported on Edge.

XCL_DRIVER_DLLESPEC int xrtRunStart(xrtRunHandle rhdl)

Start existing run handle

Parameters

xrtRunHandle rhdl
Handle to the run object to start

Return

0 on success, -1 on error

Use this API when re-using a run handle for more than one execution of the kernel associated with the run handle.

XCL_DRIVER_DLLESPEC enum ert_cmd_state xrtRunWait(xrtRunHandle rhdl)

Wait for a run to complete

Parameters

xrtRunHandle rhdl
Handle to the run object to start

Return

Run command state for completed run,
or ERT_CMD_STATE_ABORT on error

Blocks current thread until job has completed

XCL_DRIVER_DLLESPEC enum ert_cmd_state xrtRunWaitFor(xrtRunHandle rhdl, unsigned int timeout_ms)

Wait for a run to complete

Parameters

xrtRunHandle rhdl
Handle to the run object to start
unsigned int timeout_ms
Timeout in millisecond

Return

Run command state for completed run, or
current status if timeout.

Blocks current thread until job has completed

XCL_DRIVER_DLLESPEC enum ert_cmd_state xrtRunState(xrtRunHandle rhdl)

Check the current state of a run

Parameters

xrtRunHandle rhdl
Handle to check

Return

The underlying command execution state per ert.h

XCL_DRIVER_DLLESPEC int xrtRunSetCallback(xrtRunHandle rhdl, enum ert_cmd_state state, void (*callback) (xrtRunHandle, enum ert_cmd_state, void*, void * data)

Set a callback function

Parameters

xrtRunHandle rhdl
Handle to set callback on
enum ert_cmd_state state
State to invoke callback on
void (*)(xrtRunHandle, enum ert_cmd_state, void*) callback
Callback function
void * data
User data to pass to callback function

Description

Register a run callback function that is invoked when the run changes underlying execution state to specified state. Support states are: ERT_CMD_STATE_COMPLETED (to be extended)

XCL_DRIVER_DLLESPEC int xrtRunClose(xrtRunHandle rhdl)

Close a run handle

Parameters

xrtRunHandle rhdl
Handle to close

Return

0 on success, -1 on error