1.. _ptp_interface:
2
3Precision Time Protocol (PTP)
4#############################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13PTP is a network protocol implemented in the application layer, used to synchronize
14clocks in a computer network. It's accurate up to less than a microsecond.
15The stack supports the protocol and procedures as defined in the `IEEE 1588-2019 standard`_
16(IEEE Standard for a Precision Clock Synchronization Protocol
17for Networked Measurement and Control Systems). It has multiple profiles,
18and can be implemented on top of L2 (Ethernet) or L3 (UDP/IPv4 or UDP/IPv6).
19Its accuracy is achieved by using hardware timestamping of the protocol packets.
20
21Zephyr's implementation of PTP stack consist following items:
22
23* PTP stack thread that handles incoming messages and events
24* Integration with ptp_clock driver
25* PTP stack initialization executed during system init
26
27The implementation automatically creates PTP Ports (each PTP Port corresponds to unique interface).
28
29Supported features
30******************
31
32Implementation of the stack doesn't support all features specified in the standard.
33In the table below all supported features are listed.
34
35.. csv-table:: Supported features
36   :header: Feature, Supported
37   :widths: 50,10
38
39    Ordinary Clock, yes
40    Boundary Clock, yes
41    Transparent Clock,
42    Management Node,
43    End to end delay mechanism, yes
44    Peer to peer delay mechanism,
45    Multicast operation mode,
46    Hybrid operation mode,
47    Unicast operation mode,
48    Non-volatile storage,
49    UDP IPv4 transport protocol, yes
50    UDP IPv6 transport protocol, yes
51    IEEE 802.3 (Ethernet) transport protocol,
52    Hardware timestamping, yes
53    Software timestamping,
54    TIME_RECEIVER_ONLY PTP Instance, yes
55    TIME_TRANSMITTER_ONLY PTP Instance,
56
57Supported Management messages
58*****************************
59
60Based on Table 59 from section 15.5.2.3 of the IEEE 1588-2019 following management TLVs
61are supported:
62
63.. csv-table:: Supported management message's IDs
64   :header: Management_ID, Management_ID name, Allowed actions
65   :widths: 10,40,25
66
67    0x0000, NULL_PTP_MANAGEMENT, GET SET COMMAND
68    0x0001, CLOCK_DESCRIPTION, GET
69    0x0002, USER_DESCRIPTION, GET
70    0x0003, SAVE_IN_NON_VOLATILE_STORAGE, -
71    0x0004, RESET_NON_VOLATILE_STORAGE, -
72    0x0005, INITIALIZE, -
73    0x0006, FAULT_LOG, -
74    0x0007, FAULT_LOG_RESET, -
75    0x2000, DEFAULT_DATA_SET, GET
76    0x2001, CURRENT_DATA_SET, GET
77    0x2002, PARENT_DATA_SET, GET
78    0x2003, TIME_PROPERTIES_DATA_SET, GET
79    0x2004, PORT_DATA_SET, GET
80    0x2005, PRIORITY1, GET SET
81    0x2006, PRIORITY2, GET SET
82    0x2007, DOMAIN, GET SET
83    0x2008, TIME_RECEIVER_ONLY, GET SET
84    0x2009, LOG_ANNOUNCE_INTERVAL, GET SET
85    0x200A, ANNOUNCE_RECEIPT_TIMEOUT, GET SET
86    0x200B, LOG_SYNC_INTERVAL, GET SET
87    0x200C, VERSION_NUMBER, GET SET
88    0x200D, ENABLE_PORT, COMMAND
89    0x200E, DISABLE_PORT, COMMAND
90    0x200F, TIME, GET SET
91    0x2010, CLOCK_ACCURACY, GET SET
92    0x2011, UTC_PROPERTIES, GET SET
93    0x2012, TRACEBILITY_PROPERTIES, GET SET
94    0x2013, TIMESCALE_PROPERTIES, GET SET
95    0x2014, UNICAST_NEGOTIATION_ENABLE, -
96    0x2015, PATH_TRACE_LIST, -
97    0x2016, PATH_TRACE_ENABLE, -
98    0x2017, GRANDMASTER_CLUSTER_TABLE, -
99    0x2018, UNICAST_TIME_TRANSMITTER_TABLE, -
100    0x2019, UNICAST_TIME_TRANSMITTER_MAX_TABLE_SIZE, -
101    0x201A, ACCEPTABLE_TIME_TRANSMITTER_TABLE, -
102    0x201B, ACCEPTABLE_TIME_TRANSMITTER_TABLE_ENABLED, -
103    0x201C, ACCEPTABLE_TIME_TRANSMITTER_MAX_TABLE_SIZE, -
104    0x201D, ALTERNATE_TIME_TRANSMITTER, -
105    0x201E, ALTERNATE_TIME_OFFSET_ENABLE, -
106    0x201F, ALTERNATE_TIME_OFFSET_NAME, -
107    0x2020, ALTERNATE_TIME_OFFSET_MAX_KEY, -
108    0x2021, ALTERNATE_TIME_OFFSET_PROPERTIES, -
109    0x3000, EXTERNAL_PORT_CONFIGURATION_ENABLED,
110    0x3001, TIME_TRANSMITTER_ONLY, -
111    0x3002, HOLDOVER_UPGRADE_ENABLE, -
112    0x3003, EXT_PORT_CONFIG_PORT_DATA_SET, -
113    0x4000, TRANSPARENT_CLOCK_DEFAULT_DATA_SET, -
114    0x4001, TRANSPARENT_CLOCK_PORT_DATA_SET, -
115    0x4002, PRIMARY_DOMAIN, -
116    0x6000, DELAY_MECHANISM, GET
117    0x6001, LOG_MIN_PDELAY_REQ_INTERVAL, GET SET
118
119Enabling the stack
120******************
121
122The following configuration option must me enabled in :file:`prj.conf` file.
123
124- :kconfig:option:`CONFIG_PTP`
125
126Testing
127*******
128
129The stack has been informally tested using the
130`Linux ptp4l <http://linuxptp.sourceforge.net/>`_ daemons.
131The :zephyr:code-sample:`PTP sample application <ptp>` from the Zephyr
132source distribution can be used for testing.
133
134.. _IEEE 1588-2019 standard:
135   https://standards.ieee.org/ieee/1588/6825/
136
137API Reference
138*************
139
140.. doxygengroup:: ptp
141