SAI PTP Enhancements

Signed-off-by: Archisman Maitra <[email protected]>

Author: archis001-marvell

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

@@ -0,0 +1,182 @@
+# SAI PTP enhancement
+-------------------------------------------------------------------------------
+ Title       | SAI PTP Enhancement
+-------------|-----------------------------------------------------------------
+ Authors     | Archisman Maitra, Sree Shankar S, Ravindranath C K (Marvell)
+ Status      | In review
+ Type        | Standards track
+ Created     | 2025-09-11
+ SAI-Version | 1.18
+-------------------------------------------------------------------------------
+
+
+## 1.0  Introduction
+
+This proposal enhances the current PTP support in SAI.
+
+## 2.0  Overview
+
+### 2.1 Clocks managed by SAI
+
+PTP enabled devices are organized into a master−slave synchronization hierarchy with the clock at the top of the hierarchy (the grandmaster clock) determining the reference time for the entire system. SAI can configure timestamp mode (one-step/two-step) per port/switch with abstracted clock source. As part of PTP protocol, the slave computes the offset from the master. Today, this offset correction/frequency adjustment is not done via SAI. New SAI attributes are provided to program local clock (e.g. on-chip oscillator driving a PTP Hardware Clock (PHC) within the ASIC) of a PTP slave device when the clock is managed by SAI.
+
+**1. PTP Time Offset Adjustment**: This provides the functionality to apply time offset between master and slave device (PTP device is configured as non transparent clock) and should be applied in the slave device.
+
+**2. PTP Syntonization Adjustment**: This provides the functionality to apply frequency rate adjustments for slave clocks to match the master clock frequency (PTP device is configured as non transparent clock) preventing drift over time. This should be applied in the slave device.
+
+### 2.2 Peer-to-Peer transparent clock support
+
+Today SAI lacks support for Peer-to-Peer transparent clock.
+
+**1. PTP Peer Mean Path Delay**: This attribute allows application to configure one-way link propagation delay (in nanoseconds) from a port. The device uses this attribute value to adjust correction field in PTP event messages (e.g., Sync messages) to account for peer delay along with residence time.
+
+**2: Hostif Trap for PTP Peer Delay Messages**: This trap facilitates handling of Pdelay messages independent of other PTP messages. Non-Pdelay PTP messages should be forwarded, while Pdelay messages should terminate at the Peer-to-Peer Transparent Clock.
+
+## 3.0 SAI Spec Enhancement
+
+**New attributes defined for setting ptp time offset and ptp syntonize adjust**
+
+saiswitch.h
+```c
+typedef enum _sai_switch_attr_t
+{
+    /**
+     * @brief Time correction offset from epoch applied by NOS on system
+     *        clock to sync with master clock
+     *
+     * @type sai_timespec_t
+     * @flags CREATE_AND_SET
+     * @default 0
+     */
+    SAI_SWITCH_ATTR_PTP_TIME_OFFSET,
+
+    /**
+     * @brief Used by NOS to program the delta value that needs to be
+     *        added to existing clock frequency.
+     *        Unit is Parts Per Trillion
+     *
+     * @type sai_int32_t
+     * @flags CREATE_AND_SET
+     * @default 0
+     */
+    SAI_SWITCH_ATTR_PTP_SYNTONIZE_ADJUST,
+} sai_switch_attr_t;
+```
+**New attribute defined for setting ptp peer mean path delay**
+
+saiport.h
+```c
+typedef enum _sai_port_attr_t
+{
+    /**
+     * @brief One-way (From port to neighbor) link propagation delay in nanoseconds
+     *
+     * Device adds this value to PTP header correction-field along with residence time
+     * in Peer Delay Mechanism in Peer-to-Peer TC.
+     *
+     * @type sai_uint32_t
+     * @flags CREATE_AND_SET
+     * @default 0
+     */
+    SAI_PORT_ATTR_PTP_PEER_MEAN_PATH_DELAY
+} sai_port_attr_t;
+```
+**New attribute defined for trapping ptp peerdelay packets**
+
+saihostif.h
+```c
+typedef enum _sai_hostif_trap_type_t
+{
+    /**
+     * @brief Peer Delay PTP traffic.
+     * ((EtherType == 0x88F7 or UDP dst port == 319 or UDP dst port == 320)
+     * and (PTP messageType == 0x2 or PTP messageType == 0x3 or PTP messageType == 0x10))
+     * (default packet action is drop)
+     */
+    SAI_HOSTIF_TRAP_TYPE_PTP_PEER_DELAY = 0x00000015
+} sai_hostif_trap_type_t;
+```
+
+## 4.0 API Workflow and Example
+
+### 4.1 PTP Time Offset and Syntonization Adjustment
+
+![PTP-DelayReq-DelayResp](slave_offset_master.jpg)
+The diagram above shows PTP control message exchanges (one step timestamping) between a master and slave device using the delay request-response mechanism. After the control messages are exchanged, slave NOS can compute the clock offset from master and configure SAI_SWITCH_ATTR_PTP_TIME_OFFSET to synchronize the slave device clock with master.
+
+Example:-
+A time offset adjustment of 5 seconds and 80,000 nanoseconds is applied in the slave PTP device.
+
+```c
+    attr_count = 0;
+    attr_list[attr_count].id                        = SAI_SWITCH_ATTR_PTP_TIME_OFFSET;
+    attr_list[attr_count].value.timespec.tv_sec     = 5;
+    attr_list[attr_count++].value.timespec.tv_nsec  = 80000;
+    sai_set_switch_attribute_fn(switch_id, attr_list);
+```
+The slave clock may tick at a different rate than the master, resulting in time drift. Slave NOS can compute the frequency factor to align with the frequency of master clock and configure SAI_SWITCH_ATTR_PTP_SYNTONIZE_ADJUST to syntonize the slave clock with master.
+
+Example:-
+A syntonization adjustment of 5000 parts per trillion is applied in the slave PTP device.
+
+```c
+    attr_count = 0;
+    attr_list[attr_count].id                = SAI_SWITCH_ATTR_PTP_SYNTONIZE_ADJUST;
+    attr_list[attr_count++].value.value.s32 = 5000;
+    sai_set_switch_attribute_fn(switch_id, attr_list);
+```
+
+### 4.3 PTP Peer Mean Path Delay
+
+![PTP-Peer-Delay](p2p_tc.jpg)
+
+The diagram above illustrates the exchange of PTP control messages (using one-step timestamping) between a master and a slave device, with a Peer-to-Peer Transparent Clock (P2PTC) acting as an intermediary. This setup uses the peer delay mechanism. The P2PTC NOS calculates the peer mean path delay for each port by exchanging peer delay messages with its immediate neighbor. Once computed, this delay is configured on the port using the SAI_PORT_ATTR_PTP_PEER_MEAN_PATH_DELAY attribute.
+
+Subsequently, the NPU adds both the configured peer mean path delay and the residence time to the correction field of the PTP header for event messages (such as Sync and Delay_Req) that are forwarded through the port.
+
+Example:-
+PTP peer mean path delay of 14000 nsec is applied to the port for PTP device configured as peer to peer transparent clock. For all PTP event messages received on this port, this peer mean path delay will be added along with the residence time in the correction field of the PTP header.
+
+```c
+    attr_count = 0;
+    attr_list[attr_count].id          = SAI_PORT_ATTR_PTP_PEER_MEAN_PATH_DELAY;
+    attr_list[attr_count++].value.u32 = 14000;
+    sai_set_port_attribute_fn(port_id, attr_list);
+```
+
+### 4.4 Hostif Trap for PTP Peer Delay Messages
+
+For Peer-to-peer transparent clock, peer delay PTP packets are terminated at the device and non-peer delay PTP packets are forwarded. The P2PTC NOS should configure SAI_HOSTIF_TRAP_TYPE_PTP_PEER_DELAY with the action set to TRAP with higher priority than SAI_HOSTIF_TRAP_TYPE_PTP with the action set as FORWARD to facilitate this behavior.
+
+```c
+    ...
+    attr_list[attr_count].id          = SAI_HOSTIF_TRAP_ATTR_PACKET_ACTION;
+    attr_list[attr_count++].value.u32 = SAI_PACKET_ACTION_FORWARD; // Action for non-pdelay PTP pkts in P2P TC
+
+    attr_list[attr_count].id          = SAI_HOSTIF_TRAP_ATTR_TRAP_TYPE;
+    attr_list[attr_count++].value.u32 = SAI_HOSTIF_TRAP_TYPE_PTP;
+
+    attr_list[attr_count].id          = SAI_HOSTIF_TRAP_ATTR_TRAP_PRIORITY;
+    attr_list[attr_count++].value.u32 = 1; // Lower priority for non-pdelay PTP packets
+
+    sai_create_hostif_trap_fn(&ptp_trap_id, switch_id, attr_count, attr_list);
+
+    ...
+    attr_list[attr_count].id          = SAI_HOSTIF_TRAP_ATTR_PACKET_ACTION;
+    attr_list[attr_count++].value.u32 = SAI_PACKET_ACTION_TRAP; // Action for pdelay PTP pkts in P2P TC
+
+    attr_list[attr_count].id          = SAI_HOSTIF_TRAP_ATTR_TRAP_TYPE;
+    attr_list[attr_count++].value.u32 = SAI_HOSTIF_TRAP_TYPE_PTP_PEER_DELAY;
+
+    attr_list[attr_count].id          = SAI_HOSTIF_TRAP_ATTR_TRAP_PRIORITY;
+    attr_list[attr_count++].value.u32 = 2; // Higher priority for pdelay PTP packets
+
+    sai_create_hostif_trap_fn(&ptp_peer_trap_id, switch_id, attr_count, attr_list);
+```
+
+## 5.0 References
+IEEE 1588-2008 Standard for a Precision Clock Synchronization Protocol for Networked Measurement and Control Systems
+
+## 6.0 Warmboot Implications
+None
+

