A YANG Data Model for ECN Threshold Policies

Introduction A locally adjusted RED threshold can differ from the configured base value. A controller or management client needs to know which queue instance is affected, the administrative bounds, whether the effective pair has been confirmed, and why adaptation is suspended. These meanings must be consistent if management software operates across implementations. already models RED/WRED and other queue algorithms. is another substantial QoS management model. describes coupling ECN thresholds with dynamic buffer allocation; its expiration does not erase that related work. The candidate addition here is the policy and state contract around a local controller. It is not a new claim to the idea of adapting ECN thresholds. This proposal targets review with the QoS model work. Integration into that model may be preferable to a separate module. The current augment is explicitly based on QoS model revision -16 and its 2026-09-26 module revisions; these are work in progress. The dependency must stabilize and the additional requirement must be accepted before publication. No support from those editors or from a working group is assumed.

Requirements Language The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Applicability and Queue Binding The profile applies only to one RED configuration with ECN enabled, a byte-denominated minimum k_b, and maximum m_b with 0<=k_b<m_b. Its width D=m_b-k_b is positive and fixed until administrative base configuration changes. WRED color profiles, delay-based AQM, L4S coupled queues, and deterministic step marking are outside this version. Unsupported instances MUST report unavailable and MUST NOT silently ignore the policy. Configuration augments /qa:queues/qa:queue/qa:queue of . A template may instantiate several queues; it is not the identity of a physical queue. Operational state is keyed by interface and device-reported queue-id. queue-template records the applied binding. The server MUST validate each queue instance independently and MUST NOT merge effective values from different instances. The server MUST expose an accounting-quantum q>0. Validated base thresholds, policy bounds, buffer margin and maximum step MUST be exact multiples of q. Configuration that cannot be represented on an instantiated queue is rejected at activation for that instance rather than silently rounded. A configuration transaction whose invalidity can be determined beforehand MUST be rejected. Policy support and all required local update capabilities must be established before reporting active. Byte quantities are bounded by 2^53-1 so model comparisons can use exact XPath integers. Intermediate arithmetic MUST use checked integer calculations. Input proposals and the validated budget are floored to multiples of q before use. In particular, S=maximum-step must be at least q. A value expressed in packets or a vendor percentage MUST NOT be accepted as bytes without an explicit supported conversion outside this profile.

Validated Buffer Limit and Meaning of the Margin B is a current conservative egress-accounting limit established by the device for the specific queue. The budget/source string MUST identify the accounting mechanism and the mapping of shared pools, admission limits and queue occupancy to B. The server MUST omit budget if it cannot establish that meaning. Unknown B is not encoded as zero. An ingress PFC XOFF threshold is not automatically an egress queue limit. It MUST NOT be substituted for B without a validated conversion into the same egress-accounted bytes. Local occupancy, queue length, and current free shared memory also have different meanings; their numeric similarity does not establish the required bound. H=buffer-margin is an administrative arithmetic margin between the RED upper threshold and B. It neither reserves memory nor proves that the remaining capacity will absorb in-flight traffic. RED may use an average occupancy; packet admission, transport feedback delay, shared-pool changes and scheduling still affect drops or PFC. The pair bound below is a parameter bound, not an assurance that ECN feedback precedes every overflow or pause.

Policy Evaluation Let K_min=minimum-onset, M_max=maximum-threshold, H=buffer-margin, S=maximum-step, and D=m_b-k_b. After quantization, the highest permissible minimum is U=min(M_max-D, B-H-D). The envelope is feasible only if M_max>=D, B>=H+D, and K_min<=U. Implementations MUST check these conditions before unsigned subtraction. The base pair itself need not lie inside the adaptive envelope. U = min(M_max - D, B - H - D) For a normal adjustment with fresh proposal k_p: proposal = q * floor(k_p / q) stepped = min(max(proposal, k_previous - S), k_previous + S) effective = min(max(stepped, K_min), U) pair = (effective, effective + D) Normal controller adjustments MUST be serialized and occur no more often than once per update-interval, measured on a monotonic clock. k_previous is the last confirmed minimum in that control sequence. Arrivals of multiple proposals do not create extra adjustment opportunities. The server MUST revalidate input freshness, budget, policy and binding immediately before committing a pair. A proposal computed under an obsolete binding or policy MUST be discarded. The normal step limit does not delay enforcing a changed administrative bound or reduced B. A downward clamp required by a smaller U MUST be effective no later than the corresponding reduced budget becomes applicable while the instance is active. A raised lower bound can likewise require an upward clamp. Initial activation, recovery and administrative fallback are explicitly exempt from the normal controller step limit. When enforcement cannot be coordinated locally with budget changes, the instance MUST leave active and report pending or unavailable as appropriate; it cannot claim that a management polling loop provides this ordering. A device MUST apply the two thresholds as one coherent forwarding update, or use an implementation procedure that preserves the declared pair invariant throughout active operation. A device lacking such capability MUST NOT report active. The model specifies the required externally observable result and does not mandate a particular register or programming transaction.

