From df19cbe26be2ea8029c7bf97b67134dfd3b223a7 Mon Sep 17 00:00:00 2001
From: "Daniel P. Carvalho" <danieloak@gmail.com>
Date: Thu, 24 Sep 2026 11:31:11 -0300
Subject: [PATCH] netutils/ptpd: refuse to start when -H has no hardware
 timestamp support.

When ptpd runs over IEEE 802.3 (-2) with hardware timestamping and
ETHTOOL_GET_TS_INFO does not report SOF_TIMESTAMPING_TX_HARDWARE,
SOF_TIMESTAMPING_RX_HARDWARE and SOF_TIMESTAMPING_RAW_HARDWARE for the
interface, refuse to start instead of logging a warning and running in
software - the same way linuxptp/ptp4l refuses to start when hardware
timestamping is configured but not reported as supported by ethtool,
rather than silently degrading. The error message names the missing
capability and points to -S, and the usage text documents the
requirement.

Hardware RX timestamps are required as well: without them the receive
timestamps come from the system clock while the transmit ones come from
the MAC, and the two cannot be combined into a meaningful delay.

The check is limited to the 802.3 transport, the only one on which ptpd
retrieves hardware TX timestamps. -H is the default with
CONFIG_NET_TIMESTAMP, so applying it to the UDP transports would make a
plain "ptpd" refuse to start on any interface whose driver does not
report hardware timestamping, although it never needs that capability.

Assisted-by: Claude:claude-sonnet-5
Signed-off-by: Daniel P. Carvalho <danieloak@gmail.com>
---
 netutils/ptpd/ptpd.c    | 40 +++++++++++++++++++++++++++++++++-------
 system/ptpd/ptpd_main.c |  2 ++
 2 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/netutils/ptpd/ptpd.c b/netutils/ptpd/ptpd.c
index 2c0687f01..7353fe5eb 100644
--- a/netutils/ptpd/ptpd.c
+++ b/netutils/ptpd/ptpd.c
@@ -70,6 +70,15 @@
  * Pre-processor Definitions
  ****************************************************************************/
 
+/* Timestamping capabilities (ETHTOOL_GET_TS_INFO) the interface must
+ * report for hardware timestamping on the IEEE 802.3 transport, the same
+ * set linuxptp/ptp4l requires for 'time_stamping hardware'.
+ */
+
+#define PTP_HWTS_REQUIRED (SOF_TIMESTAMPING_TX_HARDWARE | \
+                           SOF_TIMESTAMPING_RX_HARDWARE | \
+                           SOF_TIMESTAMPING_RAW_HARDWARE)
+
 #if CONFIG_NETUTILS_PTPD_OUTLIER_THRESHOLD_NS > 0
 /* Outlier rejection of the measured phase error: number of recent samples
  * the median is taken over, the least number of samples needed before
@@ -759,12 +768,15 @@ static int ptp_initialize_state(FAR struct ptp_state_s *state)
         }
     }
 
-  /* Query timestamping capabilities */
+  /* Query timestamping capabilities.  Hardware TX timestamps are only
+   * retrieved on the IEEE 802.3 transport (see ptp_sendmsg()), so the
+   * UDP transports do not depend on the driver providing them.
+   */
 
   state->hwts_tx = false;
   state->hwts_tx_failed = false;
 #ifdef CONFIG_NET_TIMESTAMP
-  if (state->config->hardware_ts)
+  if (state->config->hardware_ts && state->config->af == AF_PACKET)
     {
       struct ethtool_ts_info info;
 
@@ -782,10 +794,24 @@ static int ptp_initialize_state(FAR struct ptp_state_s *state)
                  state->config->interface, errno);
           return ERROR;
         }
-      else if ((info.so_timestamping & SOF_TIMESTAMPING_TX_HARDWARE) == 0)
+      else if ((info.so_timestamping & PTP_HWTS_REQUIRED) !=
+               PTP_HWTS_REQUIRED)
         {
-          ptpwarn("Interface %s does not support hardware TX timestamping\n",
-                  state->config->interface);
+          /* -H was requested but the driver does not report hardware RX
+           * and TX timestamp support: refuse to start rather than
+           * silently run in software, the same way linuxptp/ptp4l refuses
+           * to start when 'time_stamping hardware' is configured on an
+           * interface whose ETHTOOL_GET_TS_INFO does not report them.
+           */
+
+          ptperr("Interface %s does not support hardware%s%s "
+                 "timestamping, use -S for software timestamps\n",
+                 state->config->interface,
+                 (info.so_timestamping & SOF_TIMESTAMPING_RX_HARDWARE) == 0 ?
+                 " RX" : "",
+                 (info.so_timestamping & SOF_TIMESTAMPING_TX_HARDWARE) == 0 ?
+                 " TX" : "");
+          return ERROR;
         }
       else
         {
@@ -1019,8 +1045,8 @@ static int ptp_get_tx_timestamp(FAR struct ptp_state_s *state,
     }
   else
     {
-      ptpwarn("PTP TX HWTS: poll ret=%d revents=0x%04x errno=%d\n",
-              ret, pfd.revents, errno);
+      ptpwarn("PTP TX HWTS: poll ret=%d revents=0x%04" PRIx32
+              " errno=%d\n", ret, pfd.revents, errno);
     }
 
   return ERROR;
diff --git a/system/ptpd/ptpd_main.c b/system/ptpd/ptpd_main.c
index 3347f6c2d..c66caf6e5 100644
--- a/system/ptpd/ptpd_main.c
+++ b/system/ptpd/ptpd_main.c
@@ -157,6 +157,8 @@ static void usage(FAR const char *progname)
                   " -6       UDP IPV6\n"
                   " Time Stamping:\n"
                   " -H       HARDWARE (default) depends on NET_TIMESTAMP\n"
+                  "          with -2, requires hardware RX and TX\n"
+                  "          timestamp support from the interface\n"
                   " -S       SOFTWARE\n"
                   " -B       The best master clock algorithm is used\n"
                   " -r       synchronize system (realtime) clock\n"