Feature: PTP Peer-to-Peer (P2P) Path Delay Support

doc/PTP/SAI-Proposal-PTP-Pdelay.md

@@ -0,0 +1,267 @@
+# Upstreaming PTP Peer-to-Peer (P2P) Path Delay Support in SAI
+-------------------------------------------------------------------------------
+ Title       | Upstreaming PTP Peer-to-Peer (P2P) Path Delay Support in SAI
+-------------|-----------------------------------------------------------------
+ Authors     | Gurprem Singh, Michael Cutforth, Eric Lance
+ Status      | In review
+ SAI-Version | 1.18
+-------------------------------------------------------------------------------
+
+# 1. Overview & Use Case
+
+This proposal introduces support for the IEEE 1588 Peer-to-Peer (P2P) Path Delay
+measurement mechanism in the Switch Abstraction Interface (SAI). The primary
+goal of this feature is to remove the propagation time error for
+synchronization. 
+
+Rather than calculating end-to-end latency across the entire network, each port
+independently measures the link propagation delay to its immediate neighbor. 
+
+![PTP P2P Transparent Clock](p2p_tc.png)
+
+When a PTP event packet (such as a Sync or Follow_Up message) transits through a P2P
+Transparent Clock (TC), the hardware must account for two distinct delays:
+
+- Residence Time: The internal time the packet spent inside the switch
+  (calculated as `egress_time - ingress_time`).
+- Propagation Time: The previously measured link delay of the ingress port
+  (`link_delay`).
+
+By adding both the internal residence time and the ingress link propagation delay, 
+the switch can accurately update the packet's Correction Field (CF) locally. This 
+eliminates the impact of link propagation delay anomalies and allows downstream 
+clocks to synchronize with incredibly high precision.
+
+# 2. Proposed SAI Spec 
+
+This proposal introduces spec to offload the high-frequency exchange of
+IEEE 1588 Peer Delay messages to the underlying hardware. By defining a standard
+profile, the underlying switch hardware can be configured to autonomously
+transmit, receive, and timestamp Pdelay_Req and Pdelay_Resp packets across
+multiple ports.
+
+The control plane retains full visibility and flexibility through standard SAI
+attributes. The steady state link propagation delay is programmed back into the
+datapath via the `SAI_PORT_ATTR_LINK_DELAY` attribute which can be used to
+update the Correction Field (CF) of transiting PTP event packets.
+
+To cleanly separate the configuration of this hardware engine from the active
+physical port state, we introduce a new configuration object type,
+`SAI_OBJECT_TYPE_PTP_PDELAY`. This object acts as a reusable profile holding
+the IEEE 1588 parameters for running the autonomous peer-delay engine (such as
+MAC addresses, protocol, and intervals), which is then bound to physical ports.
+
+## 2.1 Pdelay Profile Attributes (SAI_OBJECT_TYPE_PTP_PDELAY)
+
+### SAI_PTP_PDELAY_ATTR_PORT_TYPE
+
+- Value Type: sai_ptp_pdelay_type_t
+- Flags: CREATE_AND_SET
+- Description: Configure as Initiator, Responder, or Both.
+    - SAI_PTP_PDELAY_TYPE_NONE
+    - SAI_PTP_PDELAY_TYPE_INITIATOR
+    - SAI_PTP_PDELAY_TYPE_RESPONDER
+    - SAI_PTP_PDELAY_TYPE_BOTH
+
+### SAI_PTP_PDELAY_ATTR_PTP_PROTOCOL
+
+- Value Type: sai_ptp_protocol_t
+- Flags: CREATE_AND_SET
+- Description: Protocol transport (IEEE 802.3, UDP/IPv4, UDP/IPv6).
+    - SAI_PTP_PROTOCOL_NONE
+    - SAI_PTP_PROTOCOL_UDP_IPV4
+    - SAI_PTP_PROTOCOL_UDP_IPV6
+    - SAI_PTP_PROTOCOL_IEEE8023
+
+### SAI_PTP_PDELAY_ATTR_SRC_MAC
+
+- Value Type: sai_mac_t
+- Flags: CREATE_AND_SET
+- Description: Source MAC address used in egress Pdelay frames.
+
+### SAI_PTP_PDELAY_ATTR_L2_HEADER_LEN
+
+- Value Type: sai_uint8_t
+- Flags: CREATE_AND_SET
+- Description: Outer Layer-2 header encapsulation length.
+
+### SAI_PTP_PDELAY_ATTR_PTP_L2_HEADER
+
+- Value Type: sai_u8_list_t
+- Flags: CREATE_AND_SET
+- Description: Peer delay L2 header. The header representation is provided as a variable-length list.
+
+### SAI_PTP_PDELAY_ATTR_NETWORK_ADDR
+
+- Value Type: sai_ip_address_t
+- Flags: CREATE_AND_SET
+- Description: Source IP address used for UDP transport encapsulation. Note: When configuring `SAI_PTP_PROTOCOL_UDP_IPV6`, an explicit IPv6 address must be specified since `@default` is `0.0.0.0`.
+
+### SAI_PTP_PDELAY_ATTR_INGRESS_VLAN_ID
+
+- Value Type: sai_uint16_t
+- Flags: CREATE_AND_SET
+- Description: Expected VLAN tag of incoming peer delay frames.
+
+### SAI_PTP_PDELAY_ATTR_DOMAIN_NUMBER
+
+- Value Type: sai_uint8_t
+- Flags: CREATE_AND_SET
+- Description: PTP Domain Number.
+
+### SAI_PTP_PDELAY_ATTR_LOG_INTERVAL
+
+- Value Type: sai_int32_t
+- Flags: CREATE_AND_SET
+- Description: Logarithmic interval of request packet transmission.
+
+### SAI_PTP_PDELAY_ATTR_TTL
+
+- Value Type: sai_uint8_t
+- Flags: CREATE_AND_SET
+- Description: Packet Time-To-Live.
+
+### SAI_PTP_PDELAY_ATTR_IP_DSCP
+
+- Value Type: sai_uint8_t
+- Flags: CREATE_AND_SET
+- Description: Packet IP DSCP priority mapping.
+
+### SAI_PTP_PDELAY_ATTR_PORT_MODE
+
+- Value Type: bool
+- Flags: CREATE_AND_SET
+- Description: Enable or disable the local Pdelay measurement engine.
+
+## 2.2 Port-Level Attributes
+
+### SAI_PORT_ATTR_PDELAY_INSTANCE_ID
+
+- Value Type: sai_object_id_t
+- Flags: CREATE_AND_SET
+- Description: Associates the port with a specific configuration profile.
+  Setting this to `SAI_NULL_OBJECT_ID` detaches the profile and disables P2P
+  processing on the physical interface.
+
+### SAI_PORT_ATTR_LINK_DELAY
+
+- Value Type: sai_int64_t
+- Flags: CREATE_AND_SET
+- Description: Used by the control plane daemon to program the calculated
+  steady-state link propagation delay (in nanoseconds) into the physical
+  interface's hardware registers.
+
+### SAI_PORT_ATTR_PDELAY_LINK_DELAY
+
+- Value Type: sai_int64_t
+- Flags: CREATE_AND_SET
+- Description: Exposes the current measured link propagation delay value
+  from hardware.
+
+### SAI_PORT_ATTR_PDELAY_NEIGHBOR_RATE_RATIO
+
+- Value Type: sai_int32_t
+- Flags: READ_ONLY
+- Description: Exposes the calculated neighbor clock rate ratio.
+
+### SAI_PORT_ATTR_PDELAY_NEIGHBOR_PROPAGATION_DELAY
+
+- Value Type: sai_uint32_t
+- Flags: READ_ONLY
+- Description: Exposes raw neighbor propagation delay values.
+
+## 2.3 Switch-Level Global Attributes
+
+### SAI_SWITCH_ATTR_CLOCK_ID
+
+- Value Type: sai_u8_list_t
+- Flags: CREATE_AND_SET
+- Description: Specifies the global clock identity of the PTP platform.
+  An 8-octet array (`uint8_t[8]`) in network byte order as specified in IEEE
+  Std 1588-2019.
+
+### SAI_SWITCH_ATTR_PTP_PDELAY_MAX_PORTS
+
+- Value Type: sai_uint16_t
+- Flags: CREATE_AND_SET
+- Description: Configures the maximum number of ports that can have PTP
+  peer-delay enabled concurrently.
+
+### SAI_SWITCH_ATTR_PTP_PDELAY_IS_TWO_STEP
+
+- Value Type: bool
+- Flags: CREATE_AND_SET
+- Description: Specifies whether the global clock instance operates in
+  two-step timestamping mode.
+
+## 2.4 PTP Pdelay Port Statistics
+
+### SAI_PORT_STAT_PTP_PDELAY_TX_REQ_COUNT
+
+- Description: Count of transmitted Peer Delay Request packets.
+
+### SAI_PORT_STAT_PTP_PDELAY_RX_REQ_COUNT
+
+- Description: Count of received Peer Delay Request packets.
+
+### SAI_PORT_STAT_PTP_PDELAY_TX_RESP_COUNT
+
+- Description: Count of transmitted Peer Delay Response packets.
+
+### SAI_PORT_STAT_PTP_PDELAY_RX_RESP_COUNT
+
+- Description: Count of received Peer Delay Response packets.
+
+### SAI_PORT_STAT_PTP_PDELAY_TX_RESP_FOLLOWUP_COUNT
+
+- Description: Count of transmitted Peer Delay Response Follow-Up packets.
+
+### SAI_PORT_STAT_PTP_PDELAY_RX_RESP_FOLLOWUP_COUNT
+
+- Description: Count of received Peer Delay Response Follow-Up packets.
+
+### SAI_PORT_STAT_PTP_PDELAY_RESP_TIMEOUT_COUNT
+
+- Description: Count of Peer Delay Response timeouts.
+
+### SAI_PORT_STAT_PTP_PDELAY_RESP_FOLLOWUP_TIMEOUT_COUNT
+
+- Description: Count of Peer Delay Response Follow-Up timeouts.
+
+## 3. API Workflow and Example
+
+3.1 The global PTP clock identity must be initialized on the switch.
+
+```c
+sai_attribute_t attr;
+attr.id = SAI_SWITCH_ATTR_CLOCK_ID;
+attr.value.u8list.count = 8;
+attr.value.u8list.list = my_clock_id;
+sai_set_switch_attribute_fn(switch_id, &attr);
+```
+
+3.2 Creating a Pdelay Profile
+An application creates a reusable Pdelay profile
+configuration.
+
+```c
+sai_attribute_t attr_list[2];
+attr_list[0].id = SAI_PTP_PDELAY_ATTR_PORT_TYPE;
+attr_list[0].value.s32 = SAI_PTP_PDELAY_TYPE_BOTH;
+attr_list[1].id = SAI_PTP_PDELAY_ATTR_LOG_INTERVAL;
+attr_list[1].value.s32 = -3; // 8 packets per second
+
+sai_object_id_t pdelay_id;
+sai_create_ptp_pdelay_fn(&pdelay_id, switch_id, 2, attr_list);
+```
+
+3.3 Binding Profile to a Port
+The profile is bound to a physical interface to
+activate hardware P2P processing.
+
+```c
+sai_attribute_t attr;
+attr.id = SAI_PORT_ATTR_PDELAY_INSTANCE_ID;
+attr.value.oid = pdelay_id;
+sai_set_port_attribute_fn(port_id, &attr);
+```

