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 #include <gst/net/net-prelude.h>
  27
  28 G_BEGIN_DECLS
  29
  30 #define GST_TYPE_PTP_CLOCK \
  31   (gst_ptp_clock_get_type())
  32 #define GST_PTP_CLOCK(obj) \
  33   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_PTP_CLOCK,GstPtpClock))
  34 #define GST_PTP_CLOCK_CLASS(klass) \
  35   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_PTP_CLOCK,GstPtpClockClass))
  36 #define GST_IS_PTP_CLOCK(obj) \
  37   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_PTP_CLOCK))
  38 #define GST_IS_PTP_CLOCK_CLASS(klass) \
  39   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_PTP_CLOCK))
  40
  41 typedef struct _GstPtpClock GstPtpClock;
  42 typedef struct _GstPtpClockClass GstPtpClockClass;
  43 typedef struct _GstPtpClockPrivate GstPtpClockPrivate;
  44
  45 /**
  46  * GstPtpClock:
  47  *
  48  * Opaque #GstPtpClock structure.
  49  */
  50 struct _GstPtpClock {
  51   GstSystemClock clock;
  52
  53   /*< private >*/
  54   GstPtpClockPrivate *priv;
  55
  56   gpointer _gst_reserved[GST_PADDING];
  57 };
  58
  59 /**
  60  * GstPtpClockClass:
  61  * @parent_class: parented to #GstSystemClockClass
  62  *
  63  * Opaque #GstPtpClockClass structure.
  64  */
  65 struct _GstPtpClockClass {
  66   GstSystemClockClass parent_class;
  67
  68   /*< private >*/
  69   gpointer _gst_reserved[GST_PADDING];
  70 };
  71
  72 /**
  73  * GST_PTP_CLOCK_ID_NONE:
  74  * PTP clock identification that can be passed to gst_ptp_init() to
  75  * automatically select one based on the MAC address of interfaces
  76  */
  77 #define GST_PTP_CLOCK_ID_NONE ((guint64) -1)
  78
  79 GST_NET_API
  80 GType           gst_ptp_clock_get_type             (void);
  81
  82 GST_NET_API
  83 gboolean        gst_ptp_is_supported               (void);
  84
  85 GST_NET_API
  86 gboolean        gst_ptp_is_initialized             (void);
  87
  88 GST_NET_API
  89 gboolean        gst_ptp_init                       (guint64 clock_id,
  90                                                     gchar ** interfaces);
  91 GST_NET_API
  92 void            gst_ptp_deinit                     (void);
  93
  94 #define GST_PTP_STATISTICS_NEW_DOMAIN_FOUND           "GstPtpStatisticsNewDomainFound"
  95 #define GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED "GstPtpStatisticsBestMasterClockSelected"
  96 #define GST_PTP_STATISTICS_PATH_DELAY_MEASURED        "GstPtpStatisticsPathDelayMeasured"
  97 #define GST_PTP_STATISTICS_TIME_UPDATED               "GstPtpStatisticsTimeUpdated"
  98
  99 /**
 100  * GstPtpStatisticsCallback:
 101  * @domain: PTP domain identifier
 102  * @stats: New statistics
 103  * @user_data: Data passed to gst_ptp_statistics_callback_add()
 104  *
 105  * The statistics can be the following structures:
 106  *
 107  * GST_PTP_STATISTICS_NEW_DOMAIN_FOUND:
 108  * "domain"                G_TYPE_UINT          The domain identifier of the domain
 109  * "clock"                 GST_TYPE_CLOCK       The internal clock that is slaved to the
 110  *                                              PTP domain
 111  *
 112  * GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED:
 113  * "domain"                G_TYPE_UINT          The domain identifier of the domain
 114  * "master-clock-id"       G_TYPE_UINT64        PTP clock identifier of the selected master
 115  *                                              clock
 116  * "master-clock-port"     G_TYPE_UINT          PTP port number of the selected master clock
 117  * "grandmaster-clock-id"  G_TYPE_UINT64        PTP clock identifier of the grandmaster clock
 118  *
 119  * GST_PTP_STATISTICS_PATH_DELAY_MEASURED:
 120  * "domain"                G_TYPE_UINT          The domain identifier of the domain
 121  * "mean-path-delay-avg"   GST_TYPE_CLOCK_TIME  Average mean path delay
 122  * "mean-path-delay"       GST_TYPE_CLOCK_TIME  Latest mean path delay
 123  * "delay-request-delay"   GST_TYPE_CLOCK_TIME  Delay of DELAY_REQ / DELAY_RESP messages
 124  *
 125  * GST_PTP_STATISTICS_TIME_UPDATED:
 126  * "domain"                G_TYPE_UINT          The domain identifier of the domain
 127  * "mean-path-delay-avg"   GST_TYPE_CLOCK_TIME  Average mean path delay
 128  * "local-time"            GST_TYPE_CLOCK_TIME  Local time that corresponds to ptp-time
 129  * "ptp-time"              GST_TYPE_CLOCK_TIME  Newly measured PTP time at local-time
 130  * "estimated-ptp-time"    GST_TYPE_CLOCK_TIME  Estimated PTP time based on previous measurements
 131  * "discontinuity"         G_TYPE_INT64         Difference between estimated and measured PTP time
 132  * "synced"                G_TYPE_BOOLEAN       Currently synced to the remote clock
 133  * "r-squared"             G_TYPE_DOUBLE        R² of clock estimation regression
 134  * "internal-time"         GST_TYPE_CLOCK_TIME  Internal time clock parameter
 135  * "external-time"         GST_TYPE_CLOCK_TIME  External time clock parameter
 136  * "rate-num"              G_TYPE_UINT64        Internal/external rate numerator
 137  * "rate-den"              G_TYPE_UINT64        Internal/external rate denominator
 138  * "rate"                  G_TYPE_DOUBLE        Internal/external rate
 139  *
 140  * If %FALSE is returned, the callback is removed and never called again.
 141  *
 142  */
 143 typedef gboolean  (*GstPtpStatisticsCallback)      (guint8 domain,
 144                                                     const GstStructure * stats,
 145                                                     gpointer user_data);
 146 GST_NET_API
 147 gulong          gst_ptp_statistics_callback_add    (GstPtpStatisticsCallback callback,
 148                                                     gpointer user_data, GDestroyNotify destroy_data);
 149 GST_NET_API
 150 void            gst_ptp_statistics_callback_remove (gulong id);
 151
 152 GST_NET_API
 153 GstClock*       gst_ptp_clock_new                  (const gchar *name,
 154                                                     guint domain);
 155
 156 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 157 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstPtpClock, gst_object_unref)
 158 #endif
 159
 160 G_END_DECLS
 161
 162 #endif /* __GST_PTP_CLOCK_H__ */
 163