subsys: net: lib: Implement Precision Time Protocol (PTP) Support #73713

awojasinski · 2024-06-04T10:07:54Z

This pull request introduces support for the Precision Time Protocol (PTP), enhancing time synchronization capabilities within the Zephyr. PTP is a protocol that allows precise clock synchronization between networked devices over packet-switched networks, such as Ethernet. This implementation is crucial for applications requiring high-precision timekeeping systems.

Key Features

IEEE 1588 Compliance: The implementation adheres to the IEEE 1588 standard for precision clock synchronization network protocols.
Flexible Configuration: Users can configure various parameters, such as the PTP clock parameters, ports, transport protocol through Kconfig symbols.
Integration with Networking Stack via BSD Sockets API
Support for IPv4 and IPv6
PTP Slave Mode: The implementation supports both PTP slave modes, enabling devices to act as time followers in a network.

Testing

The implementation has been tested with linuxptp Project on nucleo_h563zi - Nucleo H563ZI development board. Additionally sample has been validated on native_sim target executed in docker image with net-tools.

The Pull Request could be split into two PRs. Following commits could be added as a separate PR:

However these changes are small compared to the rest of submitted code. In this PR it's clear why these commits are needed therefor I decided to included them in this PR.

aescolar · 2024-06-04T10:47:58Z

samples/net/ptp/sample.yaml

+      - native_posix
+      - native_posix/native/64
+      - native_sim
+      - native_sim/native/64


If you allow the 64 bit versions, I guess you also need a configuration overlay for them, or?

carlescufi · 2024-06-04T12:57:48Z

Thanks for the PR!

Question, how does this related to the gPTP implementation we have as an L2 here:
https://github.com/zephyrproject-rtos/zephyr/tree/main/subsys/net/l2/ethernet/gptp

awojasinski · 2024-06-04T13:18:31Z

@carlescufi gPTP is just a subset of PTP, it works only on L2. You may consider it as one of PTP profiles. Whereas PTP supports L2 Ethernet, UDP IPv4 and IPv6, and even CAN. It has predefined profiles that target different use cases. This PR brings only part of features but in the future it can be extended and gPTP could be replaced with PTP and Kconfig symbol that configures PTP stack to be compliant with gPTP standard.

If you look at ptp4l it implements gPTP as well. It's just a matter of passing proper .cfg file.

Currently main advantage of the PTP over gPTP is IP support

jukkar

There is lot of commits and it might make sense to split the PR to two, first the enabling / infra non-ptp related commits, and the other with PTP specific stuff. Currently this is hard to review properly.
While I was reviewing and commenting the code, you submitted a new version so some of my comments might not be valid any more.

jukkar · 2024-06-06T06:38:37Z

subsys/net/lib/ptp/Kconfig

+# Copyright (c) 2024 BayLibre
+# SPDX-License-Identifier: Apache-2.0
+
+menuconfig PTP


I think we should add here a !dependency to gPTP so both cannot be enabled at the same time.

jukkar · 2024-06-06T06:41:44Z

subsys/net/lib/ptp/ddt.h

