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