libs/gst/net/gstptpclock.h

   1 /* GStreamer
   2  * Copyright (C) 2015 Sebastian Dröge <sebastian@centricular.com>
   3  *
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  18  * Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef __GST_PTP_CLOCK_H__
  22 #define __GST_PTP_CLOCK_H__
  23
  24 #include <gst/gst.h>
  25 #include <gst/gstsystemclock.h>
  26
  27 G_BEGIN_DECLS
  28
  29 #define GST_TYPE_PTP_CLOCK \
  30   (gst_ptp_clock_get_type())
  31 #define GST_PTP_CLOCK(obj) \
  32   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_PTP_CLOCK,GstPtpClock))
  33 #define GST_PTP_CLOCK_CLASS(klass) \
  34   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_PTP_CLOCK,GstPtpClockClass))
  35 #define GST_IS_PTP_CLOCK(obj) \
  36   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_PTP_CLOCK))
  37 #define GST_IS_PTP_CLOCK_CLASS(klass) \
  38   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_PTP_CLOCK))
  39
  40 typedef struct _GstPtpClock GstPtpClock;
  41 typedef struct _GstPtpClockClass GstPtpClockClass;
  42 typedef struct _GstPtpClockPrivate GstPtpClockPrivate;
  43
  44 /**
  45  * GstPtpClock:
  46  *
  47  * Opaque #GstPtpClock structure.
  48  */
  49 struct _GstPtpClock {
  50   GstSystemClock clock;
  51
  52   /*< private >*/
  53   GstPtpClockPrivate *priv;
  54
  55   gpointer _gst_reserved[GST_PADDING];
  56 };
  57
  58 /**
  59  * GstPtpClockClass:
  60  * @parent_class: parented to #GstSystemClockClass
  61  *
  62  * Opaque #GstPtpClockClass structure.
  63  */
  64 struct _GstPtpClockClass {
  65   GstSystemClockClass parent_class;
  66
  67   /*< private >*/
  68   gpointer _gst_reserved[GST_PADDING];
  69 };
  70
  71 /**
  72  * GST_PTP_CLOCK_ID_NONE:
  73  * PTP clock identification that can be passed to gst_ptp_init() to
  74  * automatically select one based on the MAC address of interfaces
  75  */
  76 #define GST_PTP_CLOCK_ID_NONE ((guint64) -1)
  77
  78 GST_EXPORT
  79 GType           gst_ptp_clock_get_type             (void);
  80
  81 GST_EXPORT
  82 gboolean        gst_ptp_is_supported               (void);
  83
  84 GST_EXPORT
  85 gboolean        gst_ptp_is_initialized             (void);
  86
  87 GST_EXPORT
  88 gboolean        gst_ptp_init                       (guint64 clock_id,
  89                                                     gchar ** interfaces);
  90 GST_EXPORT
  91 void            gst_ptp_deinit                     (void);
  92
  93 #define GST_PTP_STATISTICS_NEW_DOMAIN_FOUND           "GstPtpStatisticsNewDomainFound"
  94 #define GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED "GstPtpStatisticsBestMasterClockSelected"
  95 #define GST_PTP_STATISTICS_PATH_DELAY_MEASURED        "GstPtpStatisticsPathDelayMeasured"
  96 #define GST_PTP_STATISTICS_TIME_UPDATED               "GstPtpStatisticsTimeUpdated"
  97
  98 /**
  99  * GstPtpStatisticsCallback:
 100  * @domain: PTP domain identifier
 101  * @stats: New statistics
 102  * @user_data: Data passed to gst_ptp_statistics_callback_add()
 103  *
 104  * The statistics can be the following structures:
 105  *
 106  * GST_PTP_STATISTICS_NEW_DOMAIN_FOUND:
 107  * "domain"                G_TYPE_UINT          The domain identifier of the domain
 108  * "clock"                 GST_TYPE_CLOCK       The internal clock that is slaved to the
 109  *                                              PTP domain
 110  *
 111  * GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED:
 112  * "domain"                G_TYPE_UINT          The domain identifier of the domain
 113  * "master-clock-id"       G_TYPE_UINT64        PTP clock identifier of the selected master
 114  *                                              clock
 115  * "master-clock-port"     G_TYPE_UINT          PTP port number of the selected master clock
 116  * "grandmaster-clock-id"  G_TYPE_UINT64        PTP clock identifier of the grandmaster clock
 117  *
 118  * GST_PTP_STATISTICS_PATH_DELAY_MEASURED:
 119  * "domain"                G_TYPE_UINT          The domain identifier of the domain
 120  * "mean-path-delay-avg"   GST_TYPE_CLOCK_TIME  Average mean path delay
 121  * "mean-path-delay"       GST_TYPE_CLOCK_TIME  Latest mean path delay
 122  * "delay-request-delay"   GST_TYPE_CLOCK_TIME  Delay of DELAY_REQ / DELAY_RESP messages
 123  *
 124  * GST_PTP_STATISTICS_TIME_UPDATED:
 125  * "domain"                G_TYPE_UINT          The domain identifier of the domain
 126  * "mean-path-delay-avg"   GST_TYPE_CLOCK_TIME  Average mean path delay
 127  * "local-time"            GST_TYPE_CLOCK_TIME  Local time that corresponds to ptp-time
 128  * "ptp-time"              GST_TYPE_CLOCK_TIME  Newly measured PTP time at local-time
 129  * "estimated-ptp-time"    GST_TYPE_CLOCK_TIME  Estimated PTP time based on previous measurements
 130  * "discontinuity"         G_TYPE_INT64         Difference between estimated and measured PTP time
 131  * "synced"                G_TYPE_BOOLEAN       Currently synced to the remote clock
 132  * "r-squared"             G_TYPE_DOUBLE        R² of clock estimation regression
 133  * "internal-time"         GST_TYPE_CLOCK_TIME  Internal time clock parameter
 134  * "external-time"         GST_TYPE_CLOCK_TIME  External time clock parameter
 135  * "rate-num"              G_TYPE_UINT64        Internal/external rate numerator
 136  * "rate-den"              G_TYPE_UINT64        Internal/external rate denominator
 137  * "rate"                  G_TYPE_DOUBLE        Internal/external rate
 138  *
 139  * If %FALSE is returned, the callback is removed and never called again.
 140  *
 141  */
 142 typedef gboolean  (*GstPtpStatisticsCallback)      (guint8 domain,
 143                                                     const GstStructure * stats,
 144                                                     gpointer user_data);
 145 GST_EXPORT
 146 gulong          gst_ptp_statistics_callback_add    (GstPtpStatisticsCallback callback,
 147                                                     gpointer user_data, GDestroyNotify destroy_data);
 148 GST_EXPORT
 149 void            gst_ptp_statistics_callback_remove (gulong id);
 150
 151 GST_EXPORT
 152 GstClock*       gst_ptp_clock_new                  (const gchar *name,
 153                                                     guint domain);
 154
 155 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 156 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstPtpClock, gst_object_unref)
 157 #endif
 158
 159 G_END_DECLS
 160
 161 #endif /* __GST_PTP_CLOCK_H__ */
 162