doc/PTP/p2p_tc.jpg

@@ -0,0 +1,38 @@
+# Fast Link-Up
+-------------------------------------------------------------------------------
+ Title       | Fast Link-Up
+-------------|-----------------------------------------------------------------
+ Authors     | Eddy Kvetny, Nvidia
+ Status      | In review
+ Type        | Standards track
+ Created     | 2025-09-09
+ SAI-Version | 1.17
+-------------------------------------------------------------------------------
+
+# 1. Overview
+In some cases the equalization parameters from the previous session can be used for a new link-up process. It can significantly reduce time of the Link-Up process
+
+# 2. Scope
+This approach is applicable to devices (switch-to-switch or switch-to-NIC) supporting this process, usually from the same vendor or from different vendors aligned on the process.
+
+Can be applied to cold/fast boot or link recovery flows (vendor decision)
+
+# 3. Architecture
+This feature shall be enabled per-port using a new SAI attribute - SAI_PORT_ATTR_FAST_LINKUP_ENABLED (default status - disabled/false)
+
+On ports with the enabled feature the ASIC FW shall try first to bring a link up using the equalization parameter stored from the previous successul session. The time given to ASIC to try to bring a link up with the old EQ parameters is limited by the Fast Link-Up Polling Timer. The time value is configured using a new SAI attribute - SAI_SWITCH_ATTR_FAST_LINKUP_POLLING_TIMEOUT. The supported range for this value (in secs) can be read by NOS using a new SAI attribute  SAI_SWITCH_ATTR_FAST_LINKUP_POLLING_TIMEOUT_RANGE
+
+If the process of brining a link up with the previosly used EQ parameters doesn't succeed the regular link-up process is triggered
+
+If the link succeeds moving to the Operation UP state then the BER level shall be checked to make sure that the establish link has a good quality. To do that another timer called Guard Timer is used. Its value is also configurable using a new SAI attribute (SAI_SWITCH_ATTR_FAST_LINKUP_GUARD_TIMEOUT)
+
+
+When the Guard Timer expires the BER is measured and compared with the "good" BER value configured using a new SAI attribure SAI_SWITCH_ATTR_FAST_LINKUP_BER_THRESHOLD. Only if the measured BER is equal or better than the configured BER threshold the process is considered completed. Otherwise, the fallback to the regular link-up process is done and link's Oper status changes to DOWN
+
+If the remote side doesn't support the Fast Link-up then the fallback to regular process will happen
+
+Note that the State Machine is implemented by ASIC FW and can vary between vendors. The proposal just defines just high level flow and SAI configuration for this flow
+
+The following State Machine is proposed for the Fast Link-UP process described above
+
+![](figures/sai_fast_linkup_state_machine.png)

