diff --git a/doc/hash/hash-design.md b/doc/hash/hash-design.md index 005184a0db..0b3ac0803c 100644 --- a/doc/hash/hash-design.md +++ b/doc/hash/hash-design.md @@ -24,11 +24,17 @@ - [2.4 DB schema](#24-db-schema) - [2.4.1 Config DB](#241-config-db) - [2.4.1.1 Switch hash](#2411-switch-hash) - - [2.4.2 Data sample](#242-data-sample) - - [2.4.3 Configuration sample](#243-configuration-sample) - - [2.4.4 Initial configuration](#244-initial-configuration) + - [2.4.2 State DB](#242-state-db) + - [2.4.2.1 Switch hash capabilities](#2421-switch-hash-capabilities) + - [2.4.3 Data sample](#243-data-sample) + - [2.4.4 Configuration sample](#244-configuration-sample) + - [2.4.5 Initial configuration](#245-initial-configuration) - [2.5 Flows](#25-flows) - - [2.5.1 GH update](#251-gh-update) + - [2.5.1 Config section](#251-config-section) + - [2.5.1.1 GH update](#2511-gh-update) + - [2.5.2 Show section](#252-show-section) + - [2.5.2.1 GH show](#2521-gh-show) + - [2.5.2.2 GH show capabilities](#2522-gh-show-capabilities) - [2.6 CLI](#26-cli) - [2.6.1 Command structure](#261-command-structure) - [2.6.2 Usage examples](#262-usage-examples) @@ -44,7 +50,8 @@ | Rev | Date | Author | Description | |:---:|:----------:|:--------------:|:------------------------------------------------| -| 0.1 | 12/09/2021 | Nazarii Hnydyn | Initial version | +| 0.1 | 12/09/2022 | Nazarii Hnydyn | Initial version | +| 0.2 | 05/12/2022 | Nazarii Hnydyn | Capabilities validation | ## About this manual @@ -84,7 +91,9 @@ This document describes the high level design of GH feature in SONiC [Figure 1: GH design](#figure-1-gh-design) [Figure 2: GH OA design](#figure-2-gh-oa-design) -[Figure 3: GH update flow](#figure-3-gh-update-flow) +[Figure 3: GH update flow](#figure-3-gh-update-flow) +[Figure 4: GH show flow](#figure-4-gh-show-flow) +[Figure 5: GH show capabilities flow](#figure-5-gh-show-capabilities-flow) ## List of tables @@ -183,6 +192,12 @@ GH provides global switch hash configuration for ECMP and LAG. GH will use SAI Hash API to configure user-defined list of hash fields to ASIC. Hashing policy can be set independently for ECMP and LAG. +**GH important notes:** +1. According to the SAI Behavioral Model, the hash is calculated on ingress to pipeline +2. SAI configuration of hash fields is applicable to an original packet before any DECAP/ENCAP, +i.e. configuration is tunnel-agnostic +3. If some configured field is not present in an incoming packet, then zero is assumed for hash calculation + ## 2.2 SAI API **SAI native hash fields which shall be used for GH:** @@ -210,11 +225,15 @@ Hashing policy can be set independently for ECMP and LAG. **SAI attributes which shall be used for GH:** -| API | Function | Attribute | -|:-------|:---------------------|:-------------------------------------| -| SWITCH | get_switch_attribute | SAI_SWITCH_ATTR_ECMP_HASH | -| | | SAI_SWITCH_ATTR_LAG_HASH | -| HASH | set_hash_attribute | SAI_HASH_ATTR_NATIVE_HASH_FIELD_LIST | +| API | Function | Attribute | +|:-------|:-------------------------------------------|:-------------------------------------| +| OBJECT | sai_query_attribute_capability | SAI_SWITCH_ATTR_ECMP_HASH | +| | | SAI_SWITCH_ATTR_LAG_HASH | +| | | SAI_HASH_ATTR_NATIVE_HASH_FIELD_LIST | +| | sai_query_attribute_enum_values_capability | SAI_HASH_ATTR_NATIVE_HASH_FIELD_LIST | +| SWITCH | get_switch_attribute | SAI_SWITCH_ATTR_ECMP_HASH | +| | | SAI_SWITCH_ATTR_LAG_HASH | +| HASH | set_hash_attribute | SAI_HASH_ATTR_NATIVE_HASH_FIELD_LIST | ## 2.3 Orchestration agent @@ -243,9 +262,13 @@ This class is responsible for: 4. Caching objects in order to handle updates Switch hash object is stored under `SWITCH_HASH|GLOBAL` key in Config DB. On `SWITCH_HASH` update, -method `PbhOrch::doCfgSwitchHashTableTask()` will be called to process the change. +method `SwitchOrch::doCfgSwitchHashTableTask()` will be called to process the change. Regular switch hash update will refresh the internal class structures and appropriate SAI objects. +Switch hash capabilities are stored under `SWITCH_CAPABILITY|switch` key in State DB. +The vendor specific data is being queried by switch OA on init and pushed to both internal cache and DB. +Any further switch hash update is being validated using vendor specific hash capabilities. + **Skeleton code:** ```cpp class SwitchOrch : public Orch @@ -319,7 +342,43 @@ hash-field = "IN_PORT" hash-field-list = hash-field [ 1*( "," hash-field ) ] ``` -### 2.4.2 Data sample +### 2.4.2 State DB + +#### 2.4.2.1 Switch hash capabilities +```abnf +; defines schema for switch hash configuration capabilities +key = SWITCH_CAPABILITY|switch ; must be unique + +; field = value +ECMP_HASH_CAPABLE = capability-knob ; specifies whether switch is ECMP hash capable +LAG_HASH_CAPABLE = capability-knob ; specifies whether switch is LAG hash capable +HASH|NATIVE_HASH_FIELD_LIST = hash-field-list ; hash field capabilities for hashing packets going through switch + +; value annotations +capability-knob = "true" / "false" +hash-field = "" + / "IN_PORT" + / "DST_MAC" + / "SRC_MAC" + / "ETHERTYPE" + / "VLAN_ID" + / "IP_PROTOCOL" + / "DST_IP" + / "SRC_IP" + / "L4_DST_PORT" + / "L4_SRC_PORT" + / "INNER_DST_MAC" + / "INNER_SRC_MAC" + / "INNER_ETHERTYPE" + / "INNER_IP_PROTOCOL" + / "INNER_DST_IP" + / "INNER_SRC_IP" + / "INNER_L4_DST_PORT" + / "INNER_L4_SRC_PORT" +hash-field-list = hash-field [ 1*( "," hash-field ) ] +``` + +### 2.4.3 Data sample **Config DB:** ```bash @@ -332,7 +391,20 @@ INNER_DST_MAC,INNER_SRC_MAC,INNER_ETHERTYPE,INNER_IP_PROTOCOL,INNER_DST_IP,INNER INNER_DST_MAC,INNER_SRC_MAC,INNER_ETHERTYPE,INNER_IP_PROTOCOL,INNER_DST_IP,INNER_SRC_IP,INNER_L4_DST_PORT,INNER_L4_SRC_PORT" ``` -### 2.4.3 Configuration sample +**State DB:** +```bash +redis-cli -n 6 HGETALL 'SWITCH_CAPABILITY|switch' + 1) "ECMP_HASH_CAPABLE" + 2) "true" + 3) "LAG_HASH_CAPABLE" + 4) "true" + 5) "HASH|NATIVE_HASH_FIELD_LIST" + 6) "IN_PORT,DST_MAC,SRC_MAC,ETHERTYPE,VLAN_ID,IP_PROTOCOL,DST_IP,SRC_IP,L4_DST_PORT,L4_SRC_PORT, \ +INNER_DST_MAC,INNER_SRC_MAC,INNER_ETHERTYPE,INNER_IP_PROTOCOL,INNER_DST_IP,INNER_SRC_IP, \ +INNER_L4_DST_PORT,INNER_L4_SRC_PORT" +``` + +### 2.4.4 Configuration sample **Outer/Inner frame hashing:** ```json @@ -380,7 +452,7 @@ INNER_DST_MAC,INNER_SRC_MAC,INNER_ETHERTYPE,INNER_IP_PROTOCOL,INNER_DST_IP,INNER } ``` -### 2.4.4 Initial configuration +### 2.4.5 Initial configuration GH initial configuration will be updated at `sonic-buildimage/files/build_templates/init_cfg.json.j2` in order to match vendor specific requirements. @@ -421,12 +493,34 @@ in order to match vendor specific requirements. ## 2.5 Flows -### 2.5.1 GH update +### 2.5.1 Config section + +### 2.5.1.1 GH update ![GH update flow](images/gh_update_flow.svg "Figure 3: GH update flow") ###### Figure 3: GH update flow +**Note:** + +The list of available hash fields will be queried by `sai_query_attribute_enum_values_capability` in two steps. +The first attempt is used to accommodate the target list size after getting `SAI_STATUS_BUFFER_OVERFLOW` return code. +And the second one is for getting the actual data. + +### 2.5.2 Show section + +#### 2.5.2.1 GH show + +![GH show flow](images/gh_show_flow.svg "Figure 4: GH show flow") + +###### Figure 4: GH show flow + +#### 2.5.2.2 GH show capabilities + +![GH show capabilities flow](images/gh_show_cap_flow.svg "Figure 5: GH show capabilities flow") + +###### Figure 5: GH show capabilities flow + ## 2.6 CLI ### 2.6.1 Command structure @@ -442,6 +536,7 @@ config show |--- switch-hash |--- global + |--- capabilities ``` ### 2.6.2 Usage examples @@ -511,6 +606,31 @@ INNER_L4_DST_PORT INNER_L4_DST_PORT INNER_L4_SRC_PORT INNER_L4_SRC_PORT ``` +**The following command shows switch hash capabilities:** +```bash +root@sonic:/home/admin# show switch-hash capabilities +ECMP HASH LAG HASH +----------------- ----------------- +IN_PORT IN_PORT +DST_MAC DST_MAC +SRC_MAC SRC_MAC +ETHERTYPE ETHERTYPE +VLAN_ID VLAN_ID +IP_PROTOCOL IP_PROTOCOL +DST_IP DST_IP +SRC_IP SRC_IP +L4_DST_PORT L4_DST_PORT +L4_SRC_PORT L4_SRC_PORT +INNER_DST_MAC INNER_DST_MAC +INNER_SRC_MAC INNER_SRC_MAC +INNER_ETHERTYPE INNER_ETHERTYPE +INNER_IP_PROTOCOL INNER_IP_PROTOCOL +INNER_DST_IP INNER_DST_IP +INNER_SRC_IP INNER_SRC_IP +INNER_L4_DST_PORT INNER_L4_DST_PORT +INNER_L4_SRC_PORT INNER_L4_SRC_PORT +``` + ## 2.7 YANG model Existing YANG model template `sonic-types.yang.j2` at `sonic-buildimage/src/sonic-yang-models/yang-templates` diff --git a/doc/hash/images/gh_show_cap_flow.svg b/doc/hash/images/gh_show_cap_flow.svg new file mode 100644 index 0000000000..0a5fa549e8 --- /dev/null +++ b/doc/hash/images/gh_show_cap_flow.svg @@ -0,0 +1,137 @@ + + + + + gh show cap flow + + + + + + + + + + + + + + + + + + + Page-10 + + Actor lifeline.1198 + StateDB + + Sheet.1001 + + + + Sheet.1002 + + + + Sheet.1003 + + + Sheet.1004 + + + + + StateDB + + + Actor lifeline.1213 + CLI + + Sheet.1006 + + + + Sheet.1007 + + + + Sheet.1008 + + + Sheet.1009 + + + + + CLI + + + Activation.1098 + + + + Self Message.1099 + process data + + + process data + + Activation.1102 + + + + Self Message.1103 + get switch capabilities + + + get switch capabilities + + Activation.1104 + + + + Message.1105 + HGETALL SWITCH_CAPABILITY|switch + + + HGETALL SWITCH_CAPABILITY|switch + + Activation.1106 + + + + Return Message.1107 + + + + Activation.1044 + + + + Self Message.1045 + display data + + + display data + + diff --git a/doc/hash/images/gh_show_flow.svg b/doc/hash/images/gh_show_flow.svg new file mode 100644 index 0000000000..f31e79dc94 --- /dev/null +++ b/doc/hash/images/gh_show_flow.svg @@ -0,0 +1,136 @@ + + + + + gh show flow + + + + + + + + + + + + + + + + + + + Page-11 + + Actor lifeline.1198 + ConfigDB + + Sheet.1001 + + + + Sheet.1002 + + + + Sheet.1003 + + + Sheet.1004 + + + + + ConfigDB + + + Actor lifeline.1213 + CLI + + Sheet.1006 + + + + Sheet.1007 + + + + Sheet.1008 + + + Sheet.1009 + + + + + CLI + + + Activation.1098 + + + + Self Message.1099 + process data + + + process data + + Activation.1102 + + + + Self Message.1103 + get switch hash + + + get switch hash + + Activation.1104 + + + + Message.1105 + HGETALL SWITCH_HASH|GLOBAL + + + HGETALL SWITCH_HASH|GLOBAL + + Activation.1106 + + + + Return Message.1107 + + + + Activation.1044 + + + + Self Message.1045 + display data + + + display data + + diff --git a/doc/hash/images/gh_update_flow.svg b/doc/hash/images/gh_update_flow.svg index b2a5e73cf8..b5eae557e0 100644 --- a/doc/hash/images/gh_update_flow.svg +++ b/doc/hash/images/gh_update_flow.svg @@ -1,9 +1,9 @@ - + + width="19.1163in" height="19.5663in" viewBox="0 0 1376.37 1408.77" xml:space="preserve" color-interpolation-filters="sRGB" + class="st18"> gh update flow @@ -39,210 +44,355 @@ - Page-8 - + Page-12 + Actor lifeline.1198 ConfigDB Sheet.1001 - + Sheet.1002 - + - + Sheet.1003 - + Sheet.1004 - + - - ConfigDB + + ConfigDB - + Object lifeline.1203 SwitchOrch Sheet.1006 - + Sheet.1007 - + - + Sheet.1008 - + Sheet.1009 - + - - SwitchOrch + + SwitchOrch - + Object lifeline.1208 SAI Sheet.1011 - + Sheet.1012 - + - + Sheet.1013 - + Sheet.1014 - + - - SAI + + SAI - + Actor lifeline.1213 CLI Sheet.1016 - + Sheet.1017 - + - + Sheet.1018 - + Sheet.1019 - + - - CLI + + CLI - + Activation.1098 - + - + Self Message.1099 process data - - - process data - + + + process data + Activation.1102 - + - + Self Message.1103 set switch hash - - - set switch hash - + + + set switch hash + Activation.1104 - + - + Message.1105 HMSET SWITCH_HASH|GLOBAL - - - HMSET SWITCH_HASH|GLOBAL - + + + HMSET SWITCH_HASH|GLOBAL + Activation.1106 - + - + Return Message.1107 - + - + Activation.1188 - + - + Self Message.1189 set switch ecmp/lag hash field list - - - set switch ecmp/lag hash field list - + + + set switch ecmp/lag hash field list + Activation.1190 - + - + Asynchronous Message.1240 SWITCH_HASH|GLOBAL - - - SWITCH_HASH|GLOBAL - + + + SWITCH_HASH|GLOBAL + Activation.1241 - + - + Self Message.1242 process data - - - process data - + + + process data + Message.1244 set_hash_attribute - - - set_hash_attribute - + + + set_hash_attribute + Activation.1245 - + - + Return Message.1246 return <status> - - - return <status> - + + + return <status> + Activation.1247 - + - + Self Message.1248 get switch ecmp/lag hash oid - - - get switch ecmp/lag hash oid - + + + get switch ecmp/lag hash oid + Activation.1249 - + - + Message.1250 get_switch_attribute - - - get_switch_attribute - + + + get_switch_attribute + Activation.1251 - + - + Return Message.1252 return <status> - - - return <status> + + + return <status> + + Activation.1044 + + + + Self Message.1045 + get switch ecmp/lag hash capabilities + + + get switch ecmp/lag hash capabilities + + Activation.1046 + + + + Message.1047 + sai_query_attribute_capability + + + sai_query_attribute_capability + + Activation.1048 + + + + Return Message.1049 + return <status> + + + return <status> + + Message.1050 + sai_query_attribute_enum_values_capability + + + sai_query_attribute_enum_values_capability + + Activation.1051 + + + + Return Message.1052 + return <status> + + + return <status> + + Optional fragment.1059 + + + + + Sheet.1053 + opt + + opt + + Sheet.1054 + capability is validated + capability is validated + + + Loop fragment.1063 + + + + + Sheet.1056 + query + + query + + + Loop fragment.1066 + + + + + Sheet.1059 + query + + query + + + Actor lifeline.1069 + StateDB + + Sheet.1062 + + + + Sheet.1063 + + + + Sheet.1064 + + + Sheet.1065 + + + + + StateDB + + + Activation.1066 + + + + Self Message.1075 + push switch ecmp/lag hash capabilities to DB + + + push switch ecmp/lag hash capabilities to DB + + Activation.1076 + + + + Message.1077 + HMSET SWITCH_CAPABILITY|switch + + + HMSET SWITCH_CAPABILITY|switch + + Activation.1078 + + + + Return Message.1079 + + + + Sheet.1074 + SAI_SWITCH_ATTR_ECMP_HASH SAI_SWITCH_ATTR_LAG_HASH SAI_HASH_A... + + SAI_SWITCH_ATTR_ECMP_HASH SAI_SWITCH_ATTR_LAG_HASH SAI_HASH_ATTR_NATIVE_HASH_FIELD_LIST + + Sheet.1076 + SAI_HASH_ATTR_NATIVE_HASH_FIELD_LIST + + SAI_HASH_ATTR_NATIVE_HASH_FIELD_LIST