XRT Core Library¶

Xilinx Runtime (XRT) Library Interface Definitions

Header file xrt.h defines data structures and function signatures exported by Xilinx Runtime (XRT) Library. XRT is part of software stack which is integrated into Xilinx reference platform.

typedef xclDeviceHandle¶: opaque device handle

Description

A device handle of xclDeviceHandle kind is obtained by opening a device. Clients pass this device handle to refer to the opened device in all future interaction with XRT.

XRT Device Management APIs

XCL_DRIVER_DLLESPEC unsigned int xclProbe()¶: Enumerate devices found in the system

Parameters

Return

count of devices found

XCL_DRIVER_DLLESPEC xclDeviceHandle xclOpen(unsigned int deviceIndex, const char * unused1, enum xclVerbosityLevel unused2)¶: Open a device and obtain its handle.

Parameters

unsigned int deviceIndex: Slot number of device 0 for first device, 1 for the second device…
const char * unused1: undescribed
enum xclVerbosityLevel unused2: undescribed

Return

Device handle

XCL_DRIVER_DLLESPEC void xclClose(xclDeviceHandle handle)¶: Close an opened device

Parameters

xclDeviceHandle handle: Device handle

XCL_DRIVER_DLLESPEC int xclGetDeviceInfo2(xclDeviceHandle handle, struct xclDeviceInfo2 * info)¶: Obtain various bits of information from the device

Parameters

xclDeviceHandle handle: Device handle
struct xclDeviceInfo2 * info: Information record

Return

0 on success or appropriate error number

XCL_DRIVER_DLLESPEC int xclGetUsageInfo(xclDeviceHandle handle, struct xclDeviceUsage * info)¶: Obtain usage information from the device

Parameters

xclDeviceHandle handle: Device handle
struct xclDeviceUsage * info: Information record

Return

0 on success or appropriate error number

XCL_DRIVER_DLLESPEC int xclGetErrorStatus(xclDeviceHandle handle, struct xclErrorStatus * info)¶: Obtain error information from the device

Parameters

xclDeviceHandle handle: Device handle
struct xclErrorStatus * info: Information record

Return

0 on success or appropriate error number

XCL_DRIVER_DLLESPEC int xclLoadXclBin(xclDeviceHandle handle, const struct axlf * buffer)¶: Download FPGA image (xclbin) to the device

Parameters

xclDeviceHandle handle: Device handle
const struct axlf * buffer: Pointer to device image (xclbin) in memory

Return

0 on success or appropriate error number

Download FPGA image (AXLF) to the device. The PR bitstream is encapsulated inside xclbin as a section. The xclbin may also contain other sections, which are suitably handled by the driver.

This API also downloads OVERLAY (dtbo) section (Edge only).

XCL_DRIVER_DLLESPEC int xclGetSectionInfo(xclDeviceHandle handle, void * info, size_t * size, enum axlf_section_kind kind, int index)¶: Get Information from sysfs about the downloaded xclbin sections

Parameters

xclDeviceHandle handle: Device handle
void * info: Pointer to preallocated memory which will store the return value.
size_t * size: Pointer to preallocated memory which will store the return size.
enum axlf_section_kind kind: axlf_section_kind for which info is being queried
int index: The (sub)section index for the “kind” type.

Return

0 on success or appropriate error number

Get the section information from sysfs. The index corrresponds to the (section) entry of the axlf_section_kind data being queried. The info and the size contain the return binary value of the subsection and its size.

XCL_DRIVER_DLLESPEC int xclReClock2(xclDeviceHandle handle, unsigned short region, const unsigned short * targetFreqMHz)¶: Configure PR region frequncies

Parameters

xclDeviceHandle handle: Device handle
unsigned short region: PR region (always 0)
const unsigned short * targetFreqMHz: Array of target frequencies in order for the Clock Wizards driving the PR region

Return

0 on success or appropriate error number

XCL_DRIVER_DLLESPEC int xclOpenContext(xclDeviceHandle handle, const xuid_t xclbinId, unsigned int ipIndex, bool shared)¶: Create shared/exclusive context on compute units

Parameters

xclDeviceHandle handle: Device handle
const xuid_t xclbinId: UUID of the xclbin image running on the device
unsigned int ipIndex: IP index
bool shared: Shared access or exclusive access

Return

0 on success or appropriate error number

The context is necessary before submitting execution jobs using xclExecBuf(). Contexts may be exclusive or shared. Allocation of exclusive contexts on a hardware IP would succeed only if another client has not already setup up a context on that hardware IP. Shared contexts can be concurrently allocated by many processes on the same compute units.

