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

[Stephen Hemminger]

On Mon,  4 May 2026 14:47:16 +0530
Rajesh Kumar <rajesh3.kumar at intel.com> wrote:

> 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

Lots of build failures in CI.
Looks like alot around c++ build of header etc.
g++ -Ibuildtools/chkincs/chkincs-cpp-exp.p -Ibuildtools/chkincs -I../buildtools/chkincs -I. -I.. -Iconfig -I../config -Ibuildtools/chkincs/staging -I../buildtools/chkincs/staging -fdiagnostics-color=always -pipe -D_FILE_OFFSET_BITS=64 -Wall -Winvalid-pch -Wnon-virtual-dtor -Wextra -Werror -g -include rte_config.h -march=corei7 -mrtm -Wno-missing-field-initializers -Wno-vla -DALLOW_EXPERIMENTAL_API -MD -MQ buildtools/chkincs/chkincs-cpp-exp.p/meson-generated_rte_ptp.cpp.o -MF buildtools/chkincs/chkincs-cpp-exp.p/meson-generated_rte_ptp.cpp.o.d -o buildtools/chkincs/chkincs-cpp-exp.p/meson-generated_rte_ptp.cpp.o -c buildtools/chkincs/chkincs-cpp-exp.p/rte_ptp.cpp
In file included from buildtools/chkincs/staging/rte_memory.h:18,
                 from buildtools/chkincs/staging/rte_ring_core.h:29,
                 from buildtools/chkincs/staging/rte_ring.h:38,
                 from buildtools/chkincs/staging/rte_mempool.h:49,
                 from buildtools/chkincs/staging/rte_mbuf.h:39,
                 from buildtools/chkincs/staging/rte_ether.h:20,
                 from /home/runner/work/dpdk/dpdk/lib/ptp/rte_ptp.h:32,
                 from buildtools/chkincs/chkincs-cpp-exp.p/rte_ptp.cpp:1:
buildtools/chkincs/staging/rte_bitops.h:1468:1: error: conflicting declaration of C function ‘bool rte_bit_test(const volatile uint32_t*, unsigned int)’
 1468 | rte_bit_ ## family ## fun(qualifier uint ## size ## _t *addr, arg1_type arg1_name) \
      | ^~~~~~~~
buildtools/chkincs/staging/rte_bitops.h:1475:9: note: in expansion of macro ‘__RTE_BIT_OVERLOAD_V_2R’
 1475 |         __RTE_BIT_OVERLOAD_V_2R(family, v_, fun, qualifier volatile, size, ret_type, arg1_type, \
      |         ^~~~~~~~~~~~~~~~~~~~~~~
buildtools/chkincs/staging/rte_bitops.h:1479:9: note: in expansion of macro ‘__RTE_BIT_OVERLOAD_SZ_2R’
 1479 |         __RTE_BIT_OVERLOAD_SZ_2R(family, fun, qualifier, 32, ret_type, arg1_type, arg1_name) \
      |         ^~~~~~~~~~~~~~~~~~~~~~~~
buildtools/chkincs/staging/rte_bitops.h:1575:1: note: in expansion of macro ‘__RTE_BIT_OVERLOAD_2R’
 1575 | __RTE_BIT_OVERLOAD_2R(, test, const, bool, unsigned int, nr)
      | ^~~~~~~~~~~~~~~~~~~~~
buildtools/chkincs/staging/rte_bitops.h:1468:1: note: previous declaration ‘bool rte_bit_test(const uint32_t*, unsigned int)’
 1468 | rte_bit_ ## family ## fun(qualifier uint ## size ## _t *addr, arg1_type arg1_name) \
      | ^~~~~~~~
buildtools/chkincs/staging/rte_bitops.h:1474:9: note: in expansion of macro ‘__RTE_BIT_OVERLOAD_V_2R’
 1474 |         __RTE_BIT_OVERLOAD_V_2R(family,, fun, qualifier, size, ret_type, arg1_type, arg1_name) \
      |         ^~~~~~~~~~~~~~~~~~~~~~~
buildtools/chkincs/staging/rte_bitops.h:1479:9: note: in expansion of macro ‘__RTE_BIT_OVERLOAD_SZ_2R’
 1479 |         __RTE_BIT_OVERLOAD_SZ_2R(family, fun, qualifier, 32, ret_type, arg1_type, arg1_name) \
      |         ^~~~~~~~~~~~~~~~~~~~~~~~
buildtools/chkincs/staging/rte_bitops.h:1575:1: note: in expansion of macro ‘__RTE_BIT_OVERLOAD_2R’
 1575 | __RTE_BIT_OVERLOAD_2R(, test, const, bool, unsigned int, nr)