SAI Egress DSCP action behavior

doc/ACL/SAI-Proposal-ACL-1.md

@@ -334,6 +334,7 @@ This example creates and ACL group with more than one ACL table and bind it to a
 
 ### Example 4 - Binding an ACL group to a set of ports
 This example creates an ACL group and binds it to multiple ports.
+
     // Bind this ACL group *acl_grp_id1* to port2, and port20s OID.
     port_attr_list.count = 1;
     port_attr_list.list[0].id = SAI_PORT_ATTR_INGRESS_ACL;

doc/IP-Multicast/MulticastNextHopRewrite.md

@@ -0,0 +1,80 @@
+# SAI attributes for disabling L3 rewrites
+
+# for IP Multicast forwarding
+
+```
+Author:mholankar@
+```
+
+## Overview
+
+This document discusses requirements and the SAI spec proposal for disabling rewriting fields (SourceMAC, VLAN) as part of IPMC routing.
+
+## Background
+
+### SAI pipeline for IPMC forwarding. After Multicast Replication, the egress
+
+### pipeline is very similar to Unicast Forwarding. The reference pipeline is
+
+### fromUnicastForwarding.
+
+- Nexthop sets the egress RIF and NextHopIP
+- Neighbor table lookup on NextHopIP to set packet's destination MAC address
+- Egress RIF lookup to set packet's source MAC address, VLAN and port.
+
+## Requirements
+
+We require knobs for disabling rewrites to following fields as part of Multicast forwarding flows
+
+```
+● Src MAC disable
+● Vlan rewrite disable
+```
+
+We have scenarios where we need knobs for disabling header field rewrites, for Multicast Replication.
+
+Case1:For certain flows, the switch does MulticastReplication for a VLAN tagged packet. However, we do not want the VLAN tag to be over-written during replication, we want the replication to retain the VLAN tag. For such a case we would like to disable L3 VLAN rewrite. Please note: that when a disable L3 Vlan rewrite
+flag is enabled, it does allow for untagged packets to get replicated.
+
+Case2: For some scenarios, we may want to rewrite the SRC MAC. Having NextHop based knobs for such rewrites would be very helpful.
+
+In summary, with SDN based forwarding, Controller treats the L2 fields like any other header field which can be controlled and requires them to be configured flexibility as part of MulticastReplication.
+
+## Proposal
+
+Since we require capability to disable the rewrites for certain Multicast flows and not for all flows via/to neighbor, the best option is to have these as part of NextHop object:
+
+- SAI_NEXT_HOP_ATTR_DISABLE_SRC_MAC_REWRITE
+- SAI_NEXT_HOP_ATTR_DISABLE_DST_MAC_REWRITE
+- SAI_NEXT_HOP_ATTR_DISABLE_VLAN_REWRITE
+
+### Example SAI object creation for an IPMCGroup:
+
+- Create a **SAI_OBJECT_TYPE_IPMC_GROUP** for the multicast group with the following attributes.
+- Create a SAI_OBJECT_TYPE_ROUTER_INTERFACE with following attributes:
+● SAI_ROUTER_INTERFACE_ATTR_VIRTUAL_ROUTER_ID
+● SAI_ROUTER_INTERFACE_ATTR_SRC_MAC_ADDRESS
+● SAI_ROUTER_INTERFACE_ATTR_TYPE=SAI_ROUTER_INTERFACE_TYPE_
+
+  ```
+  PORT
+  ```
+
+● SAI_ROUTER_INTERFACE_ATTR_PORT_ID
+- Create a SAI_OBJECT_TYPE_NEIGHBOR_ENTRY for each neighbor with:
+● "ip"=Link local address ● "rif" ● "switch id"
+● SAI_NEIGHBOR_ENTRY_ATTR_DST_MAC_ADDRESS(optional)
+● SAI_NEIGHBOR_ENTRY_ATTR_NO_HOST_ROUTE=true
+- Create SAI_OBJECT_TYPE_NEXT_HOP with:
+● SAI_NEXT_HOP_ATTR_TYPE=SAI_NEXT_HOP_TYPE_IPMC
+● SAI_NEXT_HOP_ATTR_ROUTER_INTERFACE_ID
+● SAI_NEXT_HOP_ATTR_IP="ip"of neighbor
+
+```
+● SAI_NEXT_HOP_ATTR_DISABLE_SRC_MAC_REWRITE=true
+● SAI_NEXT_HOP_ATTR_DISABLE_VLAN_REWRITE=true
+```
+
+- Create a **SAI_OBJECT_TYPE_IPMC_GROUP_MEMBER** with following attributes:
+● SAI_IPMC_GROUP_MEMBER_ATTR_IPMC_GROUP_ID with ipmc_group_oid
+● SAI_IPMC_GROUP_MEMBER_ATTR_IPMC_OUTPUT_ID with next_hop_oid

doc/QOS/SAI-Proposal-Egress-DSCP.md

