generic Precision Time Protocol (gPTP)

Overview

This gPTP stack supports the protocol and procedures as defined in the IEEE 802.1AS-2011 standard (Timing and Synchronization for Time-Sensitive Applications in Bridged Local Area Networks).

Supported features

The stack handles communications and state machines defined in the IEEE 802.1AS-2011 standard. Mandatory requirements for a full-duplex point-to-point link endpoint, as defined in Annex A of the standard, are supported.

The stack is in principle capable of handling communications on multiple network interfaces (also defined as “ports” in the standard) and thus act as a 802.1AS bridge. However, this mode of operation has not been validated on the Zephyr OS.

Supported hardware

Although the stack itself is hardware independent, Ethernet frame timestamping support must be enabled in ethernet drivers.

Boards supported:

Enabling the stack

The following configuration option must me enabled in prj.conf file.

Application interfaces

Only two Application Interfaces as defined in section 9 of the standard are available:

Testing

The stack has been informally tested using the OpenAVnu gPTP and Linux ptp4l daemons. The gPTP sample application from the Zephyr source distribution can be used for testing.

API Reference

group gptp

generic Precision Time Protocol (gPTP) support

Typedefs

typedef void (*gptp_phase_dis_callback_t)(uint8_t *gm_identity, uint16_t *time_base, struct gptp_scaled_ns *last_gm_ph_change, double *last_gm_freq_change)

Define callback that is called after a phase discontinuity has been sent by the grandmaster.

Parameters

  • uint8_t *gm_identity: A pointer to first element of a ClockIdentity array. The size of the array is GPTP_CLOCK_ID_LEN.

  • uint16_t *gm_time_base: A pointer to the value of timeBaseIndicator of the current grandmaster.

  • struct scaled_ns *last_gm_ph_change: A pointer to the value of lastGmPhaseChange received from grandmaster.

  • double *last_gm_freq_change: A pointer to the value of lastGmFreqChange received from the grandmaster.

typedef void (*gptp_port_cb_t)(int port, struct net_if *iface, void *user_data)

Callback used while iterating over gPTP ports.

Parameters

  • port: Port number

  • iface: Pointer to network interface

  • user_data: A valid pointer to user data or NULL

Functions

void gptp_register_phase_dis_cb(struct gptp_phase_dis_cb *phase_dis, gptp_phase_dis_callback_t cb)

Register a phase discontinuity callback.

Parameters

  • phase_dis: Caller specified handler for the callback.

  • cb: Callback to register.

void gptp_unregister_phase_dis_cb(struct gptp_phase_dis_cb *phase_dis)

Unregister a phase discontinuity callback.

Parameters

  • phase_dis: Caller specified handler for the callback.

void gptp_call_phase_dis_cb(void)

Call a phase discontinuity callback function.

int gptp_event_capture(struct net_ptp_time *slave_time, bool *gm_present)

Get gPTP time.

Return

Error code. 0 if no error.

Parameters

  • slave_time: A pointer to structure where timestamp will be saved.

  • gm_present: A pointer to a boolean where status of the presence of a grand master will be saved.

char *gptp_sprint_clock_id(const uint8_t *clk_id, char *output, size_t output_len)

Utility function to print clock id to a user supplied buffer.

Return

Pointer to output buffer

Parameters

  • clk_id: Clock id

  • output: Output buffer

  • output_len: Output buffer len

void gptp_foreach_port(gptp_port_cb_t cb, void *user_data)

Go through all the gPTP ports and call callback for each of them.

Parameters

  • cb: User-supplied callback function to call

  • user_data: User specified data

struct gptp_domain *gptp_get_domain(void)

Get gPTP domain.

This contains all the configuration / status of the gPTP domain.

Return

Pointer to domain or NULL if not found.

void gptp_clk_src_time_invoke(struct gptp_clk_src_time_invoke_params *arg)

This interface is used by the ClockSource entity to provide time to the ClockMaster entity of a time-aware system.

Parameters

  • arg: Current state and parameters of the ClockSource entity.

struct gptp_hdr *gptp_get_hdr(struct net_pkt *pkt)

Return pointer to gPTP packet header in network packet.

Return

Pointer to gPTP header.

Parameters

  • pkt: Network packet (received or sent)

struct gptp_scaled_ns
#include <gptp.h>

Scaled Nanoseconds.

struct gptp_uscaled_ns
#include <gptp.h>

UScaled Nanoseconds.

struct gptp_port_identity
#include <gptp.h>

Port Identity.

struct gptp_flags
#include <gptp.h>
struct gptp_hdr
#include <gptp.h>
struct gptp_phase_dis_cb
#include <gptp.h>

Phase discontinuity callback structure.

Stores the phase discontinuity callback information. Caller must make sure that the variable pointed by this is valid during the lifetime of registration. Typically this means that the variable cannot be allocated from stack.

struct gptp_clk_src_time_invoke_params
#include <gptp.h>

ClockSourceTime.invoke function parameters.

Parameters passed by ClockSourceTime.invoke function.