GstPtpClock

GstPtpClock — Special clock that synchronizes to a remote time provider via PTP (IEEE1588:2008).

Synopsis

#include <gst/net/net.h>

#define             GST_PTP_CLOCK_ID_NONE
gboolean            gst_ptp_init                        (guint64 clock_id,
                                                         gchar **interfaces);
void                gst_ptp_deinit                      (void);
gboolean            gst_ptp_is_initialized              (void);
gboolean            gst_ptp_is_supported                (void);
struct              GstPtpClock;
GstClock *          gst_ptp_clock_new                   (const gchar *name,
                                                         guint domain);
gboolean            (*GstPtpStatisticsCallback)         (guint8 domain,
                                                         const GstStructure *stats,
                                                         gpointer user_data);
gulong              gst_ptp_statistics_callback_add     (GstPtpStatisticsCallback callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy_data);
void                gst_ptp_statistics_callback_remove  (gulong id);
#define             GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED
#define             GST_PTP_STATISTICS_NEW_DOMAIN_FOUND
#define             GST_PTP_STATISTICS_PATH_DELAY_MEASURED
#define             GST_PTP_STATISTICS_TIME_UPDATED

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GstObject
               +----GstClock
                     +----GstSystemClock
                           +----GstPtpClock

Properties

  "domain"                   guint                 : Read / Write / Construct Only
  "grandmaster-clock-id"     guint64               : Read
  "internal-clock"           GstClock*             : Read
  "master-clock-id"          guint64               : Read

Description

GstPtpClock implements a PTP (IEEE1588:2008) ordinary clock in slave-only mode, that allows a GStreamer pipeline to synchronize to a PTP network clock in some specific domain.

The PTP subsystem can be initialized with gst_ptp_init(), which then starts a helper process to do the actual communication via the PTP ports. This is required as PTP listens on ports < 1024 and thus requires special privileges. Once this helper process is started, the main process will synchronize to all PTP domains that are detected on the selected interfaces.

gst_ptp_clock_new() then allows to create a GstClock that provides the PTP time from a master clock inside a specific PTP domain. This clock will only return valid timestamps once the timestamps in the PTP domain are known. To check this, you can use gst_clock_wait_for_sync(), the GstClock::synced signal and gst_clock_is_synced().

To gather statistics about the PTP clock synchronization, gst_ptp_statistics_callback_add() can be used. This gives the application the possibility to collect all kinds of statistics from the clock synchronization.

Details

GST_PTP_CLOCK_ID_NONE

#define GST_PTP_CLOCK_ID_NONE ((guint64) -1)

gst_ptp_init ()

gboolean            gst_ptp_init                        (guint64 clock_id,
                                                         gchar **interfaces);

Initialize the GStreamer PTP subsystem and create a PTP ordinary clock in slave-only mode for all domains on the given interfaces with the given clock_id.

If clock_id is GST_PTP_CLOCK_ID_NONE, a clock id is automatically generated from the MAC address of the first network interface.

This function is automatically called by gst_ptp_clock_new() with default parameters if it wasn't called before.

clock_id :

PTP clock id of this process' clock or GST_PTP_CLOCK_ID_NONE

interfaces :

network interfaces to run the clock on. [transfer none][array zero-terminated=1][allow-none]

Returns :

TRUE if the GStreamer PTP clock subsystem could be initialized.

Since 1.6


gst_ptp_deinit ()

void                gst_ptp_deinit                      (void);

Deinitialize the GStreamer PTP subsystem and stop the PTP clock. If there are any remaining GstPtpClock instances, they won't be further synchronized to the PTP network clock.

Since 1.6


gst_ptp_is_initialized ()

gboolean            gst_ptp_is_initialized              (void);

Check if the GStreamer PTP clock subsystem is initialized.

Returns :

TRUE if the GStreamer PTP clock subsystem is intialized.

Since 1.6


gst_ptp_is_supported ()

gboolean            gst_ptp_is_supported                (void);

Check if PTP clocks are generally supported on this system, and if previous initializations did not fail.

Returns :

TRUE if PTP clocks are generally supported on this system, and previous initializations did not fail.

Since 1.6


struct GstPtpClock

struct GstPtpClock;

Opaque GstPtpClock structure.


gst_ptp_clock_new ()

GstClock *          gst_ptp_clock_new                   (const gchar *name,
                                                         guint domain);

Creates a new PTP clock instance that exports the PTP time of the master clock in domain. This clock can be slaved to other clocks as needed.

If gst_ptp_init() was not called before, this will call gst_ptp_init() with default parameters.

