diff --git a/doc/qos/wred_ecn_marking_thresholds_HLD.md b/doc/qos/wred_ecn_marking_thresholds_HLD.md new file mode 100644 index 00000000000..edf42676f22 --- /dev/null +++ b/doc/qos/wred_ecn_marking_thresholds_HLD.md @@ -0,0 +1,256 @@ +# WRED Profile Independent ECN Marking Thresholds + +## Table of Contents + +- [Revision](#revision) +- [Scope](#scope) +- [Definitions/Abbreviations](#definitionsabbreviations) +- [Overview](#overview) +- [Requirements](#requirements) +- [Architecture Design](#architecture-design) +- [High-Level Design](#high-level-design) + - [CONFIG_DB: WRED_PROFILE additions](#config_db-wred_profile-additions) + - [Orchagent (QosOrch)](#orchagent-qosorch) + - [ECT enablement and backward compatibility](#ect-enablement-and-backward-compatibility) + - [Capability handling](#capability-handling) +- [SAI API](#sai-api) +- [Configuration and management](#configuration-and-management) + - [CONFIG_DB Enhancements](#config_db-enhancements) + - [CLI/YANG model Enhancements](#cliyang-model-enhancements) +- [Warmboot and Fastboot Design Impact](#warmboot-and-fastboot-design-impact) +- [Warmboot and Fastboot Performance Impact](#warmboot-and-fastboot-performance-impact) +- [Memory Consumption](#memory-consumption) +- [Restrictions/Limitations](#restrictionslimitations) +- [Testing Requirements/Design](#testing-requirementsdesign) +- [Open/Action items](#openaction-items) + +## Revision + +| Rev | Date | Author | Change Description | +|-----|------------|----------------------|--------------------| +| 0.1 | 2026-07-01 | Anant Kishor Sharma (HPE) | Initial version | + +## Scope + +This document describes the high-level design for adding **independent ECN marking +thresholds** to the SONiC `WRED_PROFILE` object. It covers the CONFIG_DB schema +additions, the `orchagent` (QosOrch) changes that program the corresponding SAI WRED +attributes, the YANG model additions, and the backward-compatibility and capability +handling. It does not change the WRED drop behavior or introduce any new SAI header. + +## Definitions/Abbreviations + +| Term | Definition | +|------|------------| +| WRED | Weighted Random Early Detection | +| ECN | Explicit Congestion Notification | +| ECT | ECN-Capable Transport | +| AQM | Active Queue Management | + +## Overview + +Today a SONiC `WRED_PROFILE` exposes a single set of per-color queue-depth thresholds +(`{green,yellow,red}_{min,max}_threshold`) that drive **both** random early drop and +ECN marking. When ECN is enabled for a color (via the `ecn` field), packets of that +color are ECN-marked instead of dropped, but the marking uses the **same** thresholds +as the drop curve. There is no way to mark ECN at a queue depth different from where +drop begins. + +Standard AQM practice is to **mark before drop**: start ECN-marking at a lower queue +depth than where WRED drop begins, so that congestion is signaled (ECN) well before +packets are lost (drop). This feature adds an **independent** set of per-color ECN +marking thresholds and a per-color mark probability to `WRED_PROFILE`, decoupled from +the WRED drop thresholds, and programs them through the existing SAI WRED ECN +attributes. + +## Requirements + +1. Add per-color (green/yellow/red) **independent ECN marking** min/max thresholds and + a mark probability to `WRED_PROFILE`, distinct from the WRED drop thresholds. +2. Program the new values via the existing SAI WRED ECN attributes; **no SAI header + (API) change** is required. +3. **Backward compatible:** when the new fields are not configured, ECN behavior is + unchanged. This is the SAI-defined fallback — per the SAI WRED attribute definitions, + in the absence of `SAI_WRED_ATTR_ECN__MIN/MAX_THRESHOLD` the ECT traffic uses + `SAI_WRED_ATTR__MIN/MAX_THRESHOLD` (the drop thresholds), and in the absence of + `SAI_WRED_ATTR_ECN__MARK_PROBABILITY` it uses `SAI_WRED_ATTR__DROP_PROBABILITY`. +4. **Capability-gated:** program the new attributes only where the platform/SAI reports + support for them; otherwise ignore them gracefully (best-effort) without failing the + profile. +5. Validate the configuration: `max >= min` per color; a color's ECN threshold is only + valid when that color is enabled in the profile's `ecn` mode; mark probability in the + range `0..100`. + +## Architecture Design + +There is no architectural change. The feature extends the existing WRED programming +path: `WRED_PROFILE` in CONFIG_DB → `QosOrch` → SAI `WRED` object attributes. No new +tables, daemons, or channels are introduced. + +## High-Level Design + +### CONFIG_DB: WRED_PROFILE additions + +Nine optional fields are added to `WRED_PROFILE` (three per color): + +| Field | Type | Description | +|-------|------|-------------| +| `ecn_green_min_threshold` | byte_count | Queue depth (bytes) at which ECN marking begins for green packets | +| `ecn_green_max_threshold` | byte_count | Queue depth (bytes) at which all green packets are ECN marked | +| `ecn_green_mark_probability` | percentage (0..100) | Mark probability for green packets between the ECN min/max | +| `ecn_yellow_min_threshold` | byte_count | As above, yellow | +| `ecn_yellow_max_threshold` | byte_count | As above, yellow | +| `ecn_yellow_mark_probability` | percentage (0..100) | As above, yellow | +| `ecn_red_min_threshold` | byte_count | As above, red | +| `ecn_red_max_threshold` | byte_count | As above, red | +| `ecn_red_mark_probability` | percentage (0..100) | As above, red | + +All fields are optional. When a color's ECN threshold fields are omitted, that color's +ECN marking continues to use the existing WRED drop thresholds (unchanged behavior). + +### Orchagent (QosOrch) + +`QosOrch` (`WredMapHandler`) is extended to parse the new field names when handling a +`WRED_PROFILE` update and to program the corresponding SAI `WRED` attributes: + +- Threshold fields map to `SAI_WRED_ATTR_ECN__{MIN,MAX}_THRESHOLD` (`sai_uint32_t`). +- Mark-probability fields map to `SAI_WRED_ATTR_ECN__MARK_PROBABILITY` (`sai_uint32_t`, `0..100`). +- The CONFIG_DB/YANG thresholds are `uint64` (consistent with the existing WRED drop + thresholds) while the SAI attributes are `sai_uint32_t`, so `QosOrch` narrows the values + when building the attribute list. +- To avoid transiently programming `min > max` during an update, min/max are sequenced + using a normal-and-deferred attribute queue: whichever bound would violate the ordering + against the currently stored value is deferred and applied after the other. +- The ECN attributes are applied **best-effort** — each is set individually and a failed + `set_wred_attribute` is logged and skipped, leaving the base WRED drop behavior intact + (mirroring how `PortsOrch` applies optional port attributes). + +### ECT enablement and backward compatibility + +The per-WRED ECN threshold attributes only take effect when the switch-level attribute +`SAI_SWITCH_ATTR_ECN_ECT_THRESHOLD_ENABLE` is `true` (per the SAI definition). `QosOrch` +enables it **once**, lazily — the first time a profile programs ECN threshold attributes — +and **before** the per-WRED ECN attributes are set, satisfying the SAI validity requirement. + +`SAI_SWITCH_ATTR_ECN_ECT_THRESHOLD_ENABLE` is switch-global. Enabling it is safe for +existing profiles: by the SAI attribute semantics above, a profile that does not configure +ECN threshold fields continues to use its WRED drop thresholds for ECN, so no existing +behavior changes. + +### Capability handling + +`QosOrch` queries SAI capability before programming, using `sai_query_attribute_capability` +for both the per-WRED ECN threshold attributes (`SAI_OBJECT_TYPE_WRED`) and the switch +control (`SAI_SWITCH_ATTR_ECN_ECT_THRESHOLD_ENABLE`). On platforms that do not support them, +the ECN fields are skipped and the switch control is left disabled, without failing the +`WRED_PROFILE` programming. + +## SAI API + +No SAI header change is required. The feature uses attributes already defined in SAI: + +| SAI attribute | Purpose | +|---------------|---------| +| `SAI_WRED_ATTR_ECN_GREEN_MIN_THRESHOLD` / `..._MAX_THRESHOLD` | Green ECN mark thresholds | +| `SAI_WRED_ATTR_ECN_GREEN_MARK_PROBABILITY` | Green ECN mark probability | +| `SAI_WRED_ATTR_ECN_YELLOW_MIN_THRESHOLD` / `..._MAX_THRESHOLD` | Yellow ECN mark thresholds | +| `SAI_WRED_ATTR_ECN_YELLOW_MARK_PROBABILITY` | Yellow ECN mark probability | +| `SAI_WRED_ATTR_ECN_RED_MIN_THRESHOLD` / `..._MAX_THRESHOLD` | Red ECN mark thresholds | +| `SAI_WRED_ATTR_ECN_RED_MARK_PROBABILITY` | Red ECN mark probability | +| `SAI_SWITCH_ATTR_ECN_ECT_THRESHOLD_ENABLE` | Enable ECN threshold-based marking (switch-global) | + +Notes on the SAI attributes: + +- The ECN threshold attributes are `sai_uint32_t` (thresholds in bytes, range `1 .. max + buffer size`, default `0` = maximum buffer size; mark probability `0..100`, default `100`). +- They are `@validonly` when `SAI_WRED_ATTR_ECN_MARK_MODE` enables the corresponding color + (`SAI_ECN_MARK_MODE_{GREEN,YELLOW,RED,GREEN_YELLOW,GREEN_RED,YELLOW_RED,ALL}`, which the + CONFIG_DB `ecn` field maps to) **and** `SAI_SWITCH_ATTR_ECN_ECT_THRESHOLD_ENABLE == true`. +- In the absence of an ECN threshold / probability attribute, ECT traffic falls back to the + corresponding WRED drop threshold / drop probability (backward-compatible behavior). + +## Configuration and management + +### CONFIG_DB Enhancements + +Example `WRED_PROFILE` with drop thresholds and independent ECN marking thresholds +(ECN marking begins at a lower depth than drop): + +```json +{ + "WRED_PROFILE": { + "AZURE_LOSSLESS": { + "wred_green_enable": "true", + "green_min_threshold": "1048576", + "green_max_threshold": "2097152", + "ecn": "ecn_all", + "ecn_green_min_threshold": "262144", + "ecn_green_max_threshold": "524288", + "ecn_green_mark_probability": "5" + } + } +} +``` + +### CLI/YANG model Enhancements + +The `sonic-wred-profile` YANG model adds the nine leaves above (`uint64`; the +`*_mark_probability` leaves are range `0..100`). Two classes of `must` constraints are +added: + +- `max >= min` for each color's ECN thresholds. +- Each ECN field requires the matching color to be enabled in the profile's `ecn` mode + (e.g. `ecn_green_*` requires `ecn` ∈ {`ecn_green`, `ecn_green_yellow`, `ecn_green_red`, + `ecn_all`}). + +No new CLI command is required; the fields are configurable through the existing +CONFIG_DB / `config qos` flows. CLI enhancement can be added as a follow-up. + +## Warmboot and Fastboot Design Impact + +None. The new fields live in CONFIG_DB and are reconciled on warm/fast boot exactly like +the existing `WRED_PROFILE` fields. No new dynamic state is introduced. + +## Warmboot and Fastboot Performance Impact + +None. + +## Memory Consumption + +None. The feature adds a small, fixed number of optional fields per `WRED_PROFILE` entry +and introduces no new runtime data structures beyond the attributes programmed to SAI. + +## Restrictions/Limitations + +- The feature is programmed on a best-effort basis and is gated on SAI capability; on + platforms that do not support the SAI WRED ECN threshold attributes the fields are + ignored (a failed per-attribute set is logged and skipped, leaving drop behavior intact). +- When the new fields are unset, ECN marking follows the WRED drop thresholds, preserving + existing behavior. +- Enabling independent ECN thresholds sets the switch-global + `SAI_SWITCH_ATTR_ECN_ECT_THRESHOLD_ENABLE`; this is done once, lazily, and only when a + profile uses the feature on a supporting platform. Existing profiles that do not configure + ECN thresholds are unaffected (they continue using their WRED drop thresholds for ECN). + +## Testing Requirements/Design + +### Unit Test cases + +- `orchagent` `QosOrch` unit tests (`tests/mock_tests/qosorch_ut.cpp`): verify that + configuring the independent ECN threshold/probability fields programs the expected + `SAI_WRED_ATTR_ECN_*` attributes, that min/max update ordering is respected, and that + unsupported platforms skip the fields. (Implemented in sonic-swss #4719.) +- `sonic-yang-models` tests (`tests/yang_model_tests/tests/qos.json`): positive case for + a valid configuration and negative cases for `max < min` and for an ECN threshold set + without the matching color enabled in `ecn`. (Implemented in sonic-buildimage #28164.) + +### System Test cases + +- Configure a `WRED_PROFILE` with independent ECN marking thresholds lower than the drop + thresholds, bind it to a queue, and verify via ASIC_DB that the `WRED` object carries + the `SAI_WRED_ATTR_ECN_*` attributes. +- Verify that omitting the new fields leaves ECN behavior unchanged (regression). + +## Open/Action items + +- Optional `config`/`show` CLI helpers for the independent ECN thresholds (follow-up).