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:
Native POSIX execution (native_posix) (only usable for simple testing, limited capabilities due to lack of hardware clock)
X86 Emulation (QEMU) (emulated, limited capabilities due to lack of hardware clock)
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:
ClockTargetPhaseDiscontinuity
interface (gptp_register_phase_dis_cb()
)ClockTargetEventCapture
interface (gptp_event_capture()
)
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
gm_identity – A pointer to first element of a ClockIdentity array. The size of the array is GPTP_CLOCK_ID_LEN.
time_base – A pointer to the value of timeBaseIndicator of the current grandmaster.
last_gm_ph_change – A pointer to the value of lastGmPhaseChange received from grandmaster.
last_gm_freq_change – A pointer to the value of lastGmFreqChange received from the grandmaster.
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_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>
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.
-
uint8_t
-
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.
-
sys_snode_t
-
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.
-
double
-
typedef void (*