@@ -0,0 +1,73 @@
+SAI Egress DSCP action behavior
+-------------------------------------------------------------------------------
+ Title       | SAI Egress DSCP action behavior
+-------------|-----------------------------------------------------------------
+ Authors     | Shahzad Iqbal, Microsoft Corp.
+ Status      | In review
+ Type        | Standards track
+ Created     | 07/10/2024
+ SAI-Version | 1.14
+-------------------------------------------------------------------------------
+
+This spec documents the behavior of various components which set DSCP value in the Egress packet pipeline.
+
+# Overview #
+
+There are various components with the capability to change the DSCP value of an L3 packet based on a match criteria. A clear order of precedence is needed for predictable behavior if multiple subsystems in the packet pipeline change this value.
+
+# Scope #
+
+This document only addresses the Egress stage of the packet pipeline. It does not specify any precedence for the ingress stage DSCP value change.
+## SAI functions capable of changing DSCP. ##
+There are currently 6 components in SAI which have the ability to change the DSCP value directly of a given packet. 'There are indirect ways to change the DSCP value such as ACL -> TC -> DSCP map but those fall out of the scope of this document.'
+
+-------------------------------------------------------------------------------
+ Function                             | SAI attribute 
+--------------------------------------|----------------------------------------
+ Switch Qos TC-COLOR -> DSCP map      | SAI_SWITCH_ATTR_QOS_TC_AND_COLOR_TO_DSCP_MAP
+ Switch Tunnel TC-COLOR -> DSCP map   | SAI_SWITCH_TUNNEL_ATTR_ENCAP_QOS_TC_AND_COLOR_TO_DSCP_MAP
+ Tunnel DSCP mode                     | SAI_TUNNEL_DSCP_MODE_PIPE_MODEL, SAI_TUNNEL_DSCP_MODE_UNIFORM_MODEL 
+ Tunnel TC-COLOR -> DSCP mapping      | SAI_TUNNEL_ATTR_ENCAP_QOS_TC_AND_COLOR_TO_DSCP_MAP 
+ Port Qos TC-COLOR -> DSCP map        | SAI_PORT_ATTR_QOS_TC_AND_COLOR_TO_DSCP_MAP,
+ Egress ACL DSCP change action        | ACL SAI_ACL_ENTRY_ATTR_ACTION_SET_DSCP 
+-------------------------------------------------------------------------------
+
+Since these components operate in different positions in a  ASIC pipeline, a possibility exists that DSCP value change performed by one component may be undone by the subsequent component. 
+
+The overall behavior can be segregated into three sections of the pipeline. Ingress, post-Ingress and Egress. This document focuses solely on the Egress section of the pipeline. 
+
+# Model for Egress Behavior #
+The DSCP value set by various components on the egress side of the ASIC pipeline shall have the following precedence in descending order. This precedence shall apply to packets in the egress pipeline and shall override any other DSCP value set by the Ingress stage.
+**However This precedence would be overriden if the platform provides the necessary SAI capibility API for Egress precedence check. This SAI API currently does not exist but would be added at a later date. For further details, please refer to the Community feedback section of this document.**
+
+1. Egress ACL.
+
+2. Tunnel DSCP mapping 
+    - Tunnel TC-COLOR -> DSCP mapping
+    - Tunnel DSCP mode
+    - Switch Tunnel TC-COLOR -> DSCP map
+
+3. Port Qos TC-COLOR -> DSCP map
+
+4. Switch Qos TC-COLOR -> DSCP map
+
+## Examples of packet behavior. ##
+
+These following is a logical diagram which shows how the DSCP value of a packet may be changed by different components. This diagram does not represent the actual layout of the pipeline.
+
+<img src="../figures/egress_dscp_change_precedence.png" width="1200">
+
+
+## Community Feedback ##
+After discussion with the SAI community the following feedback was recieved.
+
+1. The proposal should be enhanced to cover for both Ingress and Egress stages of pipelines.
+
+2. A SAI attribute should be devised to query the precedence behaviour set by the platform.
+
+The following issues have been created to track these additional enhancements.
+
+https://github.com/opencomputeproject/SAI/issues/2080 Request for SAI Ingress DSCP/TC precedence behavior document.
+
+https://github.com/opencomputeproject/SAI/issues/2081 Request for SAI capability check to determine the Ingress/Egress DSCP/TC action precedence supported by the ASIC
+

doc/SAI-Proposal-FRR.md

@@ -89,7 +89,7 @@ Entity.
 
 The switchover from the primary next hop to backup is triggered once a failure
 of a particular object is spotted.  This object can be a physical port, a tunnel
-interface, BFD session etc.
+interface, BFD session, ICMP ECHO session etc.
 
 It is preferred that the switchover is triggered by the switching entity without
 involving control plane in the process.  This way the amount of time it takes to
@@ -173,7 +173,7 @@ be of one of the types that the hardware is able to monitor.
 -  SAI\_NEXT\_HOP\_GROUP\_MEMBER\_ATTR\_MONITORED\_OBJECT
 
 This attribute allows the switching entity to monitor a specified object
-(BFD session, physical port, tunnel interface etc) and in case of its failure,
+(BFD session, ICMP ECHO session, physical port, tunnel interface etc) and in case of its failure,
 trigger a switchover.
 
 If the referred object fails, then the switch marks the next hop as FAILED and does not use it for forwarding.