VVAS Buffer pool and Allocator¶
Buffer pool and buffer allocator are core elements of GStreamer framework. VVAS is based on Xilinx Run Time (XRT) framework to manage multi device solutions. For physically contiguous memory requirements, VVAS user XRT buffer allocator. To abstract the XRT related complexities, VVAS has developped GstVvasBufferPool and GstVvasAllocator plug-ins which are derived form the GStreamer base classes.
GstVvasBufferPool¶
The GStreamer VVAS buffer pool holds the pool of video frames allocated using the GStreamer allocator object. It is derived from the GStreamer base video buffer pool object (GstVideoBufferPool).
The VVAS buffer pool:
Allocates buffers with stride and height alignment requirements. (e.g., the video codec unit (VCU) requires the stride to be aligned with 256 bytes and the height aligned with 64 bytes)
Provides a callback to the GStreamer plug-in when the buffer comes back to the pool after it is used.
The following API is used to create the buffer pool.
GstBufferPool * gst_vvas_buffer_pool_new (guint stride_align, guint elevation_align)
Parameters:
stride_align - stride alignment required
elevation_align - height alignment required
Return:
GstBufferPool object handle
Plug-ins can use the following API to set the callback function on the VVAS buffer pool and the callback function is called when the buffer arrives back to the pool after it is used.
Buffer release callback function pointer declaration:
typedef void (* ReleaseBufferCallback)(GstBuffer * buf, gpointer user_data);
void gst_vvas_buffer_pool_set_release_buffer_cb (GstVvasBufferPool * xpool,
ReleaseBufferCallback release_buf_cb, gpointer user_data)
Parameters:
xpool - VVAS buffer pool created using gst_vvas_buffer_pool_new
release_buf_cb - function pointer of callback
user_data - user provided handle to be sent as function argument while
calling release_buf_cb()
Return:
None
GstVvasAllocator¶
The GStreamer VVAS allocator object is derived from an open source GstAllocator object designed for allocating memory using XRT APIs. The VVAS allocator is the backbone to the VVAS framework achieving zero-copy (wherever possible).
Allocator APIs¶
GStreamer plug-in developers can use the following APIs to interact with the VVAS allocator. To allocate memory using XRT, the GStreamer plug-ins and buffer pools require the GstAllocator object provided by the following API.
GstAllocator* gst_vvas_allocator_new (guint dev_idx, gboolean need_dma)
Parameters:
dev_idx - FPGA Device index on which memory is going to allocated
need_dma - will decide memory allocated is dmabuf or not
Return:
GstAllocator handle on success or NULL on failure
Note
In PCIe platforms, the DMA buffer allocation support is not available. This means that the need_dma argument to gst_vvas_allocator_new() API must be false.
Use the following API to check if a particular GstMemory object is allocated using GstVvasAlloctor.
gboolean gst_is_vvas_memory (GstMemory * mem)
Parameters:
mem - memory to be validated
Return:
true if memory is allocated using VVAS Allocator or false
When GStreamer plug-ins are interacting with hard-kernel/IP or soft-kernel, the plug-ins need physical memory addresses on an FPGA using the following API.
guint64 gst_vvas_allocator_get_paddr (GstMemory * mem)
Parameters:
mem - memory to get physical address
Return:
valid physical address on FPGA device or 0 on failure
Use the following API when plug-ins need an XRT buffer object (BO) corresponding to an VVAS memory object.
guint gst_vvas_allocator_get_bo (GstMemory * mem)
Parameters:
mem - memory to get XRT BO
Return:
valid XRT BO on success or 0 on failure