XCL_DRIVER_DLLESPEC int xclCloseContext(xclDeviceHandle handle, const xuid_t xclbinId, unsigned int ipIndex)¶: Close previously opened context

Parameters

xclDeviceHandle handle: Device handle
const xuid_t xclbinId: UUID of the xclbin image running on the device
unsigned int ipIndex: ipIndex

Return

0 on success or appropriate error number

Close a previously allocated shared/exclusive context for a hardware IP.

XCL_DRIVER_DLLESPEC int xclLogMsg(xclDeviceHandle handle, enum xrtLogMsgLevel level, const char * tag, const char * format, ...)¶: Send message to log file as per settings in ini file.

Parameters

xclDeviceHandle handle: Device handle
enum xrtLogMsgLevel level: Severity level of the msg
const char * tag: Tag supplied by the client, like “OCL”, “XMA”, etc.
const char * format: Format of Msg string to write to log file
...: All other arguments as per the format

Return

0 on success or appropriate error number

XRT Buffer Management APIs

Buffer management APIs are used for managing device memory and migrating buffers between host and device memory

XCL_DRIVER_DLLESPEC xclBufferHandle xclAllocBO(xclDeviceHandle handle, size_t size, int unused, unsigned int flags)¶: Allocate a BO of requested size with appropriate flags

Parameters

xclDeviceHandle handle: Device handle
size_t size: Size of buffer
int unused: This argument is ignored
unsigned int flags: Specify bank information, etc

Return

BO handle

XCL_DRIVER_DLLESPEC xclBufferHandle xclAllocUserPtrBO(xclDeviceHandle handle, void * userptr, size_t size, unsigned int flags)¶: Allocate a BO using userptr provided by the user

Parameters

xclDeviceHandle handle: Device handle
void * userptr: Pointer to 4K aligned user memory
size_t size: Size of buffer
unsigned int flags: Specify bank information, etc

Return

BO handle

XCL_DRIVER_DLLESPEC void xclFreeBO(xclDeviceHandle handle, xclBufferHandle boHandle)¶: Free a previously allocated BO

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle boHandle: BO handle

XCL_DRIVER_DLLESPEC size_t xclWriteBO(xclDeviceHandle handle, xclBufferHandle boHandle, const void * src, size_t size, size_t seek)¶: Copy-in user data to host backing storage of BO

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle boHandle: BO 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 size_t xclReadBO(xclDeviceHandle handle, xclBufferHandle boHandle, void * dst, size_t size, size_t skip)¶: Copy-out user data from host backing storage of BO

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle boHandle: BO 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 void* xclMapBO(xclDeviceHandle handle, xclBufferHandle boHandle, bool write)¶: Memory map BO into user’s address space

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle boHandle: BO handle
bool write: READ only or READ/WRITE mapping

Return

Memory mapped buffer

Map the contents of the buffer object into host memory To unmap the buffer call xclUnmapBO().

XCL_DRIVER_DLLESPEC int xclUnmapBO(xclDeviceHandle handle, xclBufferHandle boHandle, void * addr)¶: Unmap a BO that was previously mapped with xclMapBO

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle boHandle: BO handle
void * addr: The mapped void * pointer returned from xclMapBO()

XCL_DRIVER_DLLESPEC int xclSyncBO(xclDeviceHandle handle, xclBufferHandle boHandle, enum xclBOSyncDirection dir, size_t size, size_t offset)¶: Synchronize buffer contents in requested direction

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle boHandle: BO handle
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 standard errno

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 int xclCopyBO(xclDeviceHandle handle, xclBufferHandle dstBoHandle, xclBufferHandle srcBoHandle, size_t size, size_t dst_offset, size_t src_offset)¶: Copy device buffer contents to another buffer

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle dstBoHandle: Destination BO handle
xclBufferHandle srcBoHandle: Source BO handle
size_t size: Size of data to synchronize
size_t dst_offset: dst Offset within the BO
size_t src_offset: src Offset within the BO

Return

0 on success or standard errno

Copy from source buffer contents to destination buffer, can be device to device or device to host. Always perform WRITE to achieve better performance, destination buffer can be on device or host require DMA from device

XCL_DRIVER_DLLESPEC xclBufferExportHandle xclExportBO(xclDeviceHandle handle, xclBufferHandle boHandle)¶: Obtain DMA-BUF file descriptor for a BO

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle boHandle: BO handle which needs to be exported

