Migration from Legacy XMA¶
Summary of changes¶
Plugin code Migration¶
Plugin Structure Change¶
The following changes have been incorporated in the main plugin structures:
.alloc_chanplugin function has been deprecated. The resource management should be done in the application level.
- The field
- The new field
In legacy XMA, the buffer creation process was complex. It was needed to specify all buffer properties such as buffer size, physical address, handle when creating the buffer.
In current XMA, the buffer creation process is simplified
A new type
- Works on
- Supports Device Only Buffer
- Now there is no need to pass physical address using
In legacy XMA the API
xma_plg_buffer_write was used to copy data from the host pointer followed by the DMA transfer.
In current XMA the API
xma_plg_buffer_write does not accept host pointer any longer. If desired, the user has to copy from the host pointer to the buffer. The API now only performs DMA transfer from host to device.
In legacy XMA, the API
xma_plg_buffer_read. used to copy data to the host pointer after DMA transfer.
In current XMA, the API
xma_plg_buffer_read does not accept host pointer any longer. If desired, the user has to copy from the buffer to the host pointer. The API now only performs DMA transfer from device to host.
In current XMA, the API
xma_plg_register_prep_write works directly on
XMASession instead of
XmaHwSession. This API has to be guarded between
Note: The API
xma_plg_register_prep_write is not needed if the new scheduling API
xma_plg_schedule_work_item_with_args is used.
In the current XMA, the kernel scheduling API
xma_plg_schedule_work_item has to be guarded between
Note: If using new scheduling API
xma_plg_schedule_work_item_with_args the above locking and unlocking APIs are not required.
Application Code Migration¶
XMA Initialize Function:
In legacy XMA, the API
xma_initlialize used to take YAML configuration file.
In current XMA, the usage of YAML file has been obsoleted. The API
xma_initlialize takes device information and XCLBIN through new datatype:
Expanded Plugin Properties¶
Plugin properties have been expanded in current XMA to contain more information.
For example, compare
XmaEncoderProperties between legacy and current XRT versions.
Now in current XMA, more fields have been added.
- Device index (Should be passed from the application level)
- Compute Unit index (Should be determined at the application level)
- Channel id (Each channel should be passed with unique id from the application level)
- DDR bank index (Set -1 if auto-detection is desired)
- Plugin lib path
List of details changes¶
- YAML configuration file is not used by XMA
- Resource management is not handled by XMA
- So channel_id for multi-channel kernels must be handled in host video application (like ffmpeg)
- channel_id is input to XMA in session_create API as part of the properties argument
- See XRM for resource management details
- MPSoC PL & soft kernels are supported in XMA
- Direct register read & write is not available
- DataFlow kernels are supported
- ZeroCopy support has changed. See below for details
- BufferObject added. See below for details
- XmaFrame & XmaDataBuffer can use device buffers instead of host only memory
- Support for device_only buffers
- Session creation & destroy APIs are thread safe now
- Multi-process support is from XRT
- schedule_work_item API changed to return CUCmdObj
- New API xma_plg_schedule_cu_cmd & xma_plg_cu_cmd_status can be used instead of schedule_work_item
- In a session if using xma_plg_cu_cmd_status then do NOT use xma_plg_is_work_item_done in same session
- Supports up to 128 CUs per device
- CU register map size < 4KB
- By default XMA will automatically select default ddr bank for new device buffers (as per selected CU). Session_create may provide user selected default ddr bank input when XMA will use user select default ddr bank for plugin with that session
- For using ddr bank other than default session ddr_bank use APIs xma_plg_buffer_alloc_arg_num(). See below for info
- XMA now support multiple ddr bank per plugin. See below for info on xma_plg_buffer_alloc_arg_num()
- XMA version check API added to plugin struct. See below for details
- New session type XMA_ADMIN for non-video applications to control multiple CUs in single session. See below for details
- get_session_cmd_load(): Get CU command load of various sessions relative to each other. Printed to log file
- CU command load of all session is automatically sent to log file at end of the application
- This gives info on which sessions (or CUs) are more busy compared to other sessions (or CUs)
- QDMA platform: Host to kernel streams will be supported by XMA in future. See below for more details