netutils/ptpd: query timestamping capabilities via ETHTOOL_GET_TS_INFO

[daniel-p-carvalho]

Summary

• Depends on net/netdev: add NETDEV_TX_STAMP and SIOCETHTOOL ETHTOOL_GET_TS_INFO nuttx#20346.
• Follow-up to the discussion in netutils/ptpd: hardware TX timestamps via MSG_ERRQUEUE and egress latency compensation #3791: ptpd currently detects hardware TX timestamp support by trial and error (three consecutive failures, then a silent, permanent switch to software timestamps). This PR switches it to querying the interface's timestamping capabilities once at startup, the same way linuxptp/ptp4l does on Linux (SIOCETHTOOL with ETHTOOL_GET_TS_INFO), and makes a genuine runtime failure visible instead of turning it into a silent, permanent mode switch.
• ptp_initialize_state() issues ETHTOOL_GET_TS_INFO once for the configured interface (implemented by net/netdev: add NETDEV_TX_STAMP and SIOCETHTOOL ETHTOOL_GET_TS_INFO nuttx#20346). If -H is requested on the IEEE 802.3 transport (-2) and the reported so_timestamping does not contain SOF_TIMESTAMPING_TX_HARDWARE, SOF_TIMESTAMPING_RX_HARDWARE and SOF_TIMESTAMPING_RAW_HARDWARE (or the ioctl itself fails), ptpd refuses to start, like ptp4l does when hardware timestamping is configured but not reported by ethtool. The error message names the missing capability and points to -S, e.g. Interface eth0 does not support hardware RX TX timestamping, use -S for software timestamps.
• Hardware RX timestamps are required as well as TX: 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 path 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 interfaces that never need the capability.
• Removed hwts_tx_failures, PTP_HWTS_TX_MAX_FAILURES and hwts_tx_disabled. Hardware TX timestamp use (state->hwts_tx) is now a fixed capability read once, not a runtime state machine.
• A genuine ptp_get_tx_timestamp() timeout on an interface that already reported the capability (a failure at runtime, after startup succeeded) still falls back to the software timestamp for that single message, but it is no longer silent or permanent: it is logged with ptperr (was ptpwarn) and invalidates clock_source_valid in the ptpd status until the next hardware TX timestamp succeeds. Hardware timestamping is retried on every message rather than being disabled.
• The -H usage text now documents that, with -2, it requires hardware RX and TX timestamp support from the interface.

Impact

• Is new feature added? Is existing feature changed? YES - changes how ptpd -2 -H decides between hardware and software timestamping (capability query instead of runtime detection), and how a hardware TX timestamp failure is reported.
• Impact on user (will user need to adapt to change)? YES - ptpd -2 -H on an interface whose driver does not report hardware RX and TX timestamping now exits immediately with an error message instead of running silently in software timestamp mode after a few failed attempts. UDP transports (-4/-6, the default) and -S are unaffected.
• Impact on build (will build process change)? NO.
• Impact on hardware (will arch(s) / board(s) / driver(s) change)? NO - ptpd is a userspace daemon; the driver-side capability declaration is in the companion net/netdev: add NETDEV_TX_STAMP and SIOCETHTOOL ETHTOOL_GET_TS_INFO nuttx#20346 PR.
• Impact on documentation (is update required / provided)? YES - the -H usage text in system/ptpd now states the capability requirement with -2.
• Impact on security (any sort of implications)? NO.
• Impact on compatibility (backward/forward/interoperability)? YES, minor - see user impact above. Boards running ptpd -2 -H must have their Ethernet driver declare hardware RX and TX timestamping (e.g. CONFIG_STM32_ETH_TIMESTAMP_RX=y and CONFIG_STM32_ETH_TIMESTAMP_TX=y).

Testing

I confirm that changes are verified on local setup and works as intended:

• Build Host(s): Linux (Ubuntu), x86_64, GCC (arm-none-eabi-gcc toolchain for the board targets, host GCC for sim).
• Target(s): arm, two real boards, both against a physical IEEE 1588 PTP Grandmaster over Ethernet (ptpd -s -2 -H -B -P -i eth0 -p /dev/ptp0); plus the sim target for the refusal-path check below. All tests use the head of this PR together with the head of net/netdev: add NETDEV_TX_STAMP and SIOCETHTOOL ETHTOOL_GET_TS_INFO nuttx#20346.
  • STM32H7 board (CONFIG_STM32_ETH_TIMESTAMP_RX=y, CONFIG_STM32_ETH_TIMESTAMP_TX=y).
  • STM32F1/F3/F4 board (CONFIG_STM32_ETH_TIMESTAMP_RX=y, CONFIG_STM32_ETH_TIMESTAMP_TX=y).

Build log (STM32H7 board):

Memory region         Used Size  Region Size  %age Used
            itcm:           0 B        64 KB      0.00%
           flash:      333508 B         2 MB     15.90%
           dtcm1:           0 B        64 KB      0.00%
           dtcm2:           0 B        64 KB      0.00%
            sram:       49200 B       512 KB      9.38%
           sram1:           0 B       128 KB      0.00%
           sram2:           0 B       128 KB      0.00%
           sram3:           0 B        32 KB      0.00%
           sram4:           0 B        64 KB      0.00%
           bbram:           0 B         4 KB      0.00%
CP: nuttx.hex
CP: nuttx.bin

Runtime log, STM32H7 board, ptpd status query (ptpd -t <pid>) 135 s after start: the daemon starts without the refusal error (both hardware capabilities are reported) and clock_source_valid is 1:

PTPD (PID 8) status:
- clock_source_valid: 1
|- id: 00 14 2d ff fe 61 2b b5
|- class: 6
|- accuracy: 34
|- gm_id: 00 14 2d ff fe 61 2b b5
|- stepsremoved: 0
- last_delta_ns: 445
- drift_ppb: 16614
- path_delay_ns: 9398
- last_received_announce: 1 s ago
- last_received_sync: 1 s ago
- last_transmitted_delayreq: 135 s ago

Build log (STM32F1/F3/F4 board):

Memory region         Used Size  Region Size  %age Used
           flash:      186332 B         1 MB     17.77%
CP: nuttx.bin

Runtime log, STM32F1/F3/F4 board (dmesg excerpt, CONFIG_DEBUG_PTP_* enabled), full PTP P2P exchange with hardware timestamps, no error or fallback message; the status query 142 s after start reports clock_source_valid: 1, last_delta_ns: -2398, drift_ppb: -80163 and path_delay_ns: 9300:

ptp_process_rx_packet: Got follow-up packet, seq 1081
ptp_update_local_clock: Local time: 1790369881.590090526, remote time 1790369881.590078683
ptp_update_local_clock: Delta: -2544 ns, adjustment -80315 ns, drift rate -80177 ppb
ptp_send_pdelay_req: Sent Pdelay_Req, seq 90
ptp_process_rx_packet: Got pdelay resp, seq 90
ptp_process_rx_packet: Got pdelay resp follow-up, seq 90
ptp_record_path_delay: Path delay: 9372 ns (avg: 9299 ns)

Refusal path, ptpd -2 -H -i eth0 on an interface that does not report hardware timestamping (sim target, host build, eth0 is the sim's virtual network device, which implements neither NETDEV_RX_STAMP nor NETDEV_TX_STAMP; CONFIG_DEBUG_PTP_ERROR=y):

nsh> ptpd -2 -H -i eth0
[    6.021917] ptp_initialize_state: Interface eth0 does not support hardware RX TX timestamping, use -S for software timestamps
[    6.022007] ptpd_start: Failed to initialize PTP state, exiting
ERROR: ptpd_start() failed: -1

PR verification Self-Check

• This PR introduces only one functional change.
• I have updated all required description fields above.
• My PR adheres to Contributing Guidelines and Documentation (git commit title and message, coding standard, etc).
• My PR is still work in progress (not ready for review).
• My PR is ready for review and can be safely merged into a codebase.

[cederom]

Thank you @daniel-p-carvalho, please:

1. Follow the PR requirements and template (summary, impact, testing), see https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md.
2. Please provide (extract) from build and runtime logs that prove build and runtime solution is working as expected. Overall description (aka "test plan") is not enough as it does not prove anything.

[daniel-p-carvalho]

Updated the PR description to follow the template (Summary/Impact/Testing/Self-Check) with real build and runtime log excerpts from two boards tested against a physical PTP Grandmaster, per your request. Thanks for the pointer to the template.