<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style type="text/css" style="display:none;"> P {margin-top:0;margin-bottom:0;} </style>
</head>
<body dir="ltr">
<div style="font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 11pt; color: rgb(0, 0, 0);">
<br>
</div>
<div><br>
</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</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);">
<b>From:</b> Rajesh Kumar <rajesh3.kumar@intel.com><br>
<b>Sent:</b> Tuesday, August 18, 2026 12:54 AM<br>
<b>To:</b> dev@dpdk.org <dev@dpdk.org><br>
<b>Cc:</b> 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><br>
<b>Subject:</b> [RFC 0/1] ethdev: per-packet Tx timestamp slot management </div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div style="font-size: 11pt;">The current DPDK ethdev time synchronization framework is architected<br>
around a single, shared hardware latch. The existing API,<br>
`rte_eth_timesync_read_tx_timestamp()`, assumes a serialization model<br>
where only one TX timestamp is outstanding at any given time.<br>
<br>
This model creates severe limitations for modern high-throughput network<br>
interface cards (NICs). When multiple packets requiring precise<br>
transmit timestamps are sent concurrently, the shared latch becomes a<br>
race-condition bottleneck. It makes timestamp retrieval unreliable and<br>
drops accuracy. Furthermore, Poll Mode Drivers (PMDs) backed by<br>
hardware that supports independent, per-packet timestamping slots have<br>
no way to expose this capability to the user.<br>
<br>
To solve this, this RFC introduces a formal slot-based lifecycle API<br>
for per-packet Tx timestamp management. The API decouples timestamp<br>
tracking from the global latch model, enabling true asynchronous,<br>
parallel hardware timestamping.<br>
<br>
Key Components of the Proposal:<br>
================================<br>
1. **Slot Lifecycle Management APIs**:<br>
- `rte_eth_timesync_tx_timestamp_slot_alloc()`: Allocates and locks<br>
a unique hardware slot prior to frame transmission.<br>
- `rte_eth_timesync_tx_timestamp_stamp_mbuf()`: Embeds the allocated<br>
slot handle into an mbuf dynamic field, allowing the PMD to<br>
program the specific hardware descriptor during the Tx burst.<br>
- `rte_eth_timesync_read_tx_timestamp_slot()`: Asynchronously polls<br>
a specific slot for its captured value, safely returning `-EAGAIN`<br>
if the hardware has not yet written back the timestamp.<br>
- `rte_eth_timesync_tx_timestamp_slot_release()`: Recycles the<br>
hardware slot back to the PMD resource pool after successful<br>
retrieval or an application timeout.<br>
<br>
2. **Dual-Domain Timing Mechanics**:<br>
- Introduces `struct rte_eth_timesync_dual_domain_timestamp` to<br>
simultaneously capture both the adjusted PTP Hardware Clock (PHC)<br>
domain (`adjusted_ns`) and the raw, free-running cycles domain<br>
(`cycles_ns`).<br>
- A dedicated `valid_mask` tracks the validity of each time domain<br>
independently, giving applications granular telemetry options.<br>
<br>
Scope of this RFC & Open Questions for the Community:<br>
======================================================<br>
This RFC establishes the structural definition of the APIs and driver<br>
interfaces. Before proceeding to a full `v1` patch with active PMD<br>
implementations, we would highly appreciate the community's feedback<br>
on the following design choices:<br>
<br>
- **Mbuf Dynamic Field Layout**: Is the encapsulation of the slot<br>
handle into an mbuf dynamic field using standard dynamic registration<br>
the preferred mechanism for passing steering context to the Tx<br>
descriptor path?</div>
<div class="elementToProof" style="font-size: 11pt;"><br>
</div>
<div class="elementToProof" style="font-size: 11pt;"> rte_mbuf structure has "timesync" field, which can be used for the slot.</div>
<div class="elementToProof" style="font-size: 11pt;"> This way mbuf dynamic field use can be avoided.</div>
<div class="elementToProof" style="font-size: 11pt;"><br>
- **Dual-Domain Structure**: Does tracking both the adjusted PHC and<br>
the cycle counter within `rte_eth_timesync_dual_domain_timestamp`<br>
cover the needs of other hardware vendors supporting concurrent<br>
domains?<br>
- **Error States**: Is `-EAGAIN` an acceptable return code for<br>
non-blocking polling of incomplete timestamps, or should we consider<br>
an explicit bitmask status?<br>
<br>
Please review the proposed design. We welcome your feedback, design<br>
suggestions, and critique.<br>
<br>
Rajesh Kumar (1):<br>
ethdev: add per-packet Tx timestamp slot APIs<br>
<br>
lib/ethdev/ethdev_driver.h | 19 ++++++<br>
lib/ethdev/rte_ethdev.c | 121 +++++++++++++++++++++++++++++++++++++<br>
lib/ethdev/rte_ethdev.h | 108 +++++++++++++++++++++++++++++++++<br>
3 files changed, 248 insertions(+)<br>
<br>
--<br>
2.54.0<br>
<br>
</div>
</body>
</html>