XRT Native Library C++ API

Configuration APIs

namespace xrt::ini

APIs for XRT configuration control.

XRT can be configured through a json xrt.ini file co-located with the host executable. If present, XRT uses configuration options from the ini file when a given option is first accessed. Without an ini file, the configuration options take on default values.

The APIs in this file allow host application to specify configuration options for XRT programatically. It is only possible for the host application to change configuration options before a given option is used by XRT the very first time.

Functions

void set(const std::string &key, const std::string &value)

set() - Change xrt.ini string value for specified key

Throws if key value cannot be changed.

Parameters
  • key: Key to change value for

  • value: New value for key

void set(const std::string &key, unsigned int value)

set() - Change xrt.ini string value for specified key

Throws if key value cannot be changed.

Parameters
  • key: Key to change value for

  • value: New value for key

Device and XCLBIN APIs

class xrt::device

Public Functions

device()

device() - Constructor for empty device

device(unsigned int didx)

device() - Constructor with user host buffer and flags

Parameters
  • didx: Device index

device(xclDeviceHandle dhdl)

device() - Create a managed device object from a shim xclDeviceHandle

Return

xrt::device object epresenting the opened device, or exception on error

Parameters
  • dhdl: Shim xclDeviceHandle

device(const device &rhs) = default

device() - Copy ctor

device(device &&rhs) = default

device() - Move ctor

device &operator=(device &&rhs) = default

operator= () - Move assignment

uuid load_xclbin(const struct axlf *xclbin)

load_xclbin() - Load an xclbin

Return

UUID of argument xclbin

Parameters
  • xclbin: Pointer to xclbin in memory image

uuid load_xclbin(const std::string &xclbin_fnm)

load_xclbin() - Read and load an xclbin file

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

Return

UUID of argument xclbin

Parameters
  • xclbin_fnm: Full path to xclbin file

uuid load_xclbin(const xrt::xclbin &xclbin)

load_xclbin() - load an xclin from an xclbin object

This function uses the specified

xrt::xclbin object created by caller. The xrt::xclbin object must contain the complete axlf structure.
Return

UUID of argument xclbin

Parameters

uuid get_xclbin_uuid() const

get_xclbin_uuid() - Get UUID of xclbin image loaded on device

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

load_xclbin()
Return

UUID of currently loaded xclbin

template<typename SectionType>
SectionType get_xclbin_section(axlf_section_kind section, const uuid &uuid) const

get_xclbin_section() - Retrieve specified xclbin section

Get the xclbin section of the xclbin currently loaded on the device. The function throws on error

Return

The specified section if available.

Parameters
  • section: The section to retrieve

  • uuid: Xclbin uuid of the xclbin with the section to retrieve

Note, this API may be replaced with more generic query request access

class xrt::xclbin

Public Functions

xclbin(const std::string &filename)

xclbin() - Constructor from an xclbin filename

The xclbin file must be accessible by the application. An exception is thrown file not found

Parameters
  • filename: Path to the xclbin file

xclbin(const std::vector<char> &data)

xclbin() - Constructor from raw data

The raw data of the xclbin can be deleted after calling the constructor.

Parameters
  • data: Raw data of xclbin

xclbin(const xclbin &rhs) = default

xclbin() - Copy ctor

xclbin(xclbin &&rhs) = default

xclbin() - Move ctor

xclbin &operator=(xclbin &&rhs) = default

operator= () - Move assignment

std::vector<std::string> get_cu_names() const

get_cu_names() - Get CU names of xclbin

An exception is thrown if the data is missing.

Return

A list of CU Names in order of increasing base address.

std::string get_xsa_name() const

get_xsa_name() - Get Xilinx Support Archive (XSA) Name of xclbin

An exception is thrown if the data is missing.

Return

Name of XSA

uuid get_uuid() const

get_uuid() - Get the uuid of the xclbin

An exception is thrown if the data is missing.

Return

UUID of xclbin

const std::vector<char> &get_data() const

get_data() - Get the raw data of the xclbin

An exception is thrown if the data is missing.

Return

The raw data of the xclbin

Buffer APIs

class xrt::bo

Public Types

enum flags

  • buffer object flags

Values:

enumerator normal

Create normal BO with host side and device side buffers

enumerator cacheable

Create cacheable BO. Only effective on embedded platforms.

enumerator device_only

Create a BO with a device side buffer only

enumerator host_only

Create a BO with a host side buffer only

enumerator p2p

Create a BO for peer-to-peer use

The flags used by xrt::bo are compatible with XCL style flags as define in xrt_mem.h

Public Functions

bo()

bo() - Constructor for empty bo

bo(xclDeviceHandle dhdl, void *userptr, size_t sz, bo::flags flags, memory_group grp)

bo() - Constructor with user host buffer and flags

Parameters
  • dhdl: Device handle

  • userptr: Pointer to aligned user memory

  • sz: Size of buffer

  • flags: Specify special flags per xrt_mem.h

  • grp: Device memory group to allocate buffer in

bo(xclDeviceHandle dhdl, void *userptr, size_t sz, memory_group grp)

