debugutils: clockselect, a pipeline that enables clock selection

Sometimes, one wants to force a clock on some pipelines - for instance,
when testing TSN related pipelines, one usually uses GstPtpClock or
CLOCK_REALTIME (assuming system realtime clock is in sync with network
one). Until now, one needs to write an application for that - not
difficult, but quite boring if one just wants to test something. This
patch presents a new element to help that: clockselect.

clockselect is a pipeline with two properties to select a clock. One
property, "clock-id", enables one to choose between "monotonic",
"realtime", "ptp" or "default" clock - where default keeps pipeline
behaviour of choosing a clock based on its elements. The other property,
"ptp-domain" gives one the choice of which PTP domain should be used.

Some very simple tests also added for this new element.

gst/debugutils/debugutilsbad.c

@@ -32,6 +32,7 @@ GType gst_error_ignore_get_type (void);
 GType gst_watchdog_get_type (void);
 GType gst_fake_video_sink_get_type (void);
 GType gst_test_src_bin_get_type (void);
+GType gst_clock_select_get_type (void);
 
 static gboolean
 plugin_init (GstPlugin * plugin)
@@ -54,6 +55,8 @@ plugin_init (GstPlugin * plugin)
       gst_fake_video_sink_get_type ());
   gst_element_register (plugin, "testsrcbin", GST_RANK_NONE,
       gst_test_src_bin_get_type ());
+  gst_element_register (plugin, "clockselect", GST_RANK_NONE,
+      gst_clock_select_get_type ());
 
   return TRUE;
 }

gst/debugutils/gstclockselect.c