+ * @note 5.3.3 - timestamp with respect to epoch
+ */
+struct ptp_timestamp {
+	/* Seconds encoded on 48 bits. */


Please add doxygen comments to all the fields in the structs as otherwise the generated documentation looks weird. Please check all the struct comments in this and other header files in this PR.

jukkar · 2024-06-06T06:54:41Z

subsys/net/lib/ptp/ddt.h

+	struct ptp_text	    name;
+	struct ptp_text	    value;
+	struct ptp_text	    desc;


Is this really going to work properly as you have now multiple flexible members in a one struct? How is the compiler going to know where the name,value and desc structs will start because the sizeof(struct ptp_text) is 1?

This structure is defined in the standard. These struct ptp_text members are only containers for fault logs. You don't treat it as continuous space they are only pointers to some space where these values are stored.

But how you have specified them means that they are not pointers. The first flexible member name will indeed point to correct position, but the next one value will point to second byte in name because sizeof(name) is 1.
Note that what I am talking about here is related to how one access the value or desc field from C code, I am not talking about how the memory layout of the protocol message. So if you try to access the desc field using ptp_fault_record.desc, the value will be garbage even if the memory layout is correct. This can be highly confusing to the user.

jukkar · 2024-06-06T06:59:29Z

subsys/net/lib/ptp/Kconfig

+config PTP_SLAVE_ONLY
+	bool "Configure Clock as slaveOnly PTP Instance"
+	depends on PTP_ORDINARY_CLOCK
+	default n


No need to mention default n as that is the default

jukkar · 2024-06-06T07:01:28Z

subsys/net/lib/ptp/msg.c

+	msg->ref--;
+	if (msg->ref) {


This is not atomic. Perhaps it should?

jukkar · 2024-06-06T07:12:18Z

subsys/net/lib/ptp/transport.c

+	};
+
+	socket = transport_socket_open(iface, (struct sockaddr *)&addr);
+


jukkar · 2024-06-06T07:14:16Z

subsys/net/lib/ptp/transport.c

+		if (IS_ENABLED(CONFIG_PTP_UDP_IPv4_PROTOCOL)) {
+			m_addr.sa_family = AF_INET;
+			net_sin(&m_addr)->sin_port = htons(port);
+			net_sin(&m_addr)->sin_addr.s_addr = mcast_addr.s_addr;
+
+		} else if (IS_ENABLED(CONFIG_PTP_UDP_IPv6_PROTOCOL)) {


I think this needs to be runtime configurable, so we should allow for example one interface to have IPv4, one IPv6 etc.

agree, in the future I could implement something that would allow to specify protocol per port but for now I would like to proceed with one protocol for all ports.

jukkar · 2024-06-06T07:15:02Z

subsys/net/lib/ptp/transport.c

+	msghdr.msg_controllen = sizeof(ctrl);
+
+	cnt = zsock_recvmsg(port->socket[idx], &msghdr, ZSOCK_MSG_DONTWAIT);
+


empty line can be omitted

jukkar · 2024-06-06T07:18:55Z

subsys/net/lib/ptp/clock.c

+	}
+
+	switch (mgmt->id) {
+	case PTP_MGMT_CLOCK_DESCRIPTION:


I think you need to add __fallthrough; after each case if we do not break

jukkar · 2024-06-06T07:21:10Z

subsys/net/lib/ptp/port.c

+				return PTP_EVT_FAULT_DETECTED;
+			}
+		}
+		/* fall through */


Use __fallthrough; instead of this comment

Add dynamic memory allocation for PTP messages. Memory allocation is done with Zephyr's memory slab. It's size can be configured with `PTP_MSG_POLL_SIZE` Kconfig symbol. Signed-off-by: Adam Wojasinski <[email protected]>

Add functions preparing messages to network byte order before sending and changing to host byte order after reception and before processing by PTP stack. Signed-off-by: Adam Wojasinski <[email protected]>

Add allocation of container used for TLVs and dummy functions for preparing correct byte order of data. TLV stands for Type, Length, Value, and it is extension of PTP messages that's used to transmit extra information. This data is attached at the end of PTP message. Signed-off-by: Adam Wojasinski <[email protected]>

This commit adds handling of Management TLVs Signed-off-by: Adam Wojasinski <[email protected]>

This commit introduces module responsible for sending and receiving messages. It is based on BSD Sockets API. Signed-off-by: Adam Wojasinski <[email protected]>

Based on Port ID decision about message processing can be made. Signed-off-by: Adam Wojasinski <[email protected]>

Foreign timeTransmitters are other PTP Clocks in a domain. They announce their parameters via announce messages. PTP Ports should record these foreign timeTransmitters. Signed-off-by: Adam Wojasinski <[email protected]>

Initial implementation of the clock adjustment and delay calculation. Timestamp values used for calculations will be obtained from proper PTP messages (Sync, Follow_Up, Delay_Req, and Delay_Resp) Signed-off-by: Adam Wojasinski <[email protected]>

This commit adds routines for handling incoming messages needed for correct operation of the PTP stack in end to end mode with multicast operation mode. Signed-off-by: Adam Wojasinski <[email protected]>