bo() - Constructor with user host buffer

The buffer type is default buffer object with host buffer and device buffer, where the host buffer is managed by user.

Parameters
  • dhdl: Device handle

  • userptr: Pointer to aligned user memory

  • sz: Size of buffer

  • grp: Device memory group to allocate buffer in

bo(xclDeviceHandle dhdl, size_t size, bo::flags flags, memory_group grp)

bo() - Constructor where XRT manages host buffer if any

If the flags require a host buffer, then the host buffer is allocated by XRT and can be accessed by using

map()
Parameters
  • dhdl: Device handle

  • size: Size of buffer

  • flags: Specify special flags per xrt_mem.h

  • grp: Device memory group to allocate buffer in

bo(xclDeviceHandle dhdl, size_t size, memory_group grp)

bo() - Constructor, default flags, where XRT manages host buffer if any

The buffer type is default buffer object with host buffer and device buffer. The host buffer is allocated and managed by XRT.

Parameters
  • dhdl: Device handle

  • size: Size of buffer

  • grp: Device memory group to allocate buffer in

bo(xclDeviceHandle dhdl, xclBufferExportHandle ehdl)

bo() - Constructor to import an exported buffer

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

Parameters
  • dhdl: Device that imports the exported buffer

  • ehdl: Exported buffer handle, implementation specific type

bo(const bo &parent, size_t size, size_t offset)

bo() - Constructor for sub-buffer

Parameters
  • parent: Parent buffer

  • size: Size of sub-buffer

  • offset: Offset into parent buffer

bo(const bo &rhs) = default

bo() - Copy ctor

bo(bo &&rhs) = default

bo() - Move ctor

bo &operator=(bo &&rhs) = default

operator= () - Move assignment

size_t size() const

size() - Get the size of this buffer

Return

Size of buffer in bytes

uint64_t address() const

address() - Get the device address of this buffer

Return

Device address of buffer

xclBufferExportHandle export_buffer()

buffer_export() - Export this buffer

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

Return

Exported buffer handle

void sync(xclBOSyncDirection dir, size_t sz, size_t offset)

sync() - Synchronize buffer content with device side

Sync specified size bytes of buffer starting at specified offset.

Parameters
  • dir: To device or from device

  • sz: Size of data to synchronize

  • offset: Offset within the BO

void sync(xclBOSyncDirection dir)

sync() - Synchronize buffer content with device side

Sync entire buffer content in specified direction.

Parameters
  • dir: To device or from device

void *map()

map() - Map the host side buffer into application

Map the contents of the buffer object into host memory

Return

Memory mapped buffer

template<typename MapType>
MapType map()

map() - Map the host side buffer info application

Return

Memory mapped buffer

Template Parameters
  • MapType: Type of mapped data

void write(const void *src, size_t size, size_t seek)

write() - Copy-in user data to host backing storage of BO

Copy source data to host buffer of this buffer object.

seek specifies how many bytes to skip at the beginning of the BO before copying-in size bytes to host buffer.
Parameters
  • src: Source data pointer

  • size: Size of data to copy

  • seek: Offset within the BO

void write(const void *src)

write() - Copy-in user data to host backing storage of BO

Copy specified source data to host buffer of this buffer object.

Parameters
  • src: Source data pointer

void read(void *dst, size_t size, size_t skip)

read() - Copy-out user data from host backing storage of BO

Copy content of host buffer of this buffer object to specified destination.

skip specifies how many bytes to skip from the beginning of the BO before copying-out size bytes of host buffer.
Parameters
  • dst: Destination data pointer

  • size: Size of data to copy

  • skip: Offset within the BO

void read(void *dst)

read() - Copy-out user data from host backing storage of BO

Copy content of host buffer of this buffer object to specified destination.

Parameters
  • dst: Destination data pointer

void copy(const bo &src, size_t sz, size_t src_offset = 0, size_t dst_offset = 0)

copy() - Deep copy BO content from another buffer

Throws if copy size is 0 or sz + src/dst_offset is out of bounds.

Parameters
  • src: Source BO to copy from

  • sz: Size of data to copy

  • src_offset: Offset into src buffer copy from

  • dst_offset: Offset into this buffer to copy to

void copy(const bo &src)

copy() - Deep copy BO content from another buffer

Copy full content of specified src buffer object to this buffer object

Parameters
  • src: Source BO to copy from

Kernel APIs

class xrt::kernel

A kernel object represents a set of instances matching a specified name. The kernel is created by finding matching kernel instances in the currently loaded xclbin.

Most interaction with kernel objects are through xrt::run objects created from the kernel object to represent an execution of the kernel

Public Functions

kernel(const xrt::device &device, const xrt::uuid &xclbin_id, const std::string &name, cu_access_mode mode = cu_access_mode::shared)

kernel() - Constructor from a device and xclbin

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 default opened with shared access, meaning that other kernels and other process will have shared access to same compute units.

Parameters
  • device: Device on which the kernel should execute

  • xclbin_id: UUID of the xclbin with the kernel

  • name: Name of kernel to construct

  • mode: Open the kernel instances with specified access (default shared)