State, Confirmation, and Fallback Freshness concerns the observations supporting the controller proposal and budget validation, not merely a running control thread. At input-timeout, new controller adjustments MUST stop. A budget that has become unknown is unavailable. For a known budget, infeasibility takes precedence over stale-input fallback. A requested pair is never reported as effective before confirmation. Operational States

State	Meaning and required behavior
active	Fresh inputs, feasible envelope, valid binding, and confirmed current pair satisfying every bound.
pending	An activation, clamp or fallback has been requested but is not confirmed. Stop accepting obsolete controller work.
fallback	The envelope is feasible but observations are stale; the base pair is confirmed in forwarding.
infeasible	The envelope cannot contain a pair under the known budget; the base pair is confirmed in forwarding.
unavailable	Unsupported mapping, unknown budget, invalid base/accounting, lost forwarding visibility or programming failure.

On stale input or infeasibility, the server MUST request restoration of the validated base pair and enter pending until it is confirmed. After confirmation it reports fallback or infeasible according to the current cause. If restoration fails, the status is unavailable. Base restoration is the defined administrative behavior; it is not a claim that the base pair satisfies the new B-H. A collector can calculate whether the reported effective maximum lies within the current budget and margin. The effective container is present only when the current forwarding pair is known, including during a pending update if the old pair is still known to be current. If partial programming or loss of visibility makes that uncertain, the container MUST be absent. A historical last-confirmed pair MUST NOT be represented as current effective state. The parameters and budget containers are similarly omitted when their values cannot be validated. Active, fallback and infeasible require all three containers. When fresh input and a feasible envelope return, the device validates and requests a bounded pair, enters pending, and reports active only after confirmation. Disabling or deleting the policy also requires orderly return to ordinary base QoS behavior. The server MUST stop local controller writes before handing ownership back; if return fails it retains an unavailable row with diagnostic reason rather than hiding the failure. Once the base configuration is confirmed and policy ownership has ended, the policy-state row can be removed. Each operational row is a coherent snapshot identified by epoch-id and state-sequence. The sequence increases whenever any exposed state field changes; before wrap a fresh epoch is created. Queue recreation, mapping change, or loss of sequence history also starts a fresh epoch. Repeated snapshots of the same identity MUST have identical fields. Atomically reading one row does not imply a simultaneous snapshot across all queues.

Configuration Ownership and ECN Behavior The local controller algorithm is implementation-defined; this document has no external propose-threshold action. The enforcement function is the sole writer of the effective threshold pair while it owns the queue. Administrative changes through NETCONF, RESTCONF, CLI, or other APIs MUST invalidate in-flight proposals and be revalidated as complete configurations. An alias MUST NOT bypass policy enforcement. The base RED template remains ordinary configuration in the relevant NMDA datastores . Dynamic proposals do not overwrite it. The parameters subtree is a snapshot of the values currently used by the local enforcement function and may differ from intended configuration during transition. This difference MUST be made visible through pending/unavailable state rather than reported as an already applied change. The device MUST preserve existing CE and follow standard Not-ECT handling in . The policy does not disable AQM or define an exception based on PFC. A zero minimum is not an all-mark command: the width, averaging and RED probability behavior still matter. Preserving D preserves the ramp width, not a proof of closed-loop behavior. Qualified PFC telemetry may be an input to a separately evaluated controller; it is not evidence that marking is unnecessary.

Implementation and Evaluation Requirements A conforming implementation MUST document how it binds templates to queue IDs, derives B, accounts bytes, confirms a pair, coordinates budget reductions, and detects stale observations. It MUST expose unsupported or failed instances. Such documentation is necessary to interpret the interface; a syntactically valid YANG implementation alone does not establish the timing guarantee. Evaluation should follow and and include incast, burst load, mixed ECT and Not-ECT traffic, PFC, shared-pool contention, input loss, downward budget jumps, failure between pair writes, policy deletion, and two queues sharing a template. Actual transport response and hardware timing need measurement. The specification claims no universal convergence, optimality, losslessness or throughput improvement.

