<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=Windows-1252"> <style type="text/css" style="display:none;"> P {margin-top:0;margin-bottom:0;} </style> </head> <body dir="ltr"> <div class="elementToProof" style="font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 11pt; color: rgb(0, 0, 0);"> </div> <div> </div> <div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> </div> <hr style="display: inline-block; width: 98%;"> <div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> From: Rajesh Kumar <rajesh3.kumar@intel.com> Sent: Tuesday, August 18, 2026 12:54 AM To: dev@dpdk.org <dev@dpdk.org> Cc: thomas@monjalon.net <thomas@monjalon.net>; Richardson, Bruce <bruce.richardson@intel.com>; andrew.rybchenko@oktetlabs.ru <andrew.rybchenko@oktetlabs.ru>; Kumar, Rajesh3 <rajesh3.kumar@intel.com> Subject: [RFC 1/1] ethdev: add per-packet Tx timestamp slot APIs </div> <div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> </div> <div style="font-size: 11pt;">Add ethdev public and driver-facing APIs for per-packet Tx hardware timestamp slot management. The existing `rte_eth_timesync_read_tx_timestamp()` exposes a single shared latch, making it unreliable when multiple Tx timestamps are outstanding concurrently. PMDs with per-packet slot hardware cannot be exploited through this interface. Introduce a slot lifecycle API: - `rte_eth_timesync_tx_timestamp_slot_alloc()`: reserve a hardware slot before transmit - `rte_eth_timesync_tx_timestamp_stamp_mbuf()`: embed slot handle into mbuf dynfield for per-packet NIC steering - `rte_eth_timesync_read_tx_timestamp_slot()`: poll slot for a captured timestamp; returns -EAGAIN if not ready - `rte_eth_timesync_tx_timestamp_slot_release()`: return slot to PMD after readback or timeout Introduce `rte_eth_timesync_dual_domain_timestamp` to carry both the adjusted PHC time (`adjusted_ns`) and free-running cycles-domain time (`cycles_ns`), each with an individual validity bit in `valid_mask`. Signed-off-by: Rajesh Kumar <rajesh3.kumar@intel.com> --- lib/ethdev/ethdev_driver.h | 19 ++++++ lib/ethdev/rte_ethdev.c | 121 +++++++++++++++++++++++++++++++++++++ lib/ethdev/rte_ethdev.h | 108 +++++++++++++++++++++++++++++++++ 3 files changed, 248 insertions(+) diff --git a/lib/ethdev/ethdev_driver.h b/lib/ethdev/ethdev_driver.h index 0f336f9567..61dadcea49 100644 --- a/lib/ethdev/ethdev_driver.h +++ b/lib/ethdev/ethdev_driver.h @@ -795,6 +795,19 @@ typedef int (*eth_timesync_read_rx_timestamp_t)(struct rte_eth_dev *dev, typedef int (*eth_timesync_read_tx_timestamp_t)(struct rte_eth_dev *dev, struct timespec *timestamp); +/** @internal Allocate a per-packet TX timestamp slot handle. */ +typedef int (*eth_timesync_tx_timestamp_slot_alloc_t)(struct rte_eth_dev *dev, + uint16_t tx_queue_id, uint32_t *slot_id); + +/** @internal Read TX timestamp by slot handle. */ +typedef int (*eth_timesync_read_tx_timestamp_slot_t)(struct rte_eth_dev *dev, + uint32_t slot_id, + struct rte_eth_timesync_dual_domain_timestamp *timestamp); + +/** @internal Release a previously allocated TX timestamp slot handle. */ +typedef int (*eth_timesync_tx_timestamp_slot_release_t)(struct rte_eth_dev *dev, + uint32_t slot_id); + /** @internal Function used to adjust the device clock. */ typedef int (*eth_timesync_adjust_time)(struct rte_eth_dev *dev, int64_t); @@ -1561,6 +1574,12 @@ struct eth_dev_ops { eth_timesync_read_rx_timestamp_t timesync_read_rx_timestamp; /** Read the IEEE1588/802.1AS Tx timestamp */ eth_timesync_read_tx_timestamp_t timesync_read_tx_timestamp; + /** Allocate a TX timestamp slot handle */ + eth_timesync_tx_timestamp_slot_alloc_t timesync_tx_timestamp_slot_alloc; + /** Read a TX timestamp using a slot handle */ + eth_timesync_read_tx_timestamp_slot_t timesync_read_tx_timestamp_slot; + /** Release a TX timestamp slot handle */ + eth_timesync_tx_timestamp_slot_release_t timesync_tx_timestamp_slot_release; /** Adjust the device clock */ eth_timesync_adjust_time timesync_adjust_time; /** Adjust the clock frequency */ diff --git a/lib/ethdev/rte_ethdev.c b/lib/ethdev/rte_ethdev.c index 9efeaf77cb..b955784594 100644 --- a/lib/ethdev/rte_ethdev.c +++ b/lib/ethdev/rte_ethdev.c @@ -6699,6 +6699,127 @@ rte_eth_timesync_read_tx_timestamp(uint16_t port_id, } +RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_eth_timesync_tx_timestamp_slot_alloc, 26.11) +int +rte_eth_timesync_tx_timestamp_slot_alloc(uint16_t port_id, + uint16_t tx_queue_id, + uint32_t *slot_id) +{ + struct rte_eth_dev *dev; + + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); + dev = &rte_eth_devices[port_id]; + + if (slot_id == NULL) { + RTE_ETHDEV_LOG_LINE(ERR, + "Cannot allocate ethdev port %u Tx timestamp slot to NULL", + port_id); + return -EINVAL; + } + + if (dev->dev_ops->timesync_tx_timestamp_slot_alloc == NULL) + return -ENOTSUP; + + return eth_err(port_id, + dev->dev_ops->timesync_tx_timestamp_slot_alloc(dev, + tx_queue_id, slot_id)); +} + +RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_eth_timesync_read_tx_timestamp_slot, 26.11) +int +rte_eth_timesync_read_tx_timestamp_slot(uint16_t port_id, + uint32_t slot_id, + struct rte_eth_timesync_dual_domain_timestamp *timestamp) +{ + struct rte_eth_dev *dev; + + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); + dev = &rte_eth_devices[port_id]; + + if (timestamp == NULL) { + RTE_ETHDEV_LOG_LINE(ERR, + "Cannot read ethdev port %u Tx timestamp slot to NULL", + port_id); + return -EINVAL; + } + + if (dev->dev_ops->timesync_read_tx_timestamp_slot == NULL) + return -ENOTSUP; + + return eth_err(port_id, + dev->dev_ops->timesync_read_tx_timestamp_slot(dev, + slot_id, timestamp)); +} + +RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_eth_timesync_tx_timestamp_slot_release, 26.11) +int +rte_eth_timesync_tx_timestamp_slot_release(uint16_t port_id, uint32_t slot_id) +{ + struct rte_eth_dev *dev; + + RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV); + dev = &rte_eth_devices[port_id]; + + if (dev->dev_ops->timesync_tx_timestamp_slot_release == NULL) + return -ENOTSUP; + + return eth_err(port_id, + dev->dev_ops->timesync_tx_timestamp_slot_release(dev, + slot_id)); +} + +static int rte_eth_timesync_tx_slot_dynfield_offset = -1; +static uint64_t rte_eth_timesync_tx_slot_dynflag; + +static int +rte_eth_timesync_tx_slot_dynfield_register(void) +{ + const struct rte_mbuf_dynfield slot_dynfield = { + .name = RTE_ETH_TIMESYNC_TX_SLOT_DYNFIELD_NAME, + .size = sizeof(uint32_t), + .align = alignof(uint32_t), + }; + + if (rte_eth_timesync_tx_slot_dynfield_offset >= 0) + return 0; + + rte_eth_timesync_tx_slot_dynfield_offset = + rte_mbuf_dynfield_register(&slot_dynfield); + if (rte_eth_timesync_tx_slot_dynfield_offset < 0) + rte_eth_timesync_tx_slot_dynfield_offset = + rte_mbuf_dynfield_lookup( + RTE_ETH_TIMESYNC_TX_SLOT_DYNFIELD_NAME, NULL); + if (rte_eth_timesync_tx_slot_dynfield_offset < 0) + return -ENOTSUP; + + { + int flag_bit = rte_mbuf_dynflag_register( + &(const struct rte_mbuf_dynflag){ + .name = RTE_ETH_TIMESYNC_TX_SLOT_DYNFIELD_NAME "_flag"}); + if (flag_bit < 0) + flag_bit = rte_mbuf_dynflag_lookup( + RTE_ETH_TIMESYNC_TX_SLOT_DYNFIELD_NAME "_flag", NULL); + if (flag_bit >= 0) + rte_eth_timesync_tx_slot_dynflag = RTE_BIT64(flag_bit); + } + return 0; +} + +RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_eth_timesync_tx_timestamp_stamp_mbuf, 26.11) +int +rte_eth_timesync_tx_timestamp_stamp_mbuf(uint16_t port_id __rte_unused, + uint32_t slot_id, struct rte_mbuf *m) +{ + if (m == NULL) + return -EINVAL; + if (rte_eth_timesync_tx_slot_dynfield_register() != 0) + return -ENOTSUP; + *RTE_MBUF_DYNFIELD(m, rte_eth_timesync_tx_slot_dynfield_offset, + uint32_t *) = slot_id; + m->ol_flags |= rte_eth_timesync_tx_slot_dynflag; + return 0; +} + RTE_EXPORT_SYMBOL(rte_eth_timesync_adjust_time) int rte_eth_timesync_adjust_time(uint16_t port_id, int64_t delta) diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h index ee400b386f..339c39fcdd 100644 --- a/lib/ethdev/rte_ethdev.h +++ b/lib/ethdev/rte_ethdev.h @@ -5528,6 +5528,114 @@ int rte_eth_timesync_read_rx_timestamp(uint16_t port_id, int rte_eth_timesync_read_tx_timestamp(uint16_t port_id, struct timespec *timestamp); +/** Valid bit for rte_eth_timesync_dual_domain_timestamp.adjusted_ns. */ +#define RTE_ETH_TIMESYNC_DUAL_DOMAIN_TIMESTAMP_ADJUSTED_VALID RTE_BIT32(0) +/** Valid bit for rte_eth_timesync_dual_domain_timestamp.cycles_ns. */ +#define RTE_ETH_TIMESYNC_DUAL_DOMAIN_TIMESTAMP_CYCLES_VALID RTE_BIT32(1) + +/** + * Dual-domain TX timestamp payload. + */ +struct rte_eth_timesync_dual_domain_timestamp { + int64_t adjusted_ns; + int64_t cycles_ns; + uint32_t valid_mask; +}; + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Allocate a TX timestamp slot handle for per-packet correlation. + * + * @param port_id + * The port identifier of the Ethernet device. + * @param tx_queue_id + * TX queue used by the packet to be transmitted. + * @param slot_id + * Output handle identifying the allocated slot. + * + * @return + * - 0: Success. + * - -ENODEV: The port ID is invalid. + * - -EIO: if device is removed. + * - -ENOTSUP: The function is not supported by the Ethernet driver. + * - -EINVAL: Invalid parameters. + */ +__rte_experimental +int rte_eth_timesync_tx_timestamp_slot_alloc(uint16_t port_id, + uint16_t tx_queue_id, uint32_t *slot_id); + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Read a per-packet TX timestamp using a previously allocated slot handle. + * + * @param port_id + * The port identifier of the Ethernet device. + * @param slot_id + * Slot handle returned by rte_eth_timesync_tx_timestamp_slot_alloc(). + * @param timestamp + * Output dual-domain timestamp payload. + * + * @return + * - 0: Success. + * - -EAGAIN: Timestamp is not ready yet. + * - -ENODEV: The port ID is invalid. + * - -EIO: if device is removed. + * - -ENOTSUP: The function is not supported by the Ethernet driver. + * - -EINVAL: Invalid parameters. + */ +__rte_experimental +int rte_eth_timesync_read_tx_timestamp_slot(uint16_t port_id, + uint32_t slot_id, + struct rte_eth_timesync_dual_domain_timestamp *timestamp);</div> <div style="font-size: 11pt;"> </div> <div class="elementToProof" style="font-size: 11pt;">How is the egress port information conveyed?</div> <div class="elementToProof" style="font-family: "Segoe UI", "Segoe UI Web (West European)", "Helvetica Neue", sans-serif; font-size: 11pt; color: rgb(0, 0, 0);"> The timestamp slot is a resource of the physical egress port.</div> <div class="elementToProof" style="font-size: 11pt;"> + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Release a previously allocated TX timestamp slot handle. + * + * @param port_id + * The port identifier of the Ethernet device. + * @param slot_id + * Slot handle to release. + * + * @return + * - 0: Success. + * - -ENODEV: The port ID is invalid. + * - -EIO: if device is removed. + * - -ENOTSUP: The function is not supported by the Ethernet driver. + * - -EINVAL: Invalid parameters. + */ +__rte_experimental +int rte_eth_timesync_tx_timestamp_slot_release(uint16_t port_id, + uint32_t slot_id); + +/** Mbuf dynfield name for the TX timestamp slot handle. */ +#define RTE_ETH_TIMESYNC_TX_SLOT_DYNFIELD_NAME "rte_eth_timesync_tx_slot" + +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Stamp an mbuf with a TX timestamp slot handle so the TX path steers the + * NIC to capture the timestamp in the correct per-packet slot. + * + * Must be called after rte_eth_timesync_tx_timestamp_slot_alloc() and before + * rte_eth_tx_burst(). Safe for concurrent callers � slot is stored per-mbuf. + * + * @param port_id The port identifier (unused; reserved for future PMD use). + * @param slot_id Slot handle from rte_eth_timesync_tx_timestamp_slot_alloc(). + * @param m Mbuf to stamp. + * @return 0 on success, -ENOTSUP if dynfield registration failed. + */ +__rte_experimental +int rte_eth_timesync_tx_timestamp_stamp_mbuf(uint16_t port_id, + uint32_t slot_id, struct rte_mbuf *m); + /** * Adjust the timesync clock on an Ethernet device. * -- 2.54.0 </div> </body> </html>