path: root/ext/avtp/gstavtp.c

/*
 * GStreamer AVTP Plugin
 * Copyright (C) 2019 Intel Corporation
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later
 * version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301 USA
 */

/**
 * plugin-avtp:
 *
 * ## Audio Video Transport Protocol (AVTP) Plugin
 *
 * The AVTP plugin implements typical Talker and Listener functionalities that
 * can be leveraged by GStreamer-based applications in order to implement TSN
 * audio/video applications.
 *
 * ### Dependencies
 *
 * The plugin uses libavtp to handle AVTP packetization. Libavtp source code can
 * be found in https://github.com/AVnu/libavtp as well as instructions to build
 * and install it.
 *
 * If libavtp isn't detected by configure, the plugin isn't built.
 *
 * ### The application/x-avtp mime type
 *
 * For valid AVTPDUs encapsulated in GstBuffers, we use the caps with mime type
 * application/x-avtp.
 *
 * AVTP mime type is pretty simple and has no fields.
 *
 * ### gPTP Setup
 *
 * The Linuxptp project provides the ptp4l daemon, which synchronizes the PTP
 * clock from NIC, and the pmc tool which communicates with ptp4l to get/set
 * some runtime settings. The project also provides the phc2sys daemon which
 * synchronizes the PTP clock and system clock.
 *
 * The AVTP plugin requires system clock is synchronized with PTP clock and
 * TAI offset is properly set in the kernel. ptp4l and phc2sys can be set up
 * in many different ways, below we provide an example that fullfils the plugin
 * requirements. For further information check ptp4l(8) and phc2sys(8).
 *
 * In the following instructions, replace $IFNAME by your PTP capable NIC
 * interface. The gPTP.cfg file mentioned below can be found in /usr/share/
 * doc/linuxptp/ (depending on your distro).
 *
 * Synchronize PTP clock with PTP time:
 *
 *	$ ptp4l -f gPTP.cfg -i $IFNAME
 *
 * Enable TAI offset to be automatically set by phc2sys:
 *
 *	$ pmc -u -t 1 -b 0 'SET GRANDMASTER_SETTINGS_NP \
 * 		clockClass 248 clockAccuracy 0xfe \
 * 		offsetScaledLogVariance 0xffff \
 * 		currentUtcOffset 37 leap61 0 leap59 0 \
 * 		currentUtcOffsetValid 1 ptpTimescale 1 \
 * 		timeTraceable 1 frequencyTraceable 0 timeSource 0xa0'
 *
 * Synchronize system clock with PTP clock:
 *
 * 	$ phc2sys -f gPTP.cfg -s $IFNAME -c CLOCK_REALTIME -w
 *
 * The commands above should be run on both AVTP Talker and Listener hosts.
 *
 * With clocks properly synchronized, applications using the AVTP plugin
 * should use GstSytemClock with GST_CLOCK_TYPE_REALTIME as the pipeline
 * clock.
 *
 * ### Clock Reference Format (CRF)
 *
 * Even though the systems are synchronized by PTP, it is possible that
 * different talkers can send media streams which are out of phase or the
 * frequencies do not exactly match. This is partcularly important when there
 * is a single listener processing data from multiple talkers. The systems in
 * this scenario can benefit if a common clock is distributed among the
 * systems.
 *
 * This can be achieved by using the avtpcrfsync element which implements CRF
 * as described in Chapter 10 of IEEE 1722-2016. avtpcrfcheck can also be used
 * to validate that the adjustment conforms to the criteria specified in the
 * spec. For further details, look at the documentation for the respective
 * elements.
 *
 * ### Traffic Control Setup
 *
 * FQTSS (Forwarding and Queuing Enhancements for Time-Sensitive Streams) can be
 * enabled on Linux with the help of the mqprio and cbs qdiscs provided by the
 * Linux Traffic Control. Below we provide an example to configure those qdiscs
 * in order to transmit a CVF H.264 stream 1280x720@30fps. For further
 * information on how to configure these qdiscs check tc-mqprio(8) and
 * tc-cbs(8) man pages.
 *
 * On the host that will run as AVTP Talker (pipeline that generates the video
 * stream), run the following commands:
 *
 * Configure mpqrio qdisc (replace $MQPRIO_HANDLE_ID by an unused handle ID):
 *
 *     $ tc qdisc add dev $IFNAME parent root handle $MQPRIO_HANDLE_ID mqprio \
 *         num_tc 3 map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \
 *         queues 1@0 1@1 2@2 hw 0
 *
 * Configure cbs qdisc (replace $CBS_HANDLE_ID by an unused handle ID):
 *
 *     $ tc qdisc replace dev $IFNAME parent $MQPRIO_HANDLE_ID:1 \
 *         handle $CBS_HANDLE_ID cbs idleslope 27756 sendslope -972244 \
 *         hicredit 42 locredit -1499 offload 1
 *
 * Also, the plugin implements a transmission scheduling mechanism that relies
 * on ETF qdisc so make sure it is properly configured in your system. It could
 * be configured in many ways, below follows an example.
 *
 *     $ tc qdisc add dev $IFNAME parent $CBS_HANDLE_ID:1 etf \
 *         clockid CLOCK_TAI delta 500000 offload
 *
 * No Traffic Control configuration is required at the host running as AVTP
 * Listener.
 *
 * ### Capabilities
 *
 * The `avtpsink` and `avtpsrc` elements open `AF_PACKET` sockets, which require
 * `CAP_NET_RAW` capability. Therefore, applications must have that capability
 * in order to successfully use this element. For instance, one can use:
 *
 *     $ sudo setcap cap_net_raw+ep <application>
 *
 * Applications can drop this capability after the sockets are open, after
 * `avtpsrc` or `avtpsink` elements transition to PAUSED state. See setcap(8)
 * man page for more information.
 *
 * ### Elements configuration
 *
 * Each element has its own configuration properties, with some being common
 * to several elements. Basic properties are:
 *
 *   * streamid (avtpaafpay, avtpcvfpay, avtpaafdepay, avtpcvfdepay,
 *     avtpcrfsync, avtpcrfcheck): Stream ID associated with the stream.
 *
 *   * ifname (avtpsink, avtpsrc, avtpcrfsync, avtpcrfcheck): Network interface
 *     used to send/receive AVTP packets.
 *
 *   * dst-macaddr (avtpsink, avtpsrc): Destination MAC address for the stream.
 *
 *   * priority (avtpsink): Priority used by the plugin to transmit AVTP
 *     traffic.
 *
 *   * mtt (avtpaafpay, avtpcvfpay): Maximum Transit Time, in nanoseconds, as
 *     defined in AVTP spec.
 *
 *   * tu (avtpaafpay, avtpcvfpay): Maximum Time Uncertainty, in nanoseconds, as
 *     defined in AVTP spec.
 *
 *   * processing-deadline (avtpaafpay, avtpcvfpay, avtpsink): Maximum amount of
 *     time, in nanoseconds, that the pipeline is expected to process any
 *     buffer. This value should be in sync between the one used on the
 *     payloader and the sink, as this time is also taken into consideration to
 *     define the correct presentation time of the packets on the AVTP listener
 *     side. It should be as low as possible (zero if possible).
 *
 *   * timestamp-mode (avtpaafpay): AAF timestamping mode, as defined in AVTP spec.
 *
 *   * mtu (avtpcvfpay): Maximum Transmit Unit of the underlying network, used
 *     to determine when to fragment a CVF packet and how big it should be.
 *
 * Check each element documentation for more details.
 *
 *
 * ### Running a sample pipeline
 *
 * The following pipelines assume a hypothetical `-k ptp` flag that forces the
 * pipeline clock to be GstPtpClock. A real application would programmatically
 * define GstPtpClock as the pipeline clock (see next section). It is also
 * assumed that `gst-launch-1.0` has CAP_NET_RAW capability.
 *
 * On the AVTP talker, the following pipeline can be used to generate an H.264
 * stream to be sent via network using AVTP:
 *
 *     $ gst-launch-1.0 -k ptp videotestsrc is-live=true ! clockoverlay ! \
 *         x264enc ! avtpcvfpay processing-deadline=20000000 ! \
 *         avtpcrfsync ifname=$IFNAME ! avtpsink ifname=$IFNAME
 *
 * On the AVTP listener host, the following pipeline can be used to get the
 * AVTP stream, depacketize it and show it on the screen:
 *
 *     $ gst-launch-1.0 -k ptp avtpsrc ifname=$IFNAME ! \
 *         avtpcrfcheck ifname=$IFNAME ! avtpcvfdepay ! \
 *         vaapih264dec ! videoconvert ! clockoverlay halignment=right ! \
 *         queue ! autovideosink
 *
 * ### Pipeline clock
 *
 * The AVTP plugin elements require that the pipeline clock is in sync with
 * the network PTP clock. As GStreamer has a GstPtpClock, using it should be
 * the simplest way of achieving that.
 *
 * However, as there's no way of forcing a clock to a pipeline using
 * gst-launch-1.0 application, even for quick tests, it's necessary to have
 * an application. One can refer to GStreamer "hello world" application,
 * remembering to set the pipeline clock to GstPtpClock before putting the
 * pipeline on "PLAYING" state. Some code like:
 *
 *     GstClock *clk = gst_ptp_clock_new("ptp-clock", 0);
 *     gst_clock_wait_for_sync(clk, GST_CLOCK_TIME_NONE);
 *     gst_pipeline_use_clock (GST_PIPELINE (pipeline), clk);
 *
 * Would do the trick.
 *
 * ### Disclaimer
 *
 * It's out of scope for the AVTP plugin to verify how it is invoked, should
 * a malicious software do it for Denial of Service attempts, or other
 * compromises attempts.
 *
 * Since: 1.18
 */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <gst/gst.h>

