doc: net: ptp: Add PTP library documentation
Add documentation page for IEEE 1588-2019 (PTP) library. Signed-off-by: Adam Wojasinski <awojasinski@baylibre.com>
This commit is contained in:
Adam Wojasinski
Anas Nashif
parent
08689e1a20
commit
4a989b736e
3 changed files with 142 additions and 0 deletions
|
|
@ -15,4 +15,5 @@ Protocols
|
|||
lwm2m
|
||||
mqtt
|
||||
mqtt_sn
|
||||
ptp
|
||||
tftp
|
||||
|
|
|
|||
140
doc/connectivity/networking/api/ptp.rst
Normal file
140
doc/connectivity/networking/api/ptp.rst
Normal file
|
|
@ -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 <http://linuxptp.sourceforge.net/>`_ daemons.
|
||||
The :zephyr:code-sample:`PTP sample application <ptp>` 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
|
||||
|
|
@ -9,3 +9,4 @@ Time Sensitive Networking
|
|||
gptp.rst
|
||||
net_time.rst
|
||||
ptp_time.rst
|
||||
ptp.rst
|
||||
|
|
|
|||
Loading…
Reference in a new issue