template<typename ...Args>
run operator()(Args&&... args)

operator() - Invoke the kernel function

Return

Run object representing this kernel function invocation

Parameters
  • args: Kernel arguments

int group_id(int argno) const

group_id() - Get the memory bank group id of an kernel argument

The function throws if the group id is ambigious.

Return

The memory group id to use when allocating buffers (see xrt::bo)

Parameters
  • argno: The argument index

uint32_t offset(int argno) const

offset() - Get the offset of kernel argument

Use with

read_register() and write_register() if manually reading or writing kernel registers for explicit arguments.
Return

The kernel register offset of the argument with specified index

Parameters
  • argno: The argument index

void write_register(uint32_t offset, uint32_t data)

write() - Write to the address range of a kernel

Throws std::out_or_range if offset is outside the kernel address space

Parameters
  • offset: Offset in register space to write to

  • data: Data to write

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

uint32_t read_register(uint32_t offset) const

read() - Read data from kernel address range

Throws std::out_or_range if offset is outside the kernel address space

Return

Value read from offset

Parameters
  • offset: Offset in register space to read from

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

class xrt::run

xrt::run represents one execution of a kernel

The run handle can be explicitly constructed from a kernel object or implicitly constructed from starting a kernel execution.

A run handle can be re-used to execute the same kernel again.

Public Functions

run()

run() - Construct empty run object

Can be used as lvalue in assignment.

run(const kernel &krnl)

run() - Construct run object from a kernel object

Parameters
  • krnl: Kernel object representing the kernel to execute

void start()

start() - Start execution of a run.

This function is asynchronous, run status must be expclicit checked or wait() must be used to wait for the run to complete.

ert_cmd_state wait(const std::chrono::milliseconds &timeout = std::chrono::milliseconds{0}) const

wait() - Wait for a run to complete execution

The default timeout of 0ms indicates blocking until run completes.

Return

Command state upon return of wait

Parameters
  • timeout: Timeout for wait (default block till run completes)

The current thread will block until the run completes or timeout expires. Completion does not guarantee success, the run status should be checked by using state.

ert_cmd_state wait(unsigned int timeout_ms) const

wait() - Wait for specified milliseconds for run to complete

The default timeout of 0ms indicates blocking until run completes.

Return

Command state upon return of wait

Parameters
  • timeout_ms: Timeout in milliseconds

The current thread will block until the run completes or timeout expires. Completion does not guarantee success, the run status should be checked by using state.

ert_cmd_state state() const

state() - Check the current state of a run object

The state values are defined in

include/ert.h
Return

Current state of this run object

void add_callback(ert_cmd_state state, std::function<void(const run&, ert_cmd_state, void*)> callback, void *data, )

add_callback() - Add a callback function for run state

The function is called when the run object changes state to argument state or any error state. Only

ERT_CMD_STATE_COMPLETED is supported currently.
Parameters
  • state: State to invoke callback on

  • callback: Callback function

  • data: User data to pass to callback function

Any number of callbacks are supported.

void set_event(const std::shared_ptr<event_impl> &event) const

set_event() - Add event for enqueued operations

This function is used when a run object is enqueued in an event graph. The event must be notified upon completion of the run.

Parameters
  • event: Opaque implementation object

operator bool() const

operator bool() - Check if run handle is valid

Return

True if run is associated with kernel object, false otherwise

template<typename ArgType>
void set_arg(int index, ArgType &&arg)

set_arg() - Set a specific kernel scalar argument for this run

Use this API to explicit set or change a kernel argument prior to starting kernel execution. After setting arguments, the kernel can be started using

start() on the run object.
Parameters
  • index: Index of kernel argument to update

  • arg: The scalar argument value to set.

See also operator() to set all arguments and start kernel.

void set_arg(int index, xrt::bo &boh)

set_arg() - Set a specific kernel global argument for a run

Use this API to explicit set or change a kernel argument prior to starting kernel execution. After setting arguments, the kernel can be started using

start() on the run object.
Parameters
  • index: Index of kernel argument to set

  • boh: The global buffer argument value to set (lvalue).

See also operator() to set all arguments and start kernel.

void set_arg(int index, const xrt::bo &boh)

set_arg - xrt::bo variant for const lvalue

void set_arg(int index, xrt::bo &&boh)

set_arg - xrt::bo variant for rvalue

template<typename ArgType>
void update_arg(int index, ArgType &&arg)

udpdate_arg() - Asynchronous update of scalar kernel global argument

Use this API to asynchronously update a specific scalar argument of the kernel associated with the run object.

Parameters
  • index: Index of kernel argument to update

  • arg: The scalar argument value to set.

This API is only supported on Edge.

void update_arg(int index, const xrt::bo &boh)

update_arg() - Asynchronous update of kernel global argument for a run

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

Parameters
  • index: Index of kernel argument to update

  • boh: The global buffer argument value to set.

This API is only supported on Edge.

template<typename ...Args>
void operator()(Args&&... args)

operator() - Set all kernel arguments and start the run

Use this API to explicitly set all kernel arguments and start kernel execution.

Parameters
  • args: Kernel arguments

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