#include "gstavtpaafdepay.h"
#include "gstavtpaafpay.h"
#include "gstavtpcvfdepay.h"
#include "gstavtpcvfpay.h"
#include "gstavtpsink.h"
#include "gstavtpsrc.h"
#include "gstavtpcrfsync.h"
#include "gstavtpcrfcheck.h"

static gboolean
plugin_init (GstPlugin * plugin)
{
  if (!gst_avtp_aaf_pay_plugin_init (plugin))
    return FALSE;
  if (!gst_avtp_aaf_depay_plugin_init (plugin))
    return FALSE;
  if (!gst_avtp_sink_plugin_init (plugin))
    return FALSE;
  if (!gst_avtp_src_plugin_init (plugin))
    return FALSE;
  if (!gst_avtp_cvf_pay_plugin_init (plugin))
    return FALSE;
  if (!gst_avtp_cvf_depay_plugin_init (plugin))
    return FALSE;
  if (!gst_avtp_crf_sync_plugin_init (plugin))
    return FALSE;
  if (!gst_avtp_crf_check_plugin_init (plugin))
    return FALSE;

  return TRUE;
}

GST_PLUGIN_DEFINE (GST_VERSION_MAJOR, GST_VERSION_MINOR,
    avtp, "Audio/Video Transport Protocol (AVTP) plugin",
    plugin_init, VERSION, GST_LICENSE, GST_PACKAGE_NAME, GST_PACKAGE_ORIGIN);