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