YANG Tree Diagram The tree is generated from the module using the notation in . module: ietf-ecn-threshold-policy augment /qa:queues/qa:queue/qa:queue: +--rw ecn-threshold-policy! +--rw minimum-onset byte-value +--rw maximum-threshold byte-value +--rw buffer-margin byte-value +--rw maximum-step uint64 +--rw update-interval? uint32 +--rw input-timeout? uint32 augment /if:interfaces/if:interface: +--ro ecn-threshold-state +--ro queue* [queue-id] +--ro queue-id string +--ro queue-template -> /qa:queues/queue/name +--ro epoch-id yang:uuid +--ro state-sequence uint64 +--ro status enumeration +--ro reason string +--ro parameters! | +--ro minimum-onset byte-value | +--ro maximum-threshold byte-value | +--ro buffer-margin byte-value | +--ro maximum-step uint64 | +--ro update-interval? uint32 | +--ro input-timeout? uint32 | +--ro accounting-quantum uint64 | +--ro base-minimum byte-value | +--ro base-maximum byte-value +--ro budget! | +--ro limit byte-value | +--ro source string +--ro effective! +--ro minimum byte-value +--ro maximum byte-value

YANG Module The module uses YANG 1.1 , NMDA , the interface model , and common types . Review follows . RFC XXXX in the module is an RFC Editor placeholder. module ietf-ecn-threshold-policy { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-ecn-threshold-policy"; prefix etp; import ietf-yang-types { prefix yang; reference "RFC 9911: Common YANG Data Types"; } import ietf-interfaces { prefix if; reference "RFC 8343: A YANG Data Model for Interface Management"; } import ietf-qos-action { prefix qa; reference "I-D.ietf-rtgwg-qos-model: QoS model, revision -16"; } import ietf-qos-types { prefix qt; reference "I-D.ietf-rtgwg-qos-model: QoS types, revision -16"; } organization "Individual Submission"; contact "Author: Jin Yang <mailto:yangjinwl@chinamobile.com> Author: Weiqiang Cheng <mailto:chengweiqiang@chinamobile.com> Author: Tingting Han <mailto:hantingting@chinamobile.com> Author: Junjie Wang <mailto:wangjj@centec.com> Author: Zongwei Meng <mailto:mengzw@centec.com> Author: Ying Feng <mailto:fengy@centec.com>"; description "Administrative limits and confirmed per-queue state for local ECN threshold adaptation on a single byte-based RED profile. Copyright (c) 2026 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Revised BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself for full legal notices."; revision 2026-10-30 { description "Initial revision."; reference "RFC XXXX: A YANG Data Model for ECN Threshold Policies"; } typedef byte-value { type uint64 { range "0..9007199254740991"; } units "bytes"; description "Accounted bytes in the exact XPath integer range."; } grouping policy-values { description "Administrative bounds, also copied into applied state."; leaf minimum-onset { type byte-value; mandatory true; description "Lower bound on the effective RED minimum."; } leaf maximum-threshold { type byte-value; mandatory true; description "Upper bound on the effective RED maximum."; } leaf buffer-margin { type byte-value; mandatory true; description "Arithmetic margin below the validated egress limit; not a physical reservation or losslessness guarantee."; } leaf maximum-step { type uint64 { range "1..9007199254740991"; } units "bytes"; mandatory true; description "Maximum normal controller step in accounted bytes."; } leaf update-interval { type uint32 { range "1..max"; } units "milliseconds"; default "10"; description "Minimum monotonic time between normal controller updates."; } leaf input-timeout { type uint32 { range "1..max"; } units "milliseconds"; default "1000"; description "Maximum permitted age of supporting observations."; } } augment "/qa:queues/qa:queue/qa:queue" { description "Policy on a reusable RED queue template."; container ecn-threshold-policy { must "../qa:algorithmic-drop/qa:red/qa:ecn-enabled = 'true'"; must '../qa:algorithmic-drop/qa:red/qa:min-threshold-val and ' + '../qa:algorithmic-drop/qa:red/qa:max-threshold-val'; must '../qa:algorithmic-drop/qa:red/qa:max-threshold-val > ' + '../qa:algorithmic-drop/qa:red/qa:min-threshold-val'; must '../qa:algorithmic-drop/qa:red/qa:max-threshold-val ' + '<= 9007199254740991'; must "derived-from-or-self(../qa:algorithmic-drop/qa:red/" + "qa:min-threshold-unit, 'qt:red-threshold-bytes') and " + "derived-from-or-self(../qa:algorithmic-drop/qa:red/" + "qa:max-threshold-unit, 'qt:red-threshold-bytes')"; must 'minimum-onset < maximum-threshold'; must 'input-timeout >= update-interval'; presence "Requests policy enforcement for instances of this template."; description "Policy for single-profile RED with ECN enabled."; uses policy-values; } } augment "/if:interfaces/if:interface" { description "Confirmed policy state of instantiated egress queues."; container ecn-threshold-state { config false; description "One coherent row for each governed queue instance."; list queue { must "status = 'unavailable' or status = 'pending' or " + "(parameters and effective and budget)"; must "status != 'active' or (budget and " + "parameters/minimum-onset <= effective/minimum and " + "effective/maximum <= parameters/maximum-threshold and " + "parameters/buffer-margin <= budget/limit and " + "effective/maximum <= budget/limit - " + "parameters/buffer-margin)"; must "status != 'fallback' and status != 'infeasible' or " + "(effective/minimum = parameters/base-minimum and " + "effective/maximum = parameters/base-maximum)"; must 'not(parameters and effective) or ' + 'effective/maximum - effective/minimum = ' + 'parameters/base-maximum - parameters/base-minimum'; key "queue-id"; description "State is coherent per row. Pending or unavailable is used while the requested state has not been confirmed."; leaf queue-id { type string { length "1..128"; } description "Stable queue identifier within this interface and epoch."; } leaf queue-template { type leafref { path "/qa:queues/qa:queue/qa:name"; require-instance false; } mandatory true; description "Template binding reflected in this state; may outlive its deletion briefly."; } leaf epoch-id { type yang:uuid; mandatory true; description "New identity on queue reuse, mapping change or loss of state-sequence history."; } leaf state-sequence { type uint64 { range "1..max"; } mandatory true; description "Increases on any exposed state change; no wrap within an epoch."; } leaf status { type enumeration { enum active { description "Confirmed pair meets current bounds."; } enum fallback { description "Base pair confirmed after stale controller input."; } enum infeasible { description "No bounded pair is feasible; base pair confirmed."; } enum pending { description "A requested pair or fallback awaits confirmation."; } enum unavailable { description "Capability, input validation or application failed."; } } mandatory true; description "Current enforcement state; not a delivery guarantee."; } leaf reason { type string { length "1..256"; } mandatory true; description "Diagnostic detail; clients use status for machine decisions."; } container parameters { must 'base-maximum > base-minimum'; must 'minimum-onset < maximum-threshold'; must 'input-timeout >= update-interval'; must 'base-minimum mod accounting-quantum = 0 and ' + 'base-maximum mod accounting-quantum = 0 and ' + 'minimum-onset mod accounting-quantum = 0 and ' + 'maximum-threshold mod accounting-quantum = 0 and ' + 'buffer-margin mod accounting-quantum = 0 and ' + 'maximum-step mod accounting-quantum = 0'; presence "Validated base and policy values for this snapshot."; description "Values used locally; may lag intended configuration."; uses policy-values; leaf accounting-quantum { type uint64 { range "1..9007199254740991"; } units "bytes"; mandatory true; description "Hardware granularity; configuration values must be exact multiples."; } leaf base-minimum { type byte-value; mandatory true; description "Validated static RED minimum."; } leaf base-maximum { type byte-value; mandatory true; description "Validated static RED maximum."; } } container budget { must 'not(../parameters) or ' + 'limit mod ../parameters/accounting-quantum = 0'; presence "A current validated egress limit is available."; description "Omitted when a conservative bound cannot be validated."; leaf limit { type byte-value; mandatory true; description "Conservative accounted-byte ceiling B, rounded down."; } leaf source { type string { length "1..256"; } mandatory true; description "Accounting mechanism and mapping to this egress queue."; } } container effective { must 'maximum > minimum'; must 'not(../parameters) or ' + '(minimum mod ../parameters/accounting-quantum = 0 and ' + 'maximum mod ../parameters/accounting-quantum = 0)'; presence "Current forwarding threshold pair is known."; description "Current confirmed values, omitted if partial failure or lost contact makes the current pair uncertain."; leaf minimum { type byte-value; mandatory true; description "Confirmed RED minimum in the forwarding plane."; } leaf maximum { type byte-value; mandatory true; description "Confirmed RED maximum in the forwarding plane."; } } } } } }

Examples and Conformance Cases Let q=100, base=(1000,2000), D=1000, B=10000, H=2000, M_max=9000, K_min=1000, S=1000. Then U=7000. From previous minimum 4000 with proposal 8500, one normal update yields (5000,6000), not an immediate jump to (7000,8000). The latter is the uppermost permitted pair after subsequent allowed updates. If the previous pair is (7000,8000) and B contracts to 6500, U becomes 3500. A coordinated clamp produces (3500,4500), overriding S. If the hardware cannot coordinate that change, it cannot continue to report active. If B=2500 with H=2000 and D=1000, the envelope is infeasible even for K_min=0. After successful restoration the row is infeasible with effective=(1000,2000); the effective maximum exceeds B-H=500. That report is honest fallback state, not active compliance. A restoration failure instead reports unavailable. A backend that can confirm neither the old nor new pair after a partial failure omits effective. An active record missing the budget or parameters is invalid. Two instances using the same template must report their own B, effective pair and state. The JSON example below shows one such operational snapshot with byte-valued uint64 leaves encoded as strings under . { "ietf-qos-action:queues": { "queue": [ { "name": "fabric-red", "queue": { "algorithmic-drop": { "red": { "min-threshold-val": "1000", "max-threshold-val": "2000", "min-threshold-unit": "ietf-qos-types:red-threshold-bytes", "max-threshold-unit": "ietf-qos-types:red-threshold-bytes", "max-probability-val": "10", "ecn-enabled": true } }, "ietf-ecn-threshold-policy:ecn-threshold-policy": { "minimum-onset": "1000", "maximum-threshold": "9000", "buffer-margin": "2000", "maximum-step": "1000", "update-interval": 10, "input-timeout": 1000 } } } ] }, "ietf-interfaces:interfaces": { "interface": [ { "name": "Ethernet1/1", "type": "iana-if-type:ethernetCsmacd", "oper-status": "up", "ietf-ecn-threshold-policy:ecn-threshold-state": { "queue": [ { "queue-id": "q3", "queue-template": "fabric-red", "epoch-id": "36b5e4fa-5d23-4a82-adc3-18a8aef08e93", "state-sequence": "7", "status": "active", "reason": "fresh input and confirmed pair", "parameters": { "minimum-onset": "1000", "maximum-threshold": "9000", "buffer-margin": "2000", "maximum-step": "1000", "update-interval": 10, "input-timeout": 1000, "accounting-quantum": "100", "base-minimum": "1000", "base-maximum": "2000" }, "budget": { "limit": "10000", "source": "validated shared-pool egress admission bound" }, "effective": { "minimum": "5000", "maximum": "6000" } } ] }, "admin-status": "up", "if-index": 1, "statistics": { "discontinuity-time": "2026-10-30T00:00:00Z" } } ] } }

Security Considerations The module is designed for NETCONF and RESTCONF over their secure transports; NETCONF over SSH is specified by . NACM or equivalent access controls MUST restrict writes and reads to authorized management roles. The writable ecn-threshold-policy container changes permitted queue thresholds, buffer margin, step and timing limits. Unauthorized or poorly chosen values can degrade throughput, increase marking or drops, and disrupt shared workloads. Write access deserves the same protection as base QoS configuration. A reusable template can affect many queues, so authorization and validation MUST consider all affected instances. Readable queue mappings, budgets, effective thresholds and state changes reveal shared-resource behavior. Access and subscription rates SHOULD be limited. This module defines no notifications, actions or remote controller interface. A compromised local controller can still generate poor proposals within the bounds; bounds do not make a malicious control algorithm safe. False but internally consistent state remains possible, and operational confirmation depends on the device implementation.

IANA Considerations IANA is requested to register the following namespace in the IETF XML Registry , and the following module in the YANG Module Names registry . These are requested registrations, not assigned values. Requested Registration

Field	Value
URI	urn:ietf:params:xml:ns:yang:ietf-ecn-threshold-policy
Registrant Contact	IESG
XML	N/A; XML namespace
Name	ietf-ecn-threshold-policy
Prefix	etp
Maintained by IANA	N
Reference	RFC XXXX