From c2741b8d5f48409a1afca51cce31cc2876271466 Mon Sep 17 00:00:00 2001 From: Stephen Sun Date: Fri, 5 Sep 2025 08:19:31 +0000 Subject: [PATCH 1/2] Check mirror capability before configuring it or setting it to SAI Signed-off-by: Stephen Sun --- .../SONiC_Port_Mirroring_HLD.md | 214 ++++++++++++++++-- 1 file changed, 194 insertions(+), 20 deletions(-) diff --git a/doc/port-mirroring/SONiC_Port_Mirroring_HLD.md b/doc/port-mirroring/SONiC_Port_Mirroring_HLD.md index d04f92f4404..4a8abd7a5df 100644 --- a/doc/port-mirroring/SONiC_Port_Mirroring_HLD.md +++ b/doc/port-mirroring/SONiC_Port_Mirroring_HLD.md @@ -25,15 +25,16 @@ * [3.3 Switch State Service Design](#33-switch-state-service-design) * [3.3.1 Orchestration Agent](#331-orchestration-agent) * [3.3.2 Other Process](#332-other-process) - * [3.4 SAI](#35-sai) - * [3.5 CLI](#36-cli) - * [3.5.1 Data Models](#351-data-models) - * [3.5.2 Configuration Commands](#352-configuration-commands) - * [3.5.3 Show Commands](#353-show-commands) - * [3.5.4 Clear Commands](#354-clear-commands) - * [3.5.5 Debug Commands](#355-debug-commands) - * [3.5.6 Rest API Support](#356-rest-api-support) - * [3.5.7 GNMI Support](#357-gnmi-support) + * [3.4 Mirror Capability Discovery](#34-mirror-capability-discovery) + * [3.5 SAI](#35-sai) + * [3.6 CLI](#36-cli) + * [3.6.1 Data Models](#361-data-models) + * [3.6.2 Configuration Commands](#362-configuration-commands) + * [3.6.3 Show Commands](#363-show-commands) + * [3.6.4 Clear Commands](#364-clear-commands) + * [3.6.5 Debug Commands](#365-debug-commands) + * [3.6.6 Rest API Support](#366-rest-api-support) + * [3.6.7 GNMI Support](#367-gnmi-support) * [4. Flow Diagrams](#4-flow-diagrams) * [5. Error Handling](#5-Error-Handling) * [6. Serviceability and Debug](#6-serviceability-and-debug) @@ -49,6 +50,7 @@ | Rev | Date | Author | Change Description | |:---:|:-----------:|:------------------:|--------------------------------------------| | 0.1 | 05/17/2019 | Rupesh Kumar | Initial version | +| 0.2 | 09/05/2025 | Stephen Sun | Added mirror capability discovery and validation | # About this Manual @@ -144,7 +146,28 @@ Existing table PORT_MIRROR_TABLE is enhanced to accept new source and destinatio ### 3.2.2 APP_DB No tables are introduced in APP_DB ### 3.2.3 STATE_DB -No tables are introduced in STATE_DB.· + +#### Table SWITCH_CAPABILITY + +Table `SWITCH_CAPABILITY` is not a new table. It has been designed to represent various switch object capabilities supported on the platform. + +The following fields are introduced in this design for mirror capability discovery: + +```text +PORT_INGRESS_MIRROR_CAPABLE = "true" | "false" ; whether SAI attribute SAI_PORT_ATTR_INGRESS_MIRROR_SESSION is supported +PORT_EGRESS_MIRROR_CAPABLE = "true" | "false" ; whether SAI attribute SAI_PORT_ATTR_EGRESS_MIRROR_SESSION is supported +``` + +These capabilities are discovered during system initialization by SwitchOrch using `sai_query_attribute_capability()` and stored in STATE_DB under the key `SWITCH_CAPABILITY|switch`. + +**Example STATE_DB entry:** +```text +SWITCH_CAPABILITY|switch + PORT_INGRESS_MIRROR_CAPABLE: "true" + PORT_EGRESS_MIRROR_CAPABLE: "false" +``` + +This indicates that the ASIC supports ingress mirror sessions but does not support egress mirror sessions. ### 3.2.4 ASIC_DB No changes are introduced in ASIC_DB.· @@ -163,7 +186,58 @@ Mirror Orchestration agent is modified to support this feature: - Session with source/destination/direction config will be active once the session created from SAI is programmed on the source ports. - Populates the mirror attribute SAI structures and pushes the entry to ASIC_DB.· -## 3.4 SAI +## 3.4 Mirror Capability Discovery + +The mirror capability discovery feature provides runtime detection and validation of ASIC mirror capabilities to ensure proper configuration and graceful error handling. + +### 3.4.1 Capability Discovery Process + +The capability discovery process involves multiple layers: + +1. **SAI Layer Discovery**: SwitchOrch queries SAI for port mirror capabilities using `sai_query_attribute_capability()` for: + - `SAI_PORT_ATTR_INGRESS_MIRROR_SESSION` + - `SAI_PORT_ATTR_EGRESS_MIRROR_SESSION` + +2. **STATE_DB Storage**: Discovered capabilities are stored in STATE_DB under `SWITCH_CAPABILITY|switch`: + - `PORT_INGRESS_MIRROR_CAPABLE`: "true"/"false" + - `PORT_EGRESS_MIRROR_CAPABLE`: "true"/"false" + +3. **Runtime Validation**: MirrorOrch validates capabilities before configuring mirror sessions + +### 3.4.2 Capability Validation Flow + +The capability validation follows this sequence: + +1. **User CLI Command**: User executes a mirror session configuration command +2. **CLI Validation**: `is_port_mirror_capability_supported()` function is called +3. **STATE_DB Query**: System queries STATE_DB for mirror capabilities +4. **Direction Validation**: System validates if the requested mirror direction is supported +5. **Result**: Command proceeds if supported, or returns error message if not supported + +### 3.4.3 Error Handling + +- **CLI Level**: Early validation prevents invalid configurations +- **OrchAgent Level**: Runtime validation with detailed error logging +- **Graceful Degradation**: System continues to function with unsupported features disabled + +### 3.4.4 Implementation Components + +#### SwitchOrch Enhancements +- New capability constants: `SWITCH_CAPABILITY_TABLE_PORT_INGRESS_MIRROR_CAPABLE`, `SWITCH_CAPABILITY_TABLE_PORT_EGRESS_MIRROR_CAPABLE` +- `querySwitchPortMirrorCapability()`: Discovers and stores capabilities +- Public interface methods: `isPortIngressMirrorSupported()`, `isPortEgressMirrorSupported()` + +#### MirrorOrch Enhancements +- Capability validation in `setUnsetPortMirror()` +- Separate validation for ingress and egress directions +- Detailed error logging for unsupported operations + +#### CLI Enhancements +- `is_port_mirror_capability_supported()`: Queries STATE_DB for capabilities +- Integration with `validate_mirror_session_config()` +- User-friendly error messages for unsupported directions + +## 3.5 SAI Mirror SAI interface APIs are already defined. More details about SAI API and attributes are described below SAI Spec @ @@ -226,8 +300,8 @@ https://github.com/opencomputeproject/SAI/blob/master/inc/saimirror.h SAI_PORT_ATTR_EGRESS_MIRROR_SESSION, ``` -## 3.5 CLI -### 3.5.1 Data Models +## 3.6 CLI +### 3.6.1 Data Models SONiC Yang model and OpenConfig extension models will be introduced for this feature. ## openconfig-mirror-ext @@ -303,7 +377,7 @@ SONiC Yang model and OpenConfig extension models will be introduced for this fe ``` -### 3.5.2 Configuration Commands +### 3.6.2 Configuration Commands Existing mirror session commands are enhanced to support this feature. ``` @@ -332,7 +406,7 @@ KLISH CLI Support. **switch(config)# [no] mirror-session **
**switch(config-mirror-)# [no] destination erspan src_ip dst_ip dscp < dscp > ttl < ttl > [ gre < gre >] [queue ] [source direction **] [policer ]
-### 3.5.3 Show Commands +### 3.6.3 Show Commands The following show command display all the mirror sessions that are configured. @@ -350,13 +424,13 @@ The following show command display all the mirror sessions that are configured. KLISH show mirror-session is same as above. -### 3.5.4 Clear Commands +### 3.6.4 Clear Commands No command variants of config commands take care of clear config. -### 3.5.5 Debug Commands +### 3.6.5 Debug Commands Not applicable -### 3.5.6 REST API Support +### 3.6.6 REST API Support - Please check all REST API from link @ https:///ui link. - This webserver provides user information about all the REST URLS, REST Data. Return codes. @@ -379,7 +453,7 @@ The following show command display all the mirror sessions that are configured. # curl -X DELETE "https:///restconf/data/sonic-mirror-session:sonic-mirror-session/MIRROR_SESSION/MIRROR_SESSION_LIST=mirr3" -H "accept: application/yang-data+json" ``` -### 3.5.7 GNMI Support +### 3.6.7 GNMI Support - Following GNMI set and get commands will be supported. ``` @@ -399,10 +473,64 @@ The following show command display all the mirror sessions that are configured. # 5 Error Handling +## 5.1 Basic Error Handling + - show mirror_session command will display any errors during session configuration and current status of session. - Internal processing errors within SwSS will be logged in syslog with ERROR level - SAI interaction errors will be logged in syslog +## 5.2 Enhanced Mirror Capability Error Handling + +### 5.2.1 Capability Validation Errors + +The enhanced error handling system provides comprehensive validation and user-friendly error messages for mirror capability issues: + +#### CLI Level Validation +- **Early Detection**: Capability validation occurs before configuration attempts +- **User-Friendly Messages**: Clear error messages indicating unsupported directions +- **Example Error Messages**: + ``` + Error: Port mirror direction 'rx' is not supported by the ASIC + Error: Port mirror direction 'tx' is not supported by the ASIC + Error: Port mirror direction 'both' is not supported by the ASIC + ``` + +#### OrchAgent Level Validation +- **Runtime Validation**: MirrorOrch validates capabilities before SAI operations +- **Detailed Logging**: Comprehensive error logging for debugging +- **Graceful Degradation**: System continues to function with unsupported features disabled + +### 5.2.2 Error Handling Flow + +The error handling follows a two-stage validation process: + +**Stage 1: CLI Validation** +1. **Configuration Attempt**: User attempts to configure mirror session +2. **CLI Validation**: Early validation checks are performed +3. **Capability Check**: System queries STATE_DB for mirror capabilities +4. **Decision Point**: + - If supported: Proceed to OrchAgent + - If not supported: Return error message to user + +**Stage 2: OrchAgent Validation** +1. **OrchAgent Validation**: Runtime validation before SAI operations +2. **Final Decision Point**: + - If supported: Configure SAI attributes + - If not supported: Log error and skip operation + +### 5.2.3 Error Recovery and Status Reporting + +- **Error Prevention**: CLI validation prevents invalid configurations from being applied +- **Status Reporting**: Clear status reporting in show commands +- **Logging**: Comprehensive logging for troubleshooting and monitoring +- **Graceful Rejection**: System rejects unsupported configurations with clear error messages + +### 5.2.4 Backward Compatibility + +- **Legacy Support**: Existing configurations continue to work +- **Graceful Migration**: New capability checks don't break existing functionality +- **Default Behavior**: When capability detection fails, system assumes full support for backward compatibility + # 6 Serviceability and Debug # 7 Warm Boot Support @@ -417,6 +545,32 @@ Max mirror sessions supported are silicon specific. |--------------------------|--------------------| | Max mirror sessions | silicon specific | +# 8.1 Backward Compatibility + +## 8.1.1 Mirror Capability Feature Compatibility + +The mirror capability discovery and validation feature is designed to be fully backward compatible: + +### 8.1.2 Existing Configurations +- **Legacy Support**: All existing mirror session configurations continue to work without modification +- **No Breaking Changes**: Existing CLI commands and configurations remain unchanged +- **Graceful Migration**: New capability checks are additive and don't interfere with existing functionality + +### 8.1.3 Capability Detection Fallback +- **Default Behavior**: When capability detection fails, the system assumes full support for backward compatibility +- **Error Handling**: If STATE_DB is unavailable or capability queries fail, the system continues to function +- **Logging**: Capability detection failures are logged but don't prevent normal operation + +### 8.1.4 CLI Compatibility +- **Command Compatibility**: All existing CLI commands work exactly as before +- **Error Message Enhancement**: New error messages are only shown when capabilities are explicitly checked +- **Optional Validation**: Capability validation is only performed when direction parameters are specified + +### 8.1.5 OrchAgent Compatibility +- **Runtime Validation**: New capability validation is performed at runtime without affecting existing sessions +- **Graceful Degradation**: Unsupported operations are logged but don't crash the system +- **State Preservation**: Existing mirror sessions continue to function regardless of capability status + # 9 Unit Test ## 9.1 CLI Test Cases @@ -465,4 +619,24 @@ test_mirror_port_span.py::TestMirror::test_PortMirrorPolicerAddRemove PASSED test_mirror_port_span.py::TestMirror::test_PortMirrorPolicerMultiAddRemove PASSED [ 83%] test_mirror_port_span.py::TestMirror::test_PortMirrorPolicerWithAcl PASSED [ 91%] test_mirror_port_span.py::TestMirror::test_LAGMirorrSpanAddRemove PASSED [100%] -``` \ No newline at end of file +``` + +## 9.2 Mirror Capability Test Cases + +### 9.2.1 CLI Capability Validation Tests + +The following test cases validate the mirror capability discovery and validation functionality: + +| S.No | Test Case Synopsis | +|------|-------------------| +| 20 | Verify that CLI validates mirror direction capabilities before configuration | +| 21 | Verify that CLI returns appropriate error messages for unsupported directions | +| 22 | Verify that CLI allows configuration when capabilities are supported | +| 23 | Verify that CLI capability checking works for both SPAN and ERSPAN sessions | +| 24 | Verify that CLI capability checking is not performed when no direction is specified | + +### 9.2.2 Integration Tests + +| S.No | Test Case Synopsis | +|------|-------------------| +| 25 | Verify end-to-end capability validation from CLI to SAI | \ No newline at end of file From 5ca2b0a7f16d4df8a771cef04b3aa86f7b85de98 Mon Sep 17 00:00:00 2001 From: Stephen Sun Date: Mon, 20 Oct 2025 17:12:17 +0800 Subject: [PATCH 2/2] Update test case description Signed-off-by: Stephen Sun --- doc/port-mirroring/SONiC_Port_Mirroring_HLD.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/port-mirroring/SONiC_Port_Mirroring_HLD.md b/doc/port-mirroring/SONiC_Port_Mirroring_HLD.md index 4a8abd7a5df..7fd69026ca6 100644 --- a/doc/port-mirroring/SONiC_Port_Mirroring_HLD.md +++ b/doc/port-mirroring/SONiC_Port_Mirroring_HLD.md @@ -629,14 +629,13 @@ The following test cases validate the mirror capability discovery and validation | S.No | Test Case Synopsis | |------|-------------------| -| 20 | Verify that CLI validates mirror direction capabilities before configuration | +| 20 | Verify that capability checking fails when direction is not supported | | 21 | Verify that CLI returns appropriate error messages for unsupported directions | | 22 | Verify that CLI allows configuration when capabilities are supported | -| 23 | Verify that CLI capability checking works for both SPAN and ERSPAN sessions | -| 24 | Verify that CLI capability checking is not performed when no direction is specified | -### 9.2.2 Integration Tests +### 9.2.2 Swss Mock Tests | S.No | Test Case Synopsis | |------|-------------------| -| 25 | Verify end-to-end capability validation from CLI to SAI | \ No newline at end of file +| 25 | Verify that capability checking fails when direction is not supported | +| 26 | Verify that the mirror capability is inserted into the STATE_DB | \ No newline at end of file