netutils/ptpd: query timestamping capabilities via SIOCGIFTSCAPS

[daniel-p-carvalho]

Summary

• Depends on net: add NETDEV_TX_STAMP capability flag and SIOCGIFTSCAPS query ioctl 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 driver's capabilities once at startup instead, and makes a genuine runtime failure visible instead of turning it into a silent, permanent mode switch. The startup check follows linuxptp/ptp4l, which refuses to start when hardware timestamping is requested but not reported by the driver via ethtool. Runtime handling is deliberately lighter than ptp4l (which takes the port to FAULTY on a TX timestamp timeout): see below.
• ptp_initialize_state() queries the new SIOCGIFTSCAPS ioctl (net: add NETDEV_TX_STAMP capability flag and SIOCGIFTSCAPS query ioctl nuttx#20346) once for the configured interface. If -H is requested on the IEEE 802.3 transport (-2) and the driver does not report both NETDEV_RX_STAMP and NETDEV_TX_STAMP (or the ioctl itself fails), ptpd now refuses to start. The error message names the missing capability and points to -S, e.g. Interface eth0 does not support hardware 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. This matches ptp4l, which checks both SOF_TIMESTAMPING_RX_HARDWARE and SOF_TIMESTAMPING_TX_HARDWARE.
• 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 sets state->hwts_tx_failed, which is reported through the existing clock_source_valid field of struct ptpd_status_s until the next hardware TX timestamp succeeds. This reuses the daemon's existing health indicator instead of adding a purpose-built one, and 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 declare both NETDEV_RX_STAMP and NETDEV_TX_STAMP 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: add NETDEV_TX_STAMP capability flag and SIOCGIFTSCAPS query ioctl 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 enable both hardware RX and TX timestamping in their Ethernet driver (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; plus the sim target for the refusal-path check below.
  • STM32H7 board (CONFIG_STM32_ETH_TIMESTAMP_RX=y, CONFIG_STM32_ETH_TIMESTAMP_TX=y), companion driver change in net: add NETDEV_TX_STAMP capability flag and SIOCGIFTSCAPS query ioctl nuttx#20346.
  • STM32F1/F3/F4 board (CONFIG_STM32_ETH_TIMESTAMP_RX=y, CONFIG_STM32_ETH_TIMESTAMP_TX=y), companion driver change in net: add NETDEV_TX_STAMP capability flag and SIOCGIFTSCAPS query ioctl nuttx#20346.

Build log (STM32H7 board, after change):

Memory region         Used Size  Region Size  %age Used
            itcm:           0 B        64 KB      0.00%
           flash:      333340 B         2 MB     15.89%
           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, ptpd -s -2 -H -B -P -i eth0 -p /dev/ptp0 started on the STM32H7 board with the current revision of this PR (both NETDEV_RX_STAMP and NETDEV_TX_STAMP reported), status query (ptpd -t <pid>) taken 130 s after start - the daemon started without the refusal error and clock_source_valid is 1 (it would drop to 0 on a hardware TX timestamp failure):

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: 925
- drift_ppb: 17651
- path_delay_ns: 9392
- last_received_announce: 0 s ago
- last_received_sync: 0 s ago
- last_transmitted_delayreq: 130 s ago

Runtime log, STM32F1/F3/F4 board (dmesg excerpt, taken on the previous revision of this PR that only checked TX), full PTP P2P exchange, hardware TX timestamp used throughout, no fallback):

ptp_process_rx_packet: Got follow-up packet, seq 6693
ptp_update_local_clock: Local time: 1790260023.503704646, remote time 1790260023.503692546
ptp_update_local_clock: Delta: -2788 ns, adjustment -80060 ns, drift rate -79662 ppb
ptp_send_pdelay_req: Sent Pdelay_Req, seq 20
ptp_process_rx_packet: Got pdelay resp, seq 20
ptp_process_rx_packet: Got pdelay resp follow-up, seq 20
ptp_record_path_delay: Path delay: 9304 ns (avg: 9312 ns)

Refusal path, ptpd -2 -H -i eth0 on an interface that does not declare the capabilities (sim target, host build, eth0 is the sim's virtual network device, which does not implement NETDEV_RX_STAMP/NETDEV_TX_STAMP; CONFIG_DEBUG_PTP_ERROR=y):

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

Same refusal on the STM32H7 board built without CONFIG_STM32_ETH_TIMESTAMP_TX and without PTP debug output (ptperr compiled out), ptpd still exits:

nsh> ptpd -2 -H -i eth0 &
ptpd [7:100]
ERROR: ptpd_start() failed: -1

10-minute soak against the Grandmaster (STM32H7 board): 0 ping failures over 19 samples at 30s intervals, clock_source_valid stayed 1 throughout, path_delay_ns stable between 9381-9395 ns.

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.