[RFC v3 0/6] introduce PTP protocol library and software relay

[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 (TPIDs 0x8100/0x88A8, single
    or double), UDP/IPv4, UDP/IPv6 (ports 319/320), and VLAN-tagged
    UDP variants
  - 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

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. Parses packets using rte_ptp_hdr_get()
  3. For event messages, records software timestamps
     (clock_gettime(CLOCK_MONOTONIC)) 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

Unit Tests: app/test
--------------------
A comprehensive test suite (ptp_autotest) covers all library APIs,
including VLAN/QinQ/IPv4/IPv6 transports, correctionField helpers,
flags, and negative tests. This v3 also adds coverage for IPv4 options
(IHL > 5).

v3:
  - Reused RTE_ETHER_TYPE_1588 via RTE_PTP_ETHERTYPE alias
  - Updated version field comment to minorVersionPTP|versionPTP
  - Fixed prog guide rte_ptp_hdr_get() signature (non-const mbuf)
  - Added ALLOW_EXPERIMENTAL_API to ptp_tap_relay_sw Makefile
  - Updated relay example to parse once (rte_ptp_hdr_get + msg_type)
  - Updated relay sample app limitations wording to match capabilities
  - Added hdr_get NULL checks in correction tests
  - Added IPv4 options classification test (IHL > 5)
  - Made correction counter update style consistent via pointer arg

v2:
  - Fixed flag bit positions for host-order representation after
    rte_be_to_cpu_16(): TWO_STEP (1<<9), UNICAST (1<<10),
    LI_61 (1<<0), LI_59 (1<<1)
  - Fixed QinQ classification: outer 0x88A8 now enters VLAN parser
  - Fixed signed left-shift UB in rte_ptp_add_correction()
  - Fixed promiscuous enable failure handling in relay port_init()
  - Replaced deprecated master/slave terminology with IEEE terms
  - Added and documented IHL validation for IPv4 PTP-over-UDP
  - Changed rte_ptp_is_event() parameter to int with negative guard
  - Changed rte_ptp_hdr_get() parameter to non-const mbuf
  - Added programmer's guide note about avoiding double-parse

Rajesh Kumar (6):
  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
  app/test: add PTP library unit tests
  examples/ptpclient: use shared PTP library definitions

 MAINTAINERS                                   |    8 +
 app/test/meson.build                          |    1 +
 app/test/test_ptp.c                           | 1106 +++++++++++++++++
 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             |  205 +++
 doc/guides/rel_notes/release_26_07.rst        |   13 +
 doc/guides/sample_app_ug/index.rst            |    1 +
 doc/guides/sample_app_ug/ptp_tap_relay_sw.rst |  212 ++++
 examples/meson.build                          |    1 +
 examples/ptp_tap_relay_sw/Makefile            |   43 +
 examples/ptp_tap_relay_sw/meson.build         |   14 +
 examples/ptp_tap_relay_sw/ptp_tap_relay_sw.c  |  433 +++++++
 examples/ptpclient/meson.build                |    1 +
 examples/ptpclient/ptpclient.c                |  188 ++-
 lib/meson.build                               |    1 +
 lib/ptp/meson.build                           |    6 +
 lib/ptp/rte_ptp.c                             |  185 +++
 lib/ptp/rte_ptp.h                             |  339 +++++
 20 files changed, 2644 insertions(+), 116 deletions(-)
 create mode 100644 app/test/test_ptp.c
 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


base-commit: 7baf81674a011ab8a2fe329566b6d43d7377244c
-- 
2.53.0