[RFC v1 0/4] introduce PTP protocol library and software relay example

[Rajesh Kumar]

This series introduces a new DPDK library (lib/ptp) for IEEE 1588-2019
PTP protocol packet processing and a companion example application
(ptp_tap_relay_sw) that demonstrates its usage.

Motivation
----------
Several DPDK applications need to classify and manipulate PTP packets
(e.g. ptpclient, ptp_tap_relay, custom Transparent Clocks). Today each
application re-implements its own PTP header parsing and correctionField
handling. A shared library avoids duplication and provides a tested,
standards-compliant foundation.

Library: lib/ptp
----------------
The library provides:
  - PTP header structures (IEEE 1588-2019 common header, timestamp,
    port identity)
  - Packet classification: rte_ptp_classify() detects PTP over L2
    (EtherType 0x88F7), VLAN-tagged L2, and UDP/IPv4 (ports 319/320)
  - Header access: rte_ptp_hdr_get() returns a pointer to the PTP
    header inside an mbuf
  - Inline helpers: correctionField manipulation (48.16 fixed-point),
    message type extraction, two-step flag check, timestamp conversion
  - Debug: rte_ptp_msg_type_str() for human-readable message names

The API is experimental (targeted for 26.07). Dependencies are minimal:
mbuf and net libraries only.

Example: ptp_tap_relay_sw
-------------------------
A minimal PTP Transparent Clock relay between a DPDK-bound physical NIC
and a kernel TAP interface using software timestamps only. No patched
kernel modules, custom TAP PMD, or hardware timestamp support is
required.

The relay:
  1. Receives packets on the physical NIC via DPDK
  2. Classifies PTP packets using rte_ptp_classify()
  3. For event messages, records software timestamps
     (CLOCK_MONOTONIC_RAW) at ingress and egress
  4. Adds residence time to correctionField via rte_ptp_add_correction()
     (IEEE 1588-2019 §10.2 Transparent Clock)
  5. Forwards bidirectionally: PHY <-> TAP

A two-pass design takes the TX timestamp as close to rte_eth_tx_burst()
as possible, minimising untracked delay.

Test Results
------------
Test setup: Intel E610 10GbE NIC (vfio-pci), ptp4l master with HW
timestamps on physical port, ptp4l slave with SW timestamps (-S) on TAP
interface, logSyncInterval=-4 (16 Sync/sec), 120s duration.

  Post-convergence (60s of locked data):
    Average RMS offset:   929 ns
    Worst max offset:     11615 ns (single transient)
    Steady-state range:   489 - 1055 ns RMS
    Corrections applied:  3635

linuxptp's PI servo uses relaxed gains for software timestamps
(kp=0.1, ki=0.001 vs kp=0.7, ki=0.3 for HW), expecting ~5-50 µs
jitter. Sub-microsecond RMS is achieved here because the master uses
HW timestamps and DPDK's poll-mode relay provides deterministic
low-latency forwarding.

Rajesh Kumar (4):
  ptp: introduce PTP protocol library
  doc: add PTP library programmer's guide
  examples/ptp_tap_relay_sw: add software PTP relay example
  doc: add PTP software relay sample app guide

 MAINTAINERS                                   |   7 +
 doc/api/doxy-api-index.md                     |   1 +
 doc/api/doxy-api.conf.in                      |   1 +
 doc/guides/prog_guide/index.rst               |   1 +
 doc/guides/prog_guide/ptp_lib.rst             | 195 ++++++++
 doc/guides/sample_app_ug/index.rst            |   1 +
 doc/guides/sample_app_ug/ptp_tap_relay_sw.rst | 210 +++++++++
 examples/meson.build                          |   1 +
 examples/ptp_tap_relay_sw/Makefile            |  41 ++
 examples/ptp_tap_relay_sw/meson.build         |  14 +
 examples/ptp_tap_relay_sw/ptp_tap_relay_sw.c  | 424 ++++++++++++++++++
 lib/meson.build                               |   1 +
 lib/ptp/meson.build                           |   6 +
 lib/ptp/rte_ptp.c                             | 195 ++++++++
 lib/ptp/rte_ptp.h                             | 328 ++++++++++++++
 15 files changed, 1426 insertions(+)
 create mode 100644 doc/guides/prog_guide/ptp_lib.rst
 create mode 100644 doc/guides/sample_app_ug/ptp_tap_relay_sw.rst
 create mode 100644 examples/ptp_tap_relay_sw/Makefile
 create mode 100644 examples/ptp_tap_relay_sw/meson.build
 create mode 100644 examples/ptp_tap_relay_sw/ptp_tap_relay_sw.c
 create mode 100644 lib/ptp/meson.build
 create mode 100644 lib/ptp/rte_ptp.c
 create mode 100644 lib/ptp/rte_ptp.h

-- 
2.52.0