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.

Param gm_identity:

A pointer to first element of a ClockIdentity array. The size of the array is GPTP_CLOCK_ID_LEN.

Param time_base:

A pointer to the value of timeBaseIndicator of the current grandmaster.

Param last_gm_ph_change:

A pointer to the value of lastGmPhaseChange received from grandmaster.

Param 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.

Param port:

Port number

Param iface:

Pointer to network interface

Param 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.

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.

Returns:

Error code. 0 if no error.

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.

Parameters:

  • clk_id – Clock id

  • output – Output buffer

  • output_len – Output buffer len

Returns:

Pointer to output buffer

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.

Returns:

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.

Parameters:

  • pkt – Network packet (received or sent)

Returns:

Pointer to gPTP header.

struct gptp_scaled_ns
#include <gptp.h>

Scaled Nanoseconds.

Public Members

int32_t high

High half.

int64_t low

Low half.

struct gptp_uscaled_ns
#include <gptp.h>

UScaled Nanoseconds.

Public Members

uint32_t high

High half.

uint64_t low

Low half.

struct gptp_port_identity
#include <gptp.h>

Port Identity.

Public Members

uint8_t clk_id[GPTP_CLOCK_ID_LEN]

Clock identity of the port.

uint16_t port_number

Number of the port.

struct gptp_flags
#include <gptp.h>

Public Members

uint8_t octets[2]

Byte access.

uint16_t all

Whole field access.

struct gptp_hdr
#include <gptp.h>

Public Members

uint8_t message_type

Type of the message.

uint8_t transport_specific

Transport specific, always 1.

uint8_t ptp_version

Version of the PTP, always 2.

uint8_t reserved0

Reserved field.

uint16_t message_length

Total length of the message from the header to the last TLV.

uint8_t domain_number

Domain number, always 0.

uint8_t reserved1

Reserved field.

struct gptp_flags flags

Message flags.

int64_t correction_field

Correction Field.

The content depends of the message type.

uint32_t reserved2

Reserved field.

struct gptp_port_identity port_id

Port Identity of the sender.

uint16_t sequence_id

Sequence Id.

uint8_t control

Control value.

Sync: 0, Follow-up: 2, Others: 5.

int8_t log_msg_interval

Message Interval in Log2 for Sync and Announce messages.

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.

Public Members

sys_snode_t node

Node information for the slist.

gptp_phase_dis_callback_t cb

Phase discontinuity callback.

struct gptp_clk_src_time_invoke_params
#include <gptp.h>

ClockSourceTime.invoke function parameters.

Parameters passed by ClockSourceTime.invoke function.

Public Members

double last_gm_freq_change

Frequency change on the last Time Base Indicator Change.

struct net_ptp_extended_time src_time

The time this function is invoked.

struct gptp_scaled_ns last_gm_phase_change

Phase change on the last Time Base Indicator Change.

uint16_t time_base_indicator

Time Base - changed only if Phase or Frequency changes.