inc/sai.h

@@ -84,6 +84,7 @@
 #include "saiicmpecho.h"
 #include "saisynce.h"
 #include "saivirtualchannel.h"
+#include "saiptppdelay.h"
 
 /**
  * @defgroup SAI SAI - Entry point specific API definitions.
@@ -157,6 +158,7 @@ typedef enum _sai_api_t
     SAI_API_SYNCE            = 54, /**< sai_synce_api_t */
     SAI_API_VIRTUAL_CHANNEL  = 55, /**< sai_virtual_channel_api_t */
     SAI_API_PERFMON          = 56, /**< sai_perfmon_api_t */
+    SAI_API_PTP_PDELAY       = 57, /**< sai_ptp_pdelay_api_t */
     SAI_API_MAX,                   /**< total number of APIs */
 
     /**

inc/saiport.h

@@ -3332,6 +3332,69 @@ typedef enum _sai_port_attr_t
      */
     SAI_PORT_ATTR_KNOWN_UNICAST_STORM_CONTROL_POLICER_ID,
 
+    /**
+     * @brief Enable/Disable PTP peer delay functionality
+     *
+     * Enable PTP peer to peer delay functionality by assigning a
+     * valid object ID. Disable functionality by assigning
+     * SAI_NULL_OBJECT_ID as attribute value.
+     *
+     * @type sai_object_id_t
+     * @flags CREATE_AND_SET
+     * @objects SAI_OBJECT_TYPE_PTP_PDELAY
+     * @allownull true
+     * @default SAI_NULL_OBJECT_ID
+     */
+    SAI_PORT_ATTR_PDELAY_INSTANCE_ID,
+
+    /**
+     * @brief Raw Link Delay, as calculated by the peer delay mechanism
+     *
+     * This attribute is applicable only when PTP peer delay functionality is enabled.
+     * When PTP peer delay functionality is disabled, 0 should be returned.
+     *
+     * @type sai_int64_t
+     * @flags CREATE_AND_SET
+     * @default 0
+     */
+    SAI_PORT_ATTR_PDELAY_LINK_DELAY,
+
+    /**
+     * @brief Computed Neighbor rate ratio, as calculated by the peer delay mechanism
+     *
+     * This attribute is applicable only when PTP peer delay functionality is enabled.
+     * When PTP peer delay functionality is disabled, 0 should be returned.
+     *
+     * @type sai_int32_t
+     * @flags READ_ONLY
+     */
+    SAI_PORT_ATTR_PDELAY_NEIGHBOR_RATE_RATIO,
+
+    /**
+     * @brief Computed Neighbor propagation delay in nanoseconds,
+     * as calculated by the peer delay mechanism
+     *
+     * This attribute is applicable only when PTP peer delay functionality is enabled.
+     * When PTP peer delay functionality is disabled, 0 should be returned.
+     *
+     * @type sai_uint32_t
+     * @flags READ_ONLY
+     */
+    SAI_PORT_ATTR_PDELAY_NEIGHBOR_PROPAGATION_DELAY,
+
+    /**
+     * @brief Link Delay used for updating correction field in the incoming PTP packet
+     *
+     * This attribute configures the link delay to be used while computing the correction
+     * field in the incoming PTP packet. It can either be computed by the peer delay
+     * mechanism or by NOS.
+     *
+     * @type sai_int64_t
+     * @flags CREATE_AND_SET
+     * @default 0
+     */
+    SAI_PORT_ATTR_LINK_DELAY,
+
     /**
      * @brief Enable unknown unicast storm control policer on port.
      *
@@ -4238,6 +4301,30 @@ typedef enum _sai_port_stat_t
     /** Number of times that LLR Rx detected the start of a replay */
     SAI_PORT_STAT_LLR_RX_REPLAY,
 