@@ -0,0 +1,215 @@
+/* GStreamer
+ * Copyright (C) 2019 Intel Corporation
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 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
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 51 Franklin Street, Suite 500,
+ * Boston, MA 02110-1335, USA.
+ */
+/**
+ * SECTION:element-gstclockselect
+ *
+ * The clockselect element is a pipeline that enables one to choose its
+ * clock. By default, pipelines chose a clock depending on its elements,
+ * however the clockselect pipeline has some properties to force an
+ * arbitrary clock on it.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch-1.0 -v clockselect. \( clock-id=ptp domain=1 fakesrc ! fakesink \)
+ * ]|
+ * This example will create a pipeline and use the PTP clock with domain 1 on it.
+ * </refsect2>
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <gst/gst.h>
+#include <gst/net/net.h>
+#include "gstclockselect.h"
+
+GST_DEBUG_CATEGORY_STATIC (gst_clock_select_debug_category);
+#define GST_CAT_DEFAULT gst_clock_select_debug_category
+
+#define GST_TYPE_CLOCK_SELECT_CLOCK_ID (gst_clock_select_clock_id_get_type())
+static GType
+gst_clock_select_clock_id_get_type (void)
+{
+  static GType clock_id_type = 0;
+  static const GEnumValue clock_id_types[] = {
+    {GST_CLOCK_SELECT_CLOCK_ID_DEFAULT,
+        "Default (elected from elements) pipeline clock", "default"},
+    {GST_CLOCK_SELECT_CLOCK_ID_MONOTONIC, "System monotonic clock",
+        "monotonic"},
+    {GST_CLOCK_SELECT_CLOCK_ID_REALTIME, "System realtime clock", "realtime"},
+    {GST_CLOCK_SELECT_CLOCK_ID_PTP, "PTP clock", "ptp"},
+    {0, NULL, NULL},
+  };
+
+  clock_id_type =
+      g_enum_register_static ("GstClockSelectClockId", clock_id_types);
+
+  return clock_id_type;
+}
+
+/* prototypes */
+static void gst_clock_select_set_property (GObject * object,
+    guint property_id, const GValue * value, GParamSpec * pspec);
+static void gst_clock_select_get_property (GObject * object,
+    guint property_id, GValue * value, GParamSpec * pspec);
+
+static GstClock *gst_clock_select_provide_clock (GstElement * element);
+
+enum
+{
+  PROP_0,
+  PROP_CLOCK_ID,
+  PROP_PTP_DOMAIN
+};
+
+#define DEFAULT_CLOCK_ID GST_CLOCK_SELECT_CLOCK_ID_DEFAULT
+#define DEFAULT_PTP_DOMAIN 0
+
+/* class initialization */
+
+#define gst_clock_select_parent_class parent_class
+G_DEFINE_TYPE_WITH_CODE (GstClockSelect, gst_clock_select, GST_TYPE_PIPELINE,
+    GST_DEBUG_CATEGORY_INIT (gst_clock_select_debug_category, "clockselect", 0,
+        "debug category for clockselect element"));
+
+static void
+gst_clock_select_class_init (GstClockSelectClass * klass)
+{
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+  GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
+
+  gobject_class->set_property = gst_clock_select_set_property;
+  gobject_class->get_property = gst_clock_select_get_property;
+
+  g_object_class_install_property (gobject_class, PROP_CLOCK_ID,
+      g_param_spec_enum ("clock-id", "Clock ID", "ID of pipeline clock",
+          GST_TYPE_CLOCK_SELECT_CLOCK_ID, DEFAULT_CLOCK_ID,
+          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+  g_object_class_install_property (gobject_class, PROP_PTP_DOMAIN,
+      g_param_spec_uint ("ptp-domain", "PTP domain",
+          "PTP clock domain (meaningful only when Clock ID is PTP)",
+          0, G_MAXUINT8, DEFAULT_PTP_DOMAIN,
+          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+  gst_element_class_set_static_metadata (GST_ELEMENT_CLASS (klass),
+      "Clock select", "Generic/Bin", "Pipeline that enables different clocks",
+      "Ederson de Souza <ederson.desouza@intel.com>");
+
+  gstelement_class->provide_clock =
+      GST_DEBUG_FUNCPTR (gst_clock_select_provide_clock);
+}
+
+static void
+gst_clock_select_init (GstClockSelect * clock_select)
+{
+  clock_select->clock_id = DEFAULT_CLOCK_ID;
+  clock_select->ptp_domain = DEFAULT_PTP_DOMAIN;
+}
+
+static void
+gst_clock_select_set_property (GObject * object, guint property_id,
+    const GValue * value, GParamSpec * pspec)
+{
+  GstClockSelect *clock_select = GST_CLOCK_SELECT (object);
+
+  GST_DEBUG_OBJECT (clock_select, "set_property");
+
+  switch (property_id) {
+    case PROP_CLOCK_ID:
+      clock_select->clock_id = g_value_get_enum (value);
+      break;
+    case PROP_PTP_DOMAIN:
+      clock_select->ptp_domain = g_value_get_uint (value);
+      break;
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+      break;
+  }
+}
+
+static void
+gst_clock_select_get_property (GObject * object, guint property_id,
+    GValue * value, GParamSpec * pspec)
+{
+  GstClockSelect *clock_select = GST_CLOCK_SELECT (object);
+
+  GST_DEBUG_OBJECT (clock_select, "get_property");
+
+  switch (property_id) {
+    case PROP_CLOCK_ID:
+      g_value_set_enum (value, clock_select->clock_id);
+      break;
+    case PROP_PTP_DOMAIN:
+      g_value_set_uint (value, clock_select->ptp_domain);
+      break;
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+      break;
+  }
+}
+
+static GstClock *
+gst_clock_select_provide_clock (GstElement * element)
+{
+  GstClock *clock;
+  GstClockSelect *clock_select = GST_CLOCK_SELECT (element);
+
+  switch (clock_select->clock_id) {
+    case GST_CLOCK_SELECT_CLOCK_ID_MONOTONIC:
+      clock =
+          g_object_new (GST_TYPE_SYSTEM_CLOCK, "name", "DebugGstSystemClock",
+          NULL);
+      gst_object_ref_sink (clock);
+      gst_util_set_object_arg (G_OBJECT (clock), "clock-type", "monotonic");
+      break;
+    case GST_CLOCK_SELECT_CLOCK_ID_REALTIME:
+      clock =
+          g_object_new (GST_TYPE_SYSTEM_CLOCK, "name", "DebugGstSystemClock",
+          NULL);
+      gst_object_ref_sink (clock);
+      gst_util_set_object_arg (G_OBJECT (clock), "clock-type", "realtime");
+      break;
+    case GST_CLOCK_SELECT_CLOCK_ID_PTP:
+      clock = gst_ptp_clock_new ("ptp-clock", clock_select->ptp_domain);
+      if (!clock) {
+        GST_WARNING_OBJECT (clock_select,
+            "Failed to get PTP clock, falling back to pipeline default clock");
+      }
+      break;
+    case GST_CLOCK_SELECT_CLOCK_ID_DEFAULT:
+    default:
+      clock = NULL;
+  }
+
+  if (clock) {
+    GST_INFO_OBJECT (clock_select, "Waiting clock sync...");
+    gst_clock_wait_for_sync (clock, GST_CLOCK_TIME_NONE);
+    gst_pipeline_use_clock (GST_PIPELINE (clock_select), clock);
+    /* gst_pipeline_use_clock above ref's clock, as well as parent call
+     * below, so we don't need our reference anymore */
+    gst_object_unref (clock);
+  }
+
+  clock = GST_ELEMENT_CLASS (parent_class)->provide_clock (element);
+
+  return clock;
+}

gst/debugutils/gstclockselect.h

@@ -0,0 +1,61 @@
+/* GStreamer
+ * Copyright (C) 2019 Intel Corporation
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 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
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#ifndef _GST_CLOCK_SELECT_H_
+#define _GST_CLOCK_SELECT_H_
+
+#include <gst/gstpipeline.h>
+
+G_BEGIN_DECLS
+
+#define GST_TYPE_CLOCK_SELECT   (gst_clock_select_get_type())
+#define GST_CLOCK_SELECT(obj)   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_CLOCK_SELECT,GstClockSelect))
+#define GST_CLOCK_SELECT_CLASS(klass)   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_CLOCK_SELECT,GstClockSelectClass))
+#define GST_IS_CLOCK_SELECT(obj)   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_CLOCK_SELECT))
+#define GST_IS_CLOCK_SELECT_CLASS(obj)   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_CLOCK_SELECT))
+
+typedef struct _GstClockSelect GstClockSelect;
+typedef struct _GstClockSelectClass GstClockSelectClass;
+typedef enum _GstClockSelectClockId GstClockSelectClockId;
+
+enum _GstClockSelectClockId {
+  GST_CLOCK_SELECT_CLOCK_ID_DEFAULT,
+  GST_CLOCK_SELECT_CLOCK_ID_MONOTONIC,
+  GST_CLOCK_SELECT_CLOCK_ID_REALTIME,
+  GST_CLOCK_SELECT_CLOCK_ID_PTP,
+};
+
+struct _GstClockSelect
+{
+  GstPipeline base_clock_select;
+
+  GstClockSelectClockId clock_id;
+  guint8 ptp_domain;
+};
+
+struct _GstClockSelectClass
+{
+  GstPipelineClass base_clock_select_class;
+};
+
+GType gst_clock_select_get_type (void);
+
+G_END_DECLS
+
+#endif

gst/debugutils/meson.build

@@ -9,13 +9,14 @@ debugutilsbad_sources = [
   'gstfakevideosink.c',
   'gstwatchdog.c',
   'gsttestsrcbin.c',
+  'gstclockselect.c',
 ]
 
 gstdebugutilsbad = library('gstdebugutilsbad',
   debugutilsbad_sources,
   c_args : gst_plugins_bad_args,
   include_directories : [configinc],
-  dependencies : [gstbase_dep, gstvideo_dep],
+  dependencies : [gstbase_dep, gstvideo_dep, gstnet_dep],
   install : true,
   install_dir : plugins_install_dir,
 )

tests/check/elements/clockselect.c

@@ -0,0 +1,113 @@
+/*
+ * 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
+ */
+
+#include <gst/check/gstcheck.h>
+#include <gst/check/gstharness.h>
+
+GST_START_TEST (test_clock_select_realtime_clock)
+{
+  GstHarness *h;
+  GstElement *element;
+  GstClock *clock;
+  guint clock_type;
+
+  h = gst_harness_new_parse ("clockselect clock-id=realtime");
+
+  /* Check if element provides right clock */
+  element = gst_harness_find_element (h, "clockselect");
+  clock = gst_element_provide_clock (element);
+
+  fail_unless (GST_IS_SYSTEM_CLOCK (clock));
+  g_object_get (G_OBJECT (clock), "clock-type", &clock_type, NULL);
+  fail_unless_equals_uint64 (clock_type, GST_CLOCK_TYPE_REALTIME);
+
+  /* Unref this element to shut up valgrind. But it looks weird, maybe
+   * some funny harness bug due clockselect being a bin? */
+  gst_object_unref (element);
+  gst_object_unref (clock);
+  gst_harness_teardown (h);
+}
+
+GST_END_TEST;
+
+GST_START_TEST (test_clock_select_monotonic_clock)
+{
+  GstHarness *h;
+  GstElement *element;
+  GstClock *clock;
+  guint clock_type;
+
+  h = gst_harness_new_parse ("clockselect clock-id=monotonic");
+
+  /* Check if element provides right clock */
+  element = gst_harness_find_element (h, "clockselect");
+  clock = gst_element_provide_clock (element);
+
+  fail_unless (GST_IS_SYSTEM_CLOCK (clock));
+  g_object_get (G_OBJECT (clock), "clock-type", &clock_type, NULL);
+  fail_unless_equals_uint64 (clock_type, GST_CLOCK_TYPE_MONOTONIC);
+
+  /* See comment on test_clock_select_realtime_clock about this unref */
+  gst_object_unref (element);
+  gst_object_unref (clock);
+  gst_harness_teardown (h);
+}
+
+GST_END_TEST;
+
+GST_START_TEST (test_clock_select_properties)
+{
+  GstHarness *h;
+  GstElement *element;
+  guint clock_id, domain;
+
+  h = gst_harness_new_parse ("clockselect clock-id=ptp ptp-domain=2");
+
+  /* Check if all properties were properly set up */
+  element = gst_harness_find_element (h, "clockselect");
+  g_object_get (G_OBJECT (element), "clock-id", &clock_id, NULL);
+  fail_unless_equals_uint64 (clock_id, 3);
+
+  g_object_get (G_OBJECT (element), "ptp-domain", &domain, NULL);
+  fail_unless_equals_uint64 (domain, 2);
+
+  /* See comment on test_clock_select_realtime_clock about this unref */
+  gst_object_unref (element);
+  gst_harness_teardown (h);
+}
+
+GST_END_TEST;
+
+static Suite *
+clock_select_suite (void)
+{
+  Suite *s = suite_create ("clockselect");
+  TCase *tc_chain = tcase_create ("general");
+
+  suite_add_tcase (s, tc_chain);
+  tcase_add_test (tc_chain, test_clock_select_properties);
+  tcase_add_test (tc_chain, test_clock_select_monotonic_clock);
+  tcase_add_test (tc_chain, test_clock_select_realtime_clock);
+
+  return s;
+}
+
+GST_CHECK_MAIN (clock_select);

tests/check/meson.build

@@ -76,6 +76,7 @@ if host_machine.system() != 'windows'
     [['elements/ccconverter.c']],
     [['elements/cccombiner.c']],
     [['elements/ccextractor.c']],
+    [['elements/clockselect.c']],
     [['elements/line21.c']],
     [['elements/curlhttpsink.c'], not curl_dep.found(), [curl_dep]],
     [['elements/curlhttpsrc.c'], not curl_dep.found(), [curl_dep, gio_dep]],