XRT Native Library C API¶
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
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
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
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 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
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 with errno set
-
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 with errno set
-
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 with errno set
-
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
-
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 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 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 with errno set
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.
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