Add handler for STATE_DECISION_EVENT it consists of following routines: - state decision algorithm - best timeTransmitter clock algorithm - data sets comparison algorithm Based on IEEE 1588-2019 section 9.3.3 Signed-off-by: Adam Wojasinski <[email protected]>

Introduction of routines processing received PTP Management messages. The processing is split into clock-oriented and port-oriented parts. Signed-off-by: Adam Wojasinski <[email protected]>

This commit introduces routines for PTP message transmission. It includes transmission of three types of messages (Announce, Sync, Delay_Req) that should be send periodically depending on the PTP Port's state. Signed-off-by: Adam Wojasinski <[email protected]>

Timers are used to trigger message transmission and detect inactivity of other PTP Clocks what should result in an action of the PTP Port. Signed-off-by: Adam Wojasinski <[email protected]>

The commit adds functions that enable and disable PTP Port. This is going to be used by event handling routine. Signed-off-by: Adam Wojasinski <[email protected]>

Introduction of PTP stack's core functions responsible for event generation and handling of these events. Events are generated base on timeouts and/or PTP messages received via BSD sockets assigned to a specific PTP Port. These function will be used in PTP thread. Signed-off-by: Adam Wojasinski <[email protected]>

The STATE_DECISION_EVENT in PTP is a pivotal mechanism that facilitates dynamic state management within the protocol, allowing devices to adapt their operational states based on the BTCA's recommendations and the health of the network. Signed-off-by: Adam Wojasinski <[email protected]>

This commit adds implementation of the PTP thread that will poll sockets descriptors and PTP Port's timeres for timeouts, generate events and handle them and trigger STATE_DECISION_EVENT handling when needed. Signed-off-by: Adam Wojasinski <[email protected]>

Adding network interface status monitor function. Depending on the interface operation state and change of the state events are generated and handled by the function. Signed-off-by: Adam Wojasinski <[email protected]>

Add documentation page for IEEE 1588-2019 (PTP) library. Signed-off-by: Adam Wojasinski <[email protected]>

Add conditions to enable ptp_clock driver implementation for native_posix when PTP subsystem is enabled. Signed-off-by: Adam Wojasinski <[email protected]>

This application demonstrates PTP functionality Signed-off-by: Adam Wojasinski <[email protected]>

Introducing a new PTP maintenance entry with awojasinski as maintainer. Signed-off-by: Adam Wojasinski <[email protected]>

awojasinski · 2024-06-12T08:27:17Z

Pushed rebased branch to pull in fix for failing test

awojasinski requested review from aescolar and daor-oti as code owners June 4, 2024 10:07

zephyrbot added area: Ethernet area: Sockets Networking sockets area: Networking platform: STM32 ST Micro STM32 area: Samples Samples area: native port Host native arch port (native_sim) labels Jun 4, 2024

zephyrbot requested review from ajarmouni-st, decsny, erwango, FRASTM, gautierg-st, jukkar, kartben, lmajewski, nashif, pdgendt, rlubos, ssharks and tbursztyka June 4, 2024 10:08

zephyrbot assigned rlubos Jun 4, 2024

aescolar reviewed Jun 4, 2024

View reviewed changes

awojasinski force-pushed the ptp_upstream branch 2 times, most recently from 2932537 to 76e5f9c Compare June 5, 2024 09:43

zephyrbot added the area: Process label Jun 5, 2024

awojasinski force-pushed the ptp_upstream branch from 76e5f9c to 61371fe Compare June 6, 2024 07:04

jukkar reviewed Jun 6, 2024

View reviewed changes

awojasinski added 22 commits June 12, 2024 10:25

net: ptp: Add PTP message allocation and management

97d6be1

Add dynamic memory allocation for PTP messages. Memory allocation is done with Zephyr's memory slab. It's size can be configured with `PTP_MSG_POLL_SIZE` Kconfig symbol. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Add byte order manipulation for PTP messages

f13b878

Add functions preparing messages to network byte order before sending and changing to host byte order after reception and before processing by PTP stack. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Extend TLV with Management TLVs

e948609

This commit adds handling of Management TLVs Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Add sockets to PTP stack

cd8cd5f

This commit introduces module responsible for sending and receiving messages. It is based on BSD Sockets API. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Add PTP Port ID comparison function

