Gst-nvdsudpsrc
================

The Gst-nvdsudpsrc plugin is a source type component which is used to receive the UDP-RTP packets from the network. Internally, the plugin uses `Rivermax` SDK APIs for network communications. NVIDIA Mellanox Rivermax® offers a unique IP-based solution for any media and data streaming use case – for more details - `Rivermax Product Page. <https://developer.nvidia.com/networking/rivermax>`_

Rivermax utilizes the kernel bypass technology and RDMA capabilities to achieve better CPU performance, low latency, and higher bandwidth. On top of `Rivermax` based enhancements, some of memory and buffer management optimization have been implemented to further reduce the CPU utilization in case of high packet rate use cases.

This component also supports RTP header and payload separation. RTP header and payloads can be received in separate memories. Header will always be in system memory while payload can directly be copied to GPU (Pinned) memory. This can avoid memory copies in cases when GPU processing is performed on the RTP payloads. Header and payload separation will happen only if “header-size” property is set to non-zero value and for fixed header size.

System can also have Gstreamer provided OSS implementation of udp source (``udpsrc``) component. In that case system would have two implementations for udp source - ``udpsrc`` and ``nvdsudpsrc``.
``nvdsudpsrc`` component can only be used with NVIDIA Mellanox ConnectX-5 and above cards after having installed ``Rivermax`` SDK and its license.

Download and setup the ``Rivermax`` 1.9.x SDK here: https://developer.nvidia.com/networking/rivermax-getting-started

``Rivermax`` license is needed – follow the instruction on the SDK page to obtain development license or purchase it here: https://store.mellanox.com/categories/ethernet/connectx-smartnics/rivermax-licenses.html.

To select ``nvdsudpsrc`` out of two installations, use either ``LOCAL_IFACE_IP`` environment variable or ``local-iface-ip`` property. Use the command below to export the environment variable: ::

     export LOCAL_IFACE_IP=<IP of Mellanox NIC>


``nvdsudpsrc`` component also requires ``CAP_NET_RAW`` capability. Either run the application that uses ``nvdsudpsrc`` component with superuser privilege or set the ``CAP_NET_RAW`` capabilities using the following command. ::

    sudo setcap CAP_NET_RAW=ep <absolute path of application>


for example: ::

     sudo setcap CAP_NET_RAW=ep /opt/nvidia/deepstream/deepstream/bin/deepstream-app

     sudo setcap CAP_NET_RAW=ep /usr/bin/gst-launch-1.0



.. image:: /content/DS_plugin_gst-nvdsudpsrc.png
         :align: center
         :alt: Gst-nvdsudpsrc


Inputs and Outputs
-------------------

* Inputs

  * None

* Control parameters

  *	LOCAL_IFACE_IP ENV flag or local-iface-ip property
  *	payload-size
  * header-size
  * num-packets
  *	uri
  *	address
  *	port

* Output

  * GstBufferList having RTP packets as buffer content.

Features
---------

The following table summarizes the features of the plugin.

.. csv-table:: Gst-nvdsudpsrc plugin features
  :file: ../text/tables/Gst-nvdsudpsrc tables/DS_Plugin_gst-nvdsudpsrc_features.csv
  :widths: 30, 30, 30
  :header-rows: 1

Gst Properties
----------------

The following table describes the Gst-nvdsudpsrc plugin’s Gst properties.

.. csv-table:: Gst-nvdsudpsrc plugin gst properties
  :file: ../text/tables/Gst-nvdsudpsrc tables/DS_Plugin_gst-nvdsudpsrc_gst-properties.csv
  :widths: 20, 20, 20, 20, 20
  :header-rows: 1