+    /** SAI port stat PTP peer delay TX Request count */
+    SAI_PORT_STAT_PTP_PDELAY_TX_REQ_COUNT,
+
+    /** SAI port stat PTP peer delay RX Request count */
+    SAI_PORT_STAT_PTP_PDELAY_RX_REQ_COUNT,
+
+    /** SAI port stat PTP peer delay TX Response count */
+    SAI_PORT_STAT_PTP_PDELAY_TX_RESP_COUNT,
+
+    /** SAI port stat PTP peer delay RX Response count */
+    SAI_PORT_STAT_PTP_PDELAY_RX_RESP_COUNT,
+
+    /** SAI port stat PTP peer delay TX Response Followup count */
+    SAI_PORT_STAT_PTP_PDELAY_TX_RESP_FOLLOWUP_COUNT,
+
+    /** SAI port stat PTP peer delay RX Response Followup count */
+    SAI_PORT_STAT_PTP_PDELAY_RX_RESP_FOLLOWUP_COUNT,
+
+    /** SAI port stat PTP peer delay response timeouts */
+    SAI_PORT_STAT_PTP_PDELAY_RESP_TIMEOUT_COUNT,
+
+    /** SAI port stat PTP peer delay response followup timeouts */
+    SAI_PORT_STAT_PTP_PDELAY_RESP_FOLLOWUP_TIMEOUT_COUNT,
+
     /** SAI port stat sender credits used */
     SAI_PORT_STAT_CBFC_SENDER_CREDITS_USED,