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