diff --git a/doc/connectivity/networking/api/protocols.rst b/doc/connectivity/networking/api/protocols.rst index 57aeaae8d02..f4f3b1f88c1 100644 --- a/doc/connectivity/networking/api/protocols.rst +++ b/doc/connectivity/networking/api/protocols.rst @@ -15,4 +15,5 @@ Protocols lwm2m mqtt mqtt_sn + ptp tftp diff --git a/doc/connectivity/networking/api/ptp.rst b/doc/connectivity/networking/api/ptp.rst new file mode 100644 index 00000000000..8b0d8384393 --- /dev/null +++ b/doc/connectivity/networking/api/ptp.rst @@ -0,0 +1,140 @@ +.. _ptp_interface: + +Precision Time Protocol (PTP) +############################# + +.. contents:: + :local: + :depth: 2 + +Overview +******** + +PTP is a network protocol implemented in the application layer, used to synchronize +clocks in a computer network. It's accurate up to less than a microsecond. +The stack supports the protocol and procedures as defined in the `IEEE 1588-2019 standard`_ +(IEEE Standard for a Precision Clock Synchronization Protocol +for Networked Measurement and Control Systems). It has multiple profiles, +and can be implemented on top of L2 (Ethernet) or L3 (UDP/IPv4 or UDP/IPv6). +Its accuracy is achieved by using hardware timestamping of the protocol packets. + +Zephyr's implementation of PTP stack consist following items: + +* PTP stack thread that handles incoming messages and events +* Integration with ptp_clock driver +* PTP stack initialization executed during system init + +The implementation automatically creates PTP Ports (each PTP Port coresponds to unique interface). + +Supported features +****************** + +Implementation of the stack doesn't support all features specified in the standard. +In the table below all supported features are listed. + +.. csv-table:: Supported features + :header: Feature, Supported + :widths: 50,10 + + Ordinary Clock, yes + Boundary Clock, yes + Transparent Clock, + Management Node, + End to end delay mechanism, yes + Peer to peer delay mechanism, + Multicast operation mode, + Hybrid operation mode, + Unicast operation mode, + Non-volatile storage, + UDP IPv4 transport protocol, yes + UDP IPv6 transport protocol, yes + IEEE 802.3 (Ethernet) transport protocol, + Hardware timestamping, yes + Software timestamping, + TIME_RECEIVER_ONLY PTP Instance, yes + TIME_TRANSMITTER_ONLY PTP Instance, + +Supported Management messages +***************************** + +Based on Table 59 from section 15.5.2.3 of the IEEE 1588-2019 following management TLVs +are supported: + +.. csv-table:: Supported management message's IDs + :header: Management_ID, Management_ID name, Allowed acctions + :widths: 10,40,25 + + 0x0000, NULL_PTP_MANAGEMENT, GET SET COMMAND + 0x0001, CLOCK_DESCRIPTION, GET + 0x0002, USER_DESCRIPTION, GET + 0x0003, SAVE_IN_NON_VOLATILE_STORAGE, - + 0x0004, RESET_NON_VOLATILE_STORAGE, - + 0x0005, INITIALIZE, - + 0x0006, FAULT_LOG, - + 0x0007, FAULT_LOG_RESET, - + 0x2000, DEFAULT_DATA_SET, GET + 0x2001, CURRENT_DATA_SET, GET + 0x2002, PARENT_DATA_SET, GET + 0x2003, TIME_PROPERTIES_DATA_SET, GET + 0x2004, PORT_DATA_SET, GET + 0x2005, PRIORITY1, GET SET + 0x2006, PRIORITY2, GET SET + 0x2007, DOMAIN, GET SET + 0x2008, TIME_RECEIVER_ONLY, GET SET + 0x2009, LOG_ANNOUNCE_INTERVAL, GET SET + 0x200A, ANNOUNCE_RECEIPT_TIMEOUT, GET SET + 0x200B, LOG_SYNC_INTERVAL, GET SET + 0x200C, VERSION_NUMBER, GET SET + 0x200D, ENABLE_PORT, COMMAND + 0x200E, DISABLE_PORT, COMMAND + 0x200F, TIME, GET SET + 0x2010, CLOCK_ACCURACY, GET SET + 0x2011, UTC_PROPERTIES, GET SET + 0x2012, TRACEBILITY_PROPERTIES, GET SET + 0x2013, TIMESCALE_PROPERTIES, GET SET + 0x2014, UNICAST_NEGOTIATION_ENABLE, - + 0x2015, PATH_TRACE_LIST, - + 0x2016, PATH_TRACE_ENABLE, - + 0x2017, GRANDMASTER_CLUSTER_TABLE, - + 0x2018, UNICAST_TIME_TRANSMITTER_TABLE, - + 0x2019, UNICAST_TIME_TRANSMITTER_MAX_TABLE_SIZE, - + 0x201A, ACCEPTABLE_TIME_TRANSMITTER_TABLE, - + 0x201B, ACCEPTABLE_TIME_TRANSMITTER_TABLE_ENABLED, - + 0x201C, ACCEPTABLE_TIME_TRANSMITTER_MAX_TABLE_SIZE, - + 0x201D, ALTERNATE_TIME_TRANSMITTER, - + 0x201E, ALTERNATE_TIME_OFFSET_ENABLE, - + 0x201F, ALTERNATE_TIME_OFFSET_NAME, - + 0x2020, ALTERNATE_TIME_OFFSET_MAX_KEY, - + 0x2021, ALTERNATE_TIME_OFFSET_PROPERTIES, - + 0x3000, EXTERNAL_PORT_CONFIGURATION_ENABLED, + 0x3001, TIME_TRANSMITTER_ONLY, - + 0x3002, HOLDOVER_UPGRADE_ENABLE, - + 0x3003, EXT_PORT_CONFIG_PORT_DATA_SET, - + 0x4000, TRANSPARENT_CLOCK_DEFAULT_DATA_SET, - + 0x4001, TRANSPARENT_CLOCK_PORT_DATA_SET, - + 0x4002, PRIMARY_DOMAIN, - + 0x6000, DELAY_MECHANISM, GET + 0x6001, LOG_MIN_PDELAY_REQ_INTERVAL, GET SET + +Enabling the stack +****************** + +The following configuration option must me enabled in :file:`prj.conf` file. + +- :kconfig:option:`CONFIG_PTP` + +Testing +******* + +The stack has been informally tested using the +`Linux ptp4l `_ daemons. +The :zephyr:code-sample:`PTP sample application ` from the Zephyr +source distribution can be used for testing. + +.. _IEEE 1588-2019 standard: + https://standards.ieee.org/ieee/1588/6825/ + +API Reference +************* + +.. doxygengroup:: ptp diff --git a/doc/connectivity/networking/api/tsn.rst b/doc/connectivity/networking/api/tsn.rst index c9d00cfcc5c..276be30e230 100644 --- a/doc/connectivity/networking/api/tsn.rst +++ b/doc/connectivity/networking/api/tsn.rst @@ -9,3 +9,4 @@ Time Sensitive Networking gptp.rst net_time.rst ptp_time.rst + ptp.rst