doc/PTP/slave_offset_master.jpg

@@ -212,3 +212,15 @@ typedef enum _sai_packet_trim_dscp_resolution_mode_t
      */
     SAI_SWITCH_ATTR_PACKET_TRIM_DSCP_RESOLUTION_MODE,
 ```
+
+## Counter
+|Header file|SAI attribute|Description|
+|-----------|-------------|-----------|
+|saiswitch.h|SAI_SWITCH_STAT_DROPPED_TRIM_PACKETS|Global counter (aggregated value of all ports) of packets trimmed but dropped due to failed shared buffer admission on a trim queue|
+|           |SAI_SWITCH_STAT_TX_TRIM_PACKETS|Global counter (aggregated value of all ports) of packets trimmed and successfully sent via a trim queue|
+|saiport.h  |SAI_PORT_STAT_TRIM_PACKETS|Per-port counter of packets trimmed due to failed shared buffer admission|
+|           |SAI_PORT_STAT_DROPPED_TRIM_PACKETS|Per-port counter of packets trimmed but dropped due to failed shared buffer admission on a trim queue|
+|           |SAI_PORT_STAT_TX_TRIM_PACKETS|Per-port counter of packets trimmed and successfully sent via a trim queue|
+|saiqueue.h |SAI_QUEUE_STAT_TRIM_PACKETS|Per-queue counter of packets trimmed on trimming-eligible queue due to failed shared buffer admission|
+|           |SAI_QUEUE_STAT_DROPPED_TRIM_PACKETS|Per-queue counter of packets trimmed on trimming-eligible queue but dropped due to failed shared buffer admission on a trim queue|
+|           |SAI_QUEUE_STAT_TX_TRIM_PACKETS|Per-queue counter of packets trimmed on trimming-eligible queue and successfully sent via a trim queue|

doc/SAI-Proposal-Fast-Linkup.md

@@ -258,6 +258,14 @@ typedef enum _sai_hostif_trap_type_t
      */
     SAI_HOSTIF_TRAP_TYPE_ESMC = 0x00000014,
 
+    /**
+     * @brief Peer Delay PTP traffic.
+     * ((EtherType == 0x88F7 or UDP dst port == 319 or UDP dst port == 320)
+     * and (PTP messageType == 0x2 or PTP messageType == 0x3 or PTP messageType == 0x10))
+     * (default packet action is drop)
+     */
+    SAI_HOSTIF_TRAP_TYPE_PTP_PEER_DELAY = 0x00000015,
+
     /** Switch traps custom range start */
     SAI_HOSTIF_TRAP_TYPE_SWITCH_CUSTOM_RANGE_BASE = 0x00001000,