This clock only returns valid timestamps after it received the first times from the PTP master clock on the network. Once this happens the GstPtpClock::internal-clock property will become non-NULL. You can check this with gst_clock_wait_for_sync(), the GstClock::synced signal and gst_clock_is_synced().

name :

Name of the clock

domain :

PTP domain

Since 1.6


GstPtpStatisticsCallback ()

gboolean            (*GstPtpStatisticsCallback)         (guint8 domain,
                                                         const GstStructure *stats,
                                                         gpointer user_data);

The statistics can be the following structures:

GST_PTP_STATISTICS_NEW_DOMAIN_FOUND: "domain" G_TYPE_UINT The domain identifier of the domain "clock" GST_TYPE_CLOCK The internal clock that is slaved to the PTP domain

GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED: "domain" G_TYPE_UINT The domain identifier of the domain "master-clock-id" G_TYPE_UINT64 PTP clock identifier of the selected master clock "master-clock-port" G_TYPE_UINT PTP port number of the selected master clock "grandmaster-clock-id" G_TYPE_UINT64 PTP clock identifier of the grandmaster clock

GST_PTP_STATISTICS_PATH_DELAY_MEASURED: "domain" G_TYPE_UINT The domain identifier of the domain "mean-path-delay-avg" GST_TYPE_CLOCK_TIME Average mean path delay "mean-path-delay" GST_TYPE_CLOCK_TIME Latest mean path delay "delay-request-delay" GST_TYPE_CLOCK_TIME Delay of DELAY_REQ / DELAY_RESP messages

GST_PTP_STATISTICS_TIME_UPDATED: "domain" G_TYPE_UINT The domain identifier of the domain "mean-path-delay-avg" GST_TYPE_CLOCK_TIME Average mean path delay "local-time" GST_TYPE_CLOCK_TIME Local time that corresponds to ptp-time "ptp-time" GST_TYPE_CLOCK_TIME Newly measured PTP time at local-time "estimated-ptp-time" GST_TYPE_CLOCK_TIME Estimated PTP time based on previous measurements "discontinuity" G_TYPE_INT64 Difference between estimated and measured PTP time "synced" G_TYPE_BOOLEAN Currently synced to the remote clock "r-squared" G_TYPE_DOUBLE R² of clock estimation regression "internal-time" GST_TYPE_CLOCK_TIME Internal time clock parameter "external-time" GST_TYPE_CLOCK_TIME External time clock parameter "rate-num" G_TYPE_UINT64 Internal/external rate numerator "rate-den" G_TYPE_UINT64 Internal/external rate denominator "rate" G_TYPE_DOUBLE Internal/external rate

If FALSE is returned, the callback is removed and never called again.

domain :

PTP domain identifier

stats :

New statistics

user_data :

Data passed to gst_ptp_statistics_callback_add()

gst_ptp_statistics_callback_add ()

gulong              gst_ptp_statistics_callback_add     (GstPtpStatisticsCallback callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy_data);

Installs a new statistics callback for gathering PTP statistics. See GstPtpStatisticsCallback for a list of statistics that are provided.

callback :

GstPtpStatisticsCallback to call

user_data :

Data to pass to the callback

destroy_data :

GDestroyNotify to destroy the data

Returns :

Id for the callback that can be passed to gst_ptp_statistics_callback_remove()

Since 1.6


gst_ptp_statistics_callback_remove ()

void                gst_ptp_statistics_callback_remove  (gulong id);

Removes a PTP statistics callback that was previously added with gst_ptp_statistics_callback_add().

id :

Callback id to remove

Since 1.6


GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED

#define GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED "GstPtpStatisticsBestMasterClockSelected"

GST_PTP_STATISTICS_NEW_DOMAIN_FOUND

#define GST_PTP_STATISTICS_NEW_DOMAIN_FOUND           "GstPtpStatisticsNewDomainFound"

GST_PTP_STATISTICS_PATH_DELAY_MEASURED

#define GST_PTP_STATISTICS_PATH_DELAY_MEASURED        "GstPtpStatisticsPathDelayMeasured"

GST_PTP_STATISTICS_TIME_UPDATED

#define GST_PTP_STATISTICS_TIME_UPDATED               "GstPtpStatisticsTimeUpdated"

Property Details

The "domain" property

  "domain"                   guint                 : Read / Write / Construct Only

The PTP domain.

Allowed values: <= 255

Default value: 0


The "grandmaster-clock-id" property

  "grandmaster-clock-id"     guint64               : Read

Grand Master Clock ID.

Default value: 0


The "internal-clock" property

  "internal-clock"           GstClock*             : Read

Internal clock.


The "master-clock-id" property

  "master-clock-id"          guint64               : Read

Master Clock ID.

Default value: 0

See Also

GstClock, GstNetClientClock, GstPipeline