avtp: Update documentation

1 files changed, 135 insertions, 0 deletions

diff --git a/ext/avtp/gstavtp.c b/ext/avtp/gstavtp.c
index e7c85a0a7..26d1d8713 100644
--- a/ext/avtp/gstavtp.c
+++ b/ext/avtp/gstavtp.c
@@ -43,6 +43,141 @@
  *
  * AVTP mime type is pretty simple and has no fields.
  *
+ * ### PTP Clock
+ *
+ * The AVTP plugin elements require that GStreamer pipeline clock be in sync
+ * with the network generalized PTP clock (gPTP). Applications using the AVTP
+ * plugin elements can achieve that by using GstPtpClock as the pipeline clock.
+ *
+ * Note that GstPtpClock is a UDP slave only clock, meaning that some other
+ * endpoint needs to provide the gPTP master clock.
+ *
+ * One can use, on another endpoint on the network, Linuxptp project ptp4l
+ * daemon to provide a gPTP master clock on the network over UDP:
+ *
+ *     $ ptp4l -i $IFNAME
+ *
+ * For further information check ptp4l(8).
+ *
+ * ### FQTSS 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 $HANDLE_ID by an unused handle ID):
+ *
+ *     $ tc qdisc add dev $IFNAME parent root handle $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:
+ *
+ *     $ tc qdisc replace dev $IFNAME parent $HANDLE_ID:1 cbs idleslope 27756 \
+ *         sendslope -972244 hicredit 42 locredit -1499 offload 1
+ *
+ * No FQTSS 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): Stream ID
+ *     associated with the stream.
+ *
+ *   * ifname (avtpsink, avtpsrc): 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).
+ *
+ *   * tstamp-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 ! \
+ *         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 ! 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.
+ *
  */
 #ifdef HAVE_CONFIG_H
 #include <config.h>