Return

File handle to the BO or standard errno

Export a BO for import into another device or Linux subsystem which accepts DMA-BUF fd This operation is backed by Linux DMA-BUF framework. The file handle must be explicitly closed when no longer needed.

XCL_DRIVER_DLLESPEC xclBufferHandle xclImportBO(xclDeviceHandle handle, xclBufferExportHandle fd, unsigned int flags)¶: Obtain BO handle for a BO represented by DMA-BUF file descriptor

Parameters

xclDeviceHandle handle: Device handle
xclBufferExportHandle fd: File handle to foreign BO owned by another device which needs to be imported
unsigned int flags: Unused

Return

BO handle of the imported BO

Import a BO exported by another device. * This operation is backed by Linux DMA-BUF framework

XCL_DRIVER_DLLESPEC int xclGetBOProperties(xclDeviceHandle handle, xclBufferHandle boHandle, struct xclBOProperties * properties)¶: Obtain xclBOProperties struct for a BO

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle boHandle: BO handle
struct xclBOProperties * properties: BO properties struct pointer

Return

0 on success

This is the prefered method for obtaining BO property information.

XCL_DRIVER_DLLESPEC int xclIPName2Index(xclDeviceHandle handle, const char * ipName)¶: Obtain IP index by IP name

Parameters

xclDeviceHandle handle: Device handle
const char * ipName: IP name. usually “<kernel name>:<instance name>”

Return

IP index or appropriate error number

xclIPName2Index() should be used to obtain unique index of IP as understood by other XRT APIs like xclOpenContext().

XRT Unmanaged DMA APIs

Unmanaged DMA APIs are for exclusive use by the debuggers and tools. The APIs allow clients to read/write from/to absolute device address. No checks are performed if a buffer was allocated before at the specified location or if the address is valid. Users who want to take over the full memory managemnt of the device memory should instead use XRT sub-buffer infrastructure for fine grained placement of buffers as it also provides better DMA performancce and richer set of features like mmap/munmap, etc.

The unmanaged APIs are planned to be be deprecated in future.

XCL_DRIVER_DLLESPEC ssize_t xclUnmgdPread(xclDeviceHandle handle, unsigned int flags, void * buf, size_t size, uint64_t offset)¶: Perform unmanaged device memory read operation

Parameters

xclDeviceHandle handle: Device handle
unsigned int flags: Unused
void * buf: Destination data pointer
size_t size: Size of data to copy
uint64_t offset: Absolute offset inside device

Return

0 on success or appropriate error number

This API may be used to perform DMA operation from absolute location specified. As stated before this API is for use by debuggers and profilers. Do not use it in your application.

XCL_DRIVER_DLLESPEC ssize_t xclUnmgdPwrite(xclDeviceHandle handle, unsigned int flags, const void * buf, size_t size, uint64_t offset)¶: Perform unmanaged device memory read operation

Parameters

xclDeviceHandle handle: Device handle
unsigned int flags: Unused
const void * buf: Source data pointer
size_t size: Size of data to copy
uint64_t offset: Absolute offset inside device

Return

0 on success or appropriate error number

This API may be used to perform DMA operation to an absolute location specified. As stated before this API is for use by debuggers and profilers. Do not use it in your application.

XRT Compute Unit Execution Management APIs

These APIs are under development. These functions will be used to start compute units and wait for them to finish.

XCL_DRIVER_DLLESPEC int xclExecBuf(xclDeviceHandle handle, xclBufferHandle cmdBO)¶: Submit an execution request to the embedded (or software) scheduler

Parameters

xclDeviceHandle handle: Device handle
xclBufferHandle cmdBO: BO handle containing command packet

Return

0 or standard error number

Submit an exec buffer for execution. The exec buffer layout is defined by struct ert_packet which is defined in file ert.h. The BO should been allocated with DRM_XOCL_BO_EXECBUF flag.

XCL_DRIVER_DLLESPEC int xclExecWait(xclDeviceHandle handle, int timeoutMilliSec)¶: Wait for one or more execution events on the device

Parameters

xclDeviceHandle handle: Device handle
int timeoutMilliSec: How long to wait for

Return

Same code as poll system call

Wait for notification from the hardware. The function essentially calls “poll” system call on the driver file handle. The return value has same semantics as poll system call. If return value is > 0 caller should check the status of submitted exec buffers Note that if you perform wait for the same handle from multiple threads, you may lose wakeup for some of them. So, use different handle in different threads.