75888da

Based on Port ID decision about message processing can be made. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Add foreign timeTransmitter records

77475f3

Foreign timeTransmitters are other PTP Clocks in a domain. They announce their parameters via announce messages. PTP Ports should record these foreign timeTransmitters. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Implement PTP message processing for ports

268cef8

This commit adds routines for handling incoming messages needed for correct operation of the PTP stack in end to end mode with multicast operation mode. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Add management message processing

f304600

Introduction of routines processing received PTP Management messages. The processing is split into clock-oriented and port-oriented parts. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Add timers processing for PTP Port

5c022e6

Timers are used to trigger message transmission and detect inactivity of other PTP Clocks what should result in an action of the PTP Port. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Implement PTP Port enabling and disabling functions

2e450f6

The commit adds functions that enable and disable PTP Port. This is going to be used by event handling routine. Signed-off-by: Adam Wojasinski <[email protected]>

net: ptp: Network interface status check in PTP thread

92e9a28

Adding network interface status monitor function. Depending on the interface operation state and change of the state events are generated and handled by the function. Signed-off-by: Adam Wojasinski <[email protected]>

doc: net: ptp: Add PTP library documentation

f8738fd

Add documentation page for IEEE 1588-2019 (PTP) library. Signed-off-by: Adam Wojasinski <[email protected]>

drivers: eth: native: Align to support ptp_clock driver for PTP subsys

dc483f7

Add conditions to enable ptp_clock driver implementation for native_posix when PTP subsystem is enabled. Signed-off-by: Adam Wojasinski <[email protected]>

samples: net: ptp: Add sample for PTP

5801133

This application demonstrates PTP functionality Signed-off-by: Adam Wojasinski <[email protected]>

MAINTAINERS: ptp: Add PTP entry to the maintenance list

d6c510f

Introducing a new PTP maintenance entry with awojasinski as maintainer. Signed-off-by: Adam Wojasinski <[email protected]>

awojasinski force-pushed the ptp_upstream branch from e1a189d to d6c510f Compare June 12, 2024 08:26

awojasinski requested review from rlubos and jukkar June 12, 2024 11:58

npitre approved these changes Jun 12, 2024

View reviewed changes

rlubos approved these changes Jun 13, 2024

View reviewed changes

nashif merged commit f16d556 into zephyrproject-rtos:main Jun 13, 2024
25 checks passed

axelnxp mentioned this pull request Aug 20, 2024

net: socket: recvmsg() doesn't update msg_controllen accordingly #77303

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

subsys: net: lib: Implement Precision Time Protocol (PTP) Support #73713

subsys: net: lib: Implement Precision Time Protocol (PTP) Support #73713

awojasinski commented Jun 4, 2024

aescolar Jun 4, 2024

carlescufi commented Jun 4, 2024

awojasinski commented Jun 4, 2024

jukkar left a comment

jukkar Jun 6, 2024

jukkar Jun 6, 2024

jukkar Jun 6, 2024

awojasinski Jun 6, 2024

jukkar Jun 6, 2024

jukkar Jun 6, 2024 •

edited

Loading

jukkar Jun 6, 2024

jukkar Jun 6, 2024

jukkar Jun 6, 2024

awojasinski Jun 6, 2024

jukkar Jun 6, 2024

jukkar Jun 6, 2024

jukkar Jun 6, 2024

awojasinski commented Jun 12, 2024

		};

		socket = transport_socket_open(iface, (struct sockaddr *)&addr);

		msghdr.msg_controllen = sizeof(ctrl);

		cnt = zsock_recvmsg(port->socket[idx], &msghdr, ZSOCK_MSG_DONTWAIT);

subsys: net: lib: Implement Precision Time Protocol (PTP) Support #73713

subsys: net: lib: Implement Precision Time Protocol (PTP) Support #73713

Conversation

awojasinski commented Jun 4, 2024

Key Features

Testing

Choose a reason for hiding this comment

carlescufi commented Jun 4, 2024

awojasinski commented Jun 4, 2024

jukkar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jukkar Jun 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

awojasinski commented Jun 12, 2024

jukkar Jun 6, 2024 •

edited

Loading