XMA Lower Edge API Library¶

XMA Plugin Interface

The interface used by XMA kernel plugin developers

XmaBufferObj xma_plg_buffer_alloc(XmaSession s_handle, size_t size, bool device_only_buffer, int32_t *return_code)¶: Allocate device memory This function allocates memory on the FPGA DDR and provides a BufferObject to the memory that can be used for copying data from the host to device memory or from the device to the host. BufferObject contains paddr, device index, ddr bank, etc. paddr (the physical address) is necessary for setting the AXI register map with physical pointers so that the kernel knows where key input and output buffers are located. This function knows which DDR bank is associated with this session and therefore automatically selects the correct DDR bank.

Parameters

XmaSession s_handle: The session handle associated with this plugin instance.
size_t size: Size in bytes of the device buffer to be allocated.
bool device_only_buffer: Allocate device only buffer without any host space
int32_t * return_code: XMA_SUCESS or XMA_ERROR.

Return

BufferObject on success;

XmaBufferObj xma_plg_buffer_alloc_arg_num(XmaSession s_handle, size_t size, bool device_only_buffer, int32_t arg_num, int32_t *return_code)¶: Allocate device memory This function allocates memory on the FPGA DDR bank connected to the supplied kernel argument number and provides a BufferObject to the memory that can be used for copying data from the host to device memory or from the device to the host. BufferObject contains paddr, device index, ddr bank, etc. paddr (the physical address) is necessary for setting the AXI register map with physical pointers so that the kernel knows where key input and output buffers are located. This function knows which DDR bank is associated with this session and therefore automatically selects the correct DDR bank.

Parameters

XmaSession s_handle: The session handle associated with this plugin instance.
size_t size: Size in bytes of the device buffer to be allocated.
bool device_only_buffer: Allocate device only buffer without any host space
int32_t arg_num: kernel argumnet num. Buffer is allocated on DDR bank connected to this kernel argument
int32_t * return_code: XMA_SUCESS or XMA_ERROR.

Return

BufferObject on success;

XmaBufferObj xma_plg_buffer_alloc_ddr(XmaSession s_handle, size_t size, bool device_only_buffer, int32_t ddr_index, int32_t *return_code)¶: Allocate device memory This function allocates memory on the FPGA DDR bank as supplied in ddr_index argument. It provides a BufferObject to the memory that can be used for copying data from the host to device memory or from the device to the host. BufferObject contains paddr, device index, ddr bank, etc. paddr (the physical address) is necessary for setting the AXI register map with physical pointers so that the kernel knows where key input and output buffers are located. This function knows which DDR bank is associated with this session and therefore automatically selects the correct DDR bank.

Parameters

XmaSession s_handle: The session handle associated with this plugin instance.
size_t size: Size in bytes of the device buffer to be allocated.
bool device_only_buffer: Allocate device only buffer without any host space
int32_t ddr_index: Buffer is allocated on this DDR bank index. Check index to use in xclbin or by command “xbutil query”
int32_t * return_code: XMA_SUCESS or XMA_ERROR.

Return

BufferObject on success;

void xma_plg_buffer_free(XmaSession s_handle, XmaBufferObj b_obj)¶: Free a device buffer This function frees a previous allocated buffer that was obtained using the ref xma_plg_buffer_alloc() function.

Parameters

XmaSession s_handle: The session handle associated with this plugin instance
XmaBufferObj b_obj: The BufferObject returned from ref xma_plg_buffer_alloc()

int32_t xma_plg_buffer_write(XmaSession s_handle, XmaBufferObj b_obj, size_t size, size_t offset)¶: Write data from host to device buffer This function copies data from host memory to device memory.

Parameters

XmaSession s_handle: The session handle associated with this plugin instance
XmaBufferObj b_obj: The BufferObject returned from ref xma_plg_buffer_alloc()
size_t size: Size of data to copy
size_t offset: Offset from the beginning of the allocated device memory

Return

XMA_SUCCESS on success XMA_ERROR on failure

int32_t xma_plg_buffer_read(XmaSession s_handle, XmaBufferObj b_obj, size_t size, size_t offset)¶: Read data from device memory and copy to host memory

Parameters

XmaSession s_handle: The session handle associated with this plugin instance
XmaBufferObj b_obj: The BufferObject returned from ref xma_plg_buffer_alloc()
size_t size: Size of data to copy
size_t offset: Offset from the beginning of the allocated device memory

Return

XMA_SUCCESS on success XMA_ERROR on failure

int32_t xma_plg_channel_id(XmaSession s_handle)¶: Query channel_id assigned to this plugin session

Parameters

XmaSession s_handle: The session handle associated with this plugin instance

Return

Assigned channel_id on success XMA_ERROR on failure

int32_t xma_plg_is_work_item_done(XmaSession s_handle, uint32_t timeout_in_ms)¶: This function checks if at least one work item previously submitted via xma_plg_schedule_work_item() has completed. If the supplied timeout expires before a work item has completed, this function returns an error.

Parameters

XmaSession s_handle: The session handle associated with this plugin instance
uint32_t timeout_in_ms: A timeout value in milliseconds

Return

XMA_SUCCESS on success

XMA_ERROR on timeout

int32_t xma_plg_work_item_return_code(XmaSession s_handle, XmaCUCmdObj *cmd_obj_array, int32_t num_cu_objs, uint32_t *num_cu_errors)¶: This function gets return code of completed cu cmds previously submitted via xma_plg_schedule_work_item(). If any cu cmd hasn’t completed yet, this function returns an error.

Parameters

XmaSession s_handle: The session handle associated with this plugin instance
XmaCUCmdObj * cmd_obj_array: An array of command objects
int32_t num_cu_objs: Num of cu cmd objects in above array of command objects
uint32_t * num_cu_errors: Num of cu cmd objects which have error codes i.e negative return code

Return

XMA_SUCCESS on success

XMA_ERROR if a cu cmd has not completed yet

XmaCUCmdObj xma_plg_schedule_work_item(XmaSession s_handle, void *regmap, int32_t regmap_size, int32_t *return_code)¶: This function schedules a request to the XRT scheduler for execution of a kernel based on the supplied kernel register map Work items are processed in FIFO order. For dataflow kernels with channels work items for a given channel are processed in FIFO order. After calling xma_plg_schedule_work_item_with_args() one or more times, the caller can invoke xma_plg_is_work_item_done() to wait for one item of work to complete. pointer to regamp contains aruments to be supplied to kernel regmap must start from offset 0 of register map of a kernel

Parameters

XmaSession s_handle: The session handle associated with this plugin instance
void * regmap: pointer to register map to use for kernel arguments. regmap must start from offset 0 of register map of a kernel
int32_t regmap_size: Size of above regmap (in bytes) to copy
int32_t * return_code: XMA_SUCCESS or XMA_ERROR

Note

register map lock is not required before this call. So xma_plg_kernel_lock_regmap is not required before this call

Return

CuCmd Object

XMA_ERROR on failure

void *xma_plg_get_dev_handle(XmaSession s_handle)¶

Parameters

XmaSession s_handle: The session handle associated with this plugin instance

NOTE

This function will be removed in future

Return

Device handle or NULL