module bbf-qos-traffic-mngt {

    yang-version 1.1;

    namespace
      "urn:bbf:yang:bbf-qos-traffic-mngt";

    prefix bbf-qos-tm;

    import ietf-interfaces {
      prefix if;
    }
    import ietf-yang-types {
      prefix yang;
    }
    import bbf-yang-types {
      prefix bbf-yang;
    }
    import bbf-qos-types {
      prefix bbf-qos-t;
    }

    organization
      "Broadband Forum <https://www.broadband-forum.org>
Common YANG Work Area";

    contact
      "Comments or questions about this Broadband Forum YANG module
should be directed to <mailto:help@broadband-forum.org>.

Editor:      Nick Hancock, Adtran

Editor:      Ludwig Pauwels, Nokia

PS Leader:   Joey Boyd, Adtran

WA Director: Joey Boyd, Adtran

WA Director: Sven Ooghe, Nokia";

    description
      "This module contains a collection of YANG definitions for
supporting the Broadband Forum requirements on the management of
Quality of Service (QoS) as applicable to access network
equipment. As such, this module is specific to access network
equipment (e.g., BBF-specified Access Nodes and FTTdp DPUs).

Specifically, this module contains a collection of functions for
QoS traffic management (TM).

Copyright (c) 2017-2023, Broadband Forum

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The above license is used as a license under copyright only.
Please reference the Forum IPR Policy for patent licensing terms
<https://www.broadband-forum.org/ipr-policy>.

Any moral rights which are necessary to exercise under the above
license grant are also deemed granted under this license.

This version of this YANG module is part of TR-383a7; see
the TR itself for full legal notices.";

    revision "2023-12-15" {
      description
        "Amendment 7.
* Approval Date:    2023-12-15.
* Publication Date: 2023-12-15.";
      reference
        "TR-383a7: Common YANG Modules
        	  <https://www.broadband-forum.org/technical/download/
        		   TR-383_Amendment-7.pdf>";

    }

    revision "2023-03-07" {
      description
        "Amendment 6.
* Approval Date:    2023-03-07.
* Publication Date: 2023-03-07.";
      reference
        "TR-383a6: Common YANG Modules
        	  <https://www.broadband-forum.org/technical/download/
        		   TR-383_Amendment-6.pdf>";

    }

    revision "2022-03-01" {
      description
        "Amendment 5.
* Approval Date:    2022-03-01.
* Publication Date: 2022-03-01.";
      reference
        "TR-383a5: Common YANG Modules
        	  <https://www.broadband-forum.org/technical/download/
        		   TR-383_Amendment-5.pdf>";

    }

    revision "2021-06-02" {
      description
        "Amendment 4.
* Approval Date:    2021-06-02.
* Publication Date: 2021-06-02.";
      reference
        "TR-383a4: Common YANG Modules
        	  <https://www.broadband-forum.org/technical/download/
        		   TR-383_Amendment-4.pdf>";

    }

    revision "2020-10-13" {
      description
        "Amendment 3.
* Approval Date:    2020-10-13.
* Publication Date: 2020-10-13.";
      reference
        "TR-383a3: Common YANG Modules
        	  <https://www.broadband-forum.org/technical/download/
        		   TR-383_Amendment-3.pdf>";

    }

    revision "2018-12-03" {
      description
        "Amendment 2.
* Approval Date:    2018-12-03.
* Publication Date: 2018-12-03.";
      reference
        "TR-383a2: Common YANG Modules
        	<https://www.broadband-forum.org/technical/download/
        		 TR-383_Amendment-2.pdf>";

    }

    revision "2018-07-13" {
      description
        "Amendment 1.
* Approval Date:    2018-06-04.
* Publication Date: see revision date above.";
      reference
        "TR-383: Common YANG Modules
        	<https://www.broadband-forum.org/technical/download/
        		 TR-383_Amendment-1.pdf>";

    }

    revision "2017-05-08" {
      description
        "Initial revision.
* Approval Date:    see revision date above.
* Publication Date: 2017-06-02.";
      reference
        "TR-383: Common YANG Modules
        	<https://www.broadband-forum.org/technical/download/
        		 TR-383.pdf>";

    }


    feature pre-emption {
      description
        "This feature indicates whether the network element supports
pre-emption.";
    }

    feature tc-id-2-queue-id-mapping-config {
      description
        "This feature indicates whether the network element supports
configuring traffic class ID to queue ID mapping profiles.";
    }

    feature extended-scheduling-weight {
      description
        "Indicates support for extending the maximum weight value from
255 to 65535.";
    }

    feature dual-rate-scheduling-from-queue {
      description
        "Indicates support for dual rate scheduling, i.e., configuring
from a parent scheduler a separate priority and/or weight
for the CIR and EIR traffic from a single child scheduler.";
    }

    feature queue-statistics {
      description
        "Indicates support for reporting statistics per queue.";
    }

    feature queue-templates {
      description
        "Indicates that the network element supports templates to
configure queues.";
    }

    feature queue-template-in-tm-root {
      description
        "Indicates that the network element supports templates to
configure queues in the container 'tm-root'.";
    }

    typedef queue-id {
      type uint32 {
        range "0..7";
      }
      description
        "An integer number identifying a queue within the context from
which traffic will be scheduled. It is an abstract identifier:
its value does NOT represent the priority of the queue itself.
This 'queue-id' value is determined by means of a traffic class
ID to queue ID mapping profile.";
    }

    typedef scheduling-priority {
      type uint8 {
        range "0..7";
      }
      description
        "This number represents the priority of the queue or a scheduler
competing with others in the context of scheduling traffic.
Value 7 means highest priority and 0 means lowest priority.";
    }

    typedef extended-scheduling-priority {
      type uint8 {
        range "0..15";
      }
      description
        "This number represents the priority of the queue or a scheduler
competing with others in the context of scheduling traffic.
Value 15 means highest priority and 0 means lowest priority.";
    }

    typedef scheduling-weight {
      type uint8;
      description
        "If scheduling is to be performed from multiple queues or
schedulers with the same priority, then the scheduling-weight
assigns a weight to each of them.";
    }

    typedef extended-scheduling-weight {
      type uint16;
      description
        "If scheduling is to be performed from multiple queues or
schedulers with the same priority, then the scheduling-weight
assigns a weight to each of them.";
    }

    identity bac-type {
      description
        "Base identity of a Buffer Acceptance Control (BAC) type.";
    }

    identity taildrop {
      base bac-type;
      description "Taildrop BAC type.";
    }

    identity red {
      base bac-type;
      description
        "Random Early Detection (RED) BAC type.";
    }

    identity wtaildrop {
      base bac-type;
      description
        "Weighted taildrop BAC type.";
    }

    identity wred {
      base bac-type;
      description
        "Weighted Random Early Detection (WRED) BAC type.";
    }

    grouping min-threshold {
      description
        "Definition of minimum threshold.";
      leaf min-threshold {
        type bbf-yang:percent;
        description
          "The threshold from which the system begins to discard
incoming frames in a random way.

The value is a percentage to be calculated on the value of
the leaf 'max-queue-size' of the queue on which the BAC is
applied.";
      }
    }  // grouping min-threshold

    grouping max-threshold {
      description
        "Definition of maximum threshold.";
      leaf max-threshold {
        type bbf-yang:percent;
        description
          "The threshold to discard all incoming frames.

The value is a percentage to be calculated on the value of
the leaf 'max-queue-size'.";
      }
    }  // grouping max-threshold

    grouping max-probability {
      description
        "Definition of maximum probability.";
      leaf max-probability {
        type bbf-yang:percent;
        description
          "The maximum discard probability of frames before the
maximum threshold is reached.";
      }
    }  // grouping max-probability

    grouping common-random-early-detection-parameters {
      description
        "A set of parameters common to RED and WRED BAC algorithms.";
      uses min-threshold;

      uses max-threshold;

      uses max-probability;
    }  // grouping common-random-early-detection-parameters

    grouping queue-counters-common {
      description
        "Queue counters common to each frame type, e.g., green frames.";
      leaf out-frames {
        type yang:counter64;
        units "frames";
        description
          "The number of frames transmitted by this queue.";
      }

      leaf out-octets {
        type yang:counter64;
        units "bytes";
        description
          "The number of bytes in frames transmitted by this queue.";
      }

      leaf congestion-discard-frames {
        type yang:counter64;
        units "frames";
        description
          "The number of frames discarded by this queue due to
congestion.";
      }

      leaf congestion-discard-octets {
        type yang:counter64;
        units "bytes";
        description
          "The number of bytes in frames discarded by this queue due to
congestion.";
      }
    }  // grouping queue-counters-common

    grouping queue-counters {
      description
        "Queue counters reported by frame type.";
      container total {
        description
          "Counters associated with all traffic related to this queue.";
        uses queue-counters-common;
      }  // container total

      container green {
        description
          "Counters associated with all traffic, which is considered
green, related to this queue.";
        uses queue-counters-common;
      }  // container green

      container yellow {
        description
          "Counters associated with all traffic, which is considered
yellow, related to this queue.";
        uses queue-counters-common;
      }  // container yellow

      container red {
        description
          "Counters associated with all traffic, which is considered
red, related to this queue.";
        uses queue-counters-common;
      }  // container red
    }  // grouping queue-counters

    grouping reset-queue-counters {
      description
        "Statistics associated with queues.";
      action reset-counters {
        description
          "Reset all queue counters associated with this queue.

Note: this resets the 'counters', i.e., the leafs that
count and wrap around when coming to their maximum value.
This does not include a reset of other gauge statistics.";
      }  // rpc reset-counters
    }  // grouping reset-queue-counters

    grouping queue-statistics {
      description
        "Statistics associated with queues.";
      leaf enqueued-frames {
        type yang:gauge64;
        description
          "The number of frames currently enqueued by this queue.";
      }

      leaf enqueued-octets {
        type yang:gauge64;
        description
          "The number of bytes contained in frames currently enqueued
by this queue.";
      }

      uses queue-counters;
    }  // grouping queue-statistics

    grouping tc-id-2-queue-id-mapping-profile-ref {
      description
        "A reference to a traffic class ID to queue ID mapping
profile.";
      leaf tc-id-2-queue-id-mapping-profile-name {
        if-feature bbf-qos-tm:tc-id-2-queue-id-mapping-config;
        type leafref {
          path "/bbf-qos-tm:tm-profiles/bbf-qos-tm:tc-id-2-queue-id-mapping-profile/bbf-qos-tm:name";
        }
        description
          "The name of a referenced traffic class ID to queue ID mapping
profile.";
      }
    }  // grouping tc-id-2-queue-id-mapping-profile-ref

    grouping bac-ref {
      description
        "A reference to a BAC entry.";
      leaf bac-name {
        type leafref {
          path "/bbf-qos-tm:tm-profiles/bbf-qos-tm:bac-entry/bbf-qos-tm:name";
        }
        description
          "The name of a referenced BAC entry.";
      }
    }  // grouping bac-ref

    grouping scheduling-gen-attr {
      description
        "Configuration data for scheduling traffic from queues.";
      leaf priority {
        type scheduling-priority;
        description
          "The priority used to schedule frames from a queue or
scheduler, relative to the priority assigned to other queues
or schedulers that are defined in the same traffic scheduling
context. For example the set of queues defined for a
particular interface form the context for scheduling outgoing
traffic to this interface.";
      }

      leaf weight {
        type scheduling-weight;
        description
          "Queues or schedulers that are defined in a particular
context, e.g., queues defined to schedule outgoing traffic to
an interface, can have the same priority. The weight defines
the portion of traffic that will be taken from this queue or
scheduler by comparing the weight of this queue or scheduler
against the sum of the weights of all queues or schedulers
with the same scope and the same priority.";
      }

      leaf extended-weight {
        if-feature bbf-qos-tm:extended-scheduling-weight;
        type extended-scheduling-weight;
        must "not(boolean(../weight))" {
          error-message
            "'extended-weight' and 'weight' are configured at the same time.";
          description
            "Both weight and extended weight must not be configured at
the same time.";
        }
        description
          "Queues or schedulers that are defined in a particular
context, e.g., queues defined to schedule outgoing traffic to
an interface, can have the same priority. The weight defines
the portion of traffic that will be taken from this queue or
scheduler by comparing the weight of this queue or scheduler
against the sum of the weights of all queues or schedulers
with the same scope and the same priority.";
      }
    }  // grouping scheduling-gen-attr

    grouping scheduling-attributes {
      description
        "Configuration data for scheduling traffic from queues.";
      leaf priority {
        type extended-scheduling-priority;
        description
          "The priority used to schedule frames from a queue or
scheduler, relative to the priority assigned to other queues
or schedulers that are defined in the same traffic scheduling
context. For example the set of queues defined for a
particular interface form the context for scheduling outgoing
traffic to this interface.";
      }

      leaf extended-weight {
        type extended-scheduling-weight;
        description
          "Queues or schedulers that are defined in a particular
context, e.g., queues defined to schedule outgoing traffic to
an interface, can have the same priority. The weight defines
the portion of traffic that will be taken from this queue or
scheduler by comparing the weight of this queue or scheduler
against the sum of the weights of all queues or schedulers
with the same scope and the same priority.";
      }
    }  // grouping scheduling-attributes

    grouping queues-base {
      description
        "Configuration data for queues.";
      list queue {
        key "local-queue-id";
        description "A queue.";
        leaf local-queue-id {
          type queue-id;
          description
            "The unique ID of this queue.";
        }

        uses bac-ref;

        choice queue-scheduling-cfg-type {
          description
            "Choice of queue scheduling types.";
          case inline {
            description
              "The queue parameters are directly configured here.";
          }  // case inline

          case dual-rate-scheduling {
            if-feature bbf-qos-tm:dual-rate-scheduling-from-queue;
            description
              "The queue parameters are directly configured here.";
            container dual-rate-scheduling {
              description
                "Configuration which determines the separate processing
of CIR and EIR traffic.";
              container cir-traffic {
                description
                  "Configuration for the CIR type of traffic from the
child scheduler that is used by the parent
scheduler.";
                uses bbf-qos-tm:scheduling-attributes;
              }  // container cir-traffic

              container eir-traffic {
                description
                  "Configuration for the EIR type of traffic from the
child scheduler that is used by the parent
scheduler.";
                uses bbf-qos-tm:scheduling-attributes;
              }  // container eir-traffic
            }  // container dual-rate-scheduling
          }  // case dual-rate-scheduling
        }  // choice queue-scheduling-cfg-type

        leaf pre-emption {
          if-feature bbf-qos-tm:pre-emption;
          type boolean;
          description
            "Indicates whether the transmission of a frames from this
queue can be interrupted in favor of frames from a higher
priority queue.";
        }
      }  // list queue

      leaf queue-statistics-enable {
        if-feature bbf-qos-tm:queue-statistics;
        type boolean;
        description
          "If 'true', enable statistics collection per queue. When
transitioning from false to true (disabled to enabled), any
existing counts should be cleared.

The leaf not existing has the same meaning as queue
statistics being disabled.";
      }
    }  // grouping queues-base

    grouping queues {
      description
        "Configuration data for queues.

This grouping exists for historical, backward compatibility
reasons: it provides per queue the original 'one byte' priority
and 'one byte' weight, and adds a second 'two bytes' weight.";
      uses queues-base {
        augment queue/queue-scheduling-cfg-type/inline {
          description
            "Adds data nodes to a queue configured with the inline
scheduling method.";
          uses bbf-qos-tm:scheduling-gen-attr;
        }
      }
    }  // grouping queues

    grouping queues-extended-scheduling {
      description
        "Configuration data for queues.

This grouping exists for an up-to-date scheduling definition:
it provides per queue a 'two bytes' priority and a 'two bytes'
weight.";
      uses queues-base {
        augment queue/queue-scheduling-cfg-type/inline {
          description
            "Adds data nodes to a queue configured with the inline
scheduling method.";
          uses bbf-qos-tm:scheduling-attributes;
        }
      }
    }  // grouping queues-extended-scheduling

    grouping tm-root {
      description
        "The root for traffic management data.
Traffic management involves the following aspects:
- the forwarding decision determined to egress a frame through
  an outgoing traffic container (which can be an interface).
- the traffic container (which can be a bottleneck) is
  associated to a scheduler resolving the contention of
  different queues competing to access the traffic container.
- so after the outgoing traffic container is determined, the
  system needs to determine in which queue of the traffic
  container the frame must be directed. This takes place based
  on the frame's traffic class by means of the traffic class ID
  to queue ID mapping concept.
- at any time, the scheduler resolves which queue should
  deliver the next frame to the egress traffic container by
  looking at the scheduling-priority and scheduling-weight of
  each of queues.
The tm-root represents the scheduling stage directly attached
to the bottleneck resource (typically an interface).";
      container tm-root {
        presence
          "Indicates the interface supports queues, either directly or
through a scheduling hierarchy. Interfaces that support
queues are typically the lowest layer of an interface stack
that is Ethernet frame aware.";
        description
          "The attributes of the root in the scheduling tree.";
        choice children-type {
          description
            "Choice of a tm-root's child data node types.";
          case queues {
            description
              "In this mode the interface related to the tm-root can
directly be selected by the forwarding process and has
its own set of queues. Hence the scheduling of a frame
from a forwarder to the egress queue takes place in a
single stage.";
            uses queues;
          }  // case queues

          case queues-from-template {
            if-feature bbf-qos-tm:queue-templates and bbf-qos-tm:queue-template-in-tm-root;
            description
              "The child data nodes are a list of queues, however these
queues are not explicitly configured. Instead a reference
is provided to a template that contains the definition of
queues to be created.

The queues' state data is as for case 'queue', i.e., when
queue statistics collection is enabled, then the state
data will contain data statistics per queue. The
'queue-id' of the queues is the 'queue-id' used in the
template.";
            container queues-from-template {
              description
                "Data for defining queues using a template.";
              leaf queue-template {
                type leafref {
                  path "/bbf-qos-tm:tm-profiles/bbf-qos-tm:queue-templates/bbf-qos-tm:template/bbf-qos-tm:name";
                }
                description
                  "A reference to a queues template.";
              }

              leaf queue-statistics-enable {
                if-feature bbf-qos-tm:queue-statistics;
                type boolean;
                description
                  "If 'false', no statistics will be collected. If
'true', enable statistics collection per queue. When
transitioning from false to true (disabled to
enabled), any existing counts should be cleared.

Note that statistics collection can also be enabled
from within the template. This leaf defined here
overrules the setting inside the template.

When the leaf defined here is not configured (does
not exist) it means the setting within the template
will be applied. When there is also no setting in the
template it has the same meaning as queue statistics
being disabled.";
              }
            }  // container queues-from-template
          }  // case queues-from-template
        }  // choice children-type

        uses tc-id-2-queue-id-mapping-profile-ref;
      }  // container tm-root
    }  // grouping tm-root

    container tm-profiles {
      description
        "A set of types of profiles for traffic management
configuration.";
      list tc-id-2-queue-id-mapping-profile {
        if-feature tc-id-2-queue-id-mapping-config;
        key "name";
        description
          "A traffic class ID to queue ID mapping profile.";
        leaf name {
          type bbf-yang:string-ascii64;
          description
            "The name of a traffic class ID to queue ID mapping
profile.";
        }

        list mapping-entry {
          key "traffic-class-id";
          description
            "A traffic class ID to queue ID mapping profile. One profile
maps each of the traffic class IDs to a queue ID.";
          leaf traffic-class-id {
            type bbf-qos-t:traffic-class-id;
            description
              "A traffic class ID.";
          }

          leaf local-queue-id {
            type queue-id;
            mandatory true;
            description
              "The identification of a queue locally within a parent
node context.";
          }
        }  // list mapping-entry
      }  // list tc-id-2-queue-id-mapping-profile

      list bac-entry {
        key "name";
        description
          "A Buffer Acceptance Control (BAC) entry.";
        leaf name {
          type bbf-yang:string-ascii64;
          description
            "The name of a BAC entry.";
        }

        leaf max-queue-size {
          type uint32;
          units "bytes";
          description
            "The maximum queue length.";
        }

        choice bac-type {
          mandatory true;
          description "Choice of BAC types.";
          case taildrop {
            description
              "Applicable when the BAC type is 'taildrop'.";
            container taildrop {
              description
                "Management data nodes associated with taildrop.";
              uses max-threshold;
            }  // container taildrop
          }  // case taildrop

          case red {
            description
              "Applicable when the BAC type is 'red'.";
            container red {
              description
                "Management data nodes associated with Random Early
Detection (RED).";
              uses common-random-early-detection-parameters;
            }  // container red
          }  // case red

          case wtaildrop {
            description
              "Applicable when the BAC type is 'wtaildrop'.";
            container wtaildrop {
              description
                "Management data nodes associated with weighted
taildrop.";
              container color {
                description
                  "Management data nodes associated with the marked
color of the frame.";
                container green {
                  description
                    "Green frames.";
                  uses max-threshold;
                }  // container green

                container yellow {
                  description
                    "Yellow frames.";
                  uses max-threshold;
                }  // container yellow

                container red {
                  description "Red frames.";
                  uses max-threshold;
                }  // container red
              }  // container color
            }  // container wtaildrop
          }  // case wtaildrop

          case wred {
            description
              "Applicable when the BAC type is 'wred'.";
            container wred {
              description
                "Management data nodes associated with Weighted
Random Early Detection.";
              container color {
                description
                  "Management data nodes associated with the marked
color of the frame.";
                container green {
                  description
                    "Green frames.";
                  uses common-random-early-detection-parameters;
                }  // container green

                container yellow {
                  description
                    "Yellow frames.";
                  uses common-random-early-detection-parameters;
                }  // container yellow

                container red {
                  description "Red frames.";
                  uses common-random-early-detection-parameters;
                }  // container red
              }  // container color
            }  // container wred
          }  // case wred
        }  // choice bac-type
      }  // list bac-entry

      container queue-templates {
        if-feature queue-templates;
        description
          "Contains data nodes for configuring templates for a set of
queues.";
        list template {
          key "name";
          description
            "A template for a a set of queues.

A template provides a method to configure a pattern for a
specific behavior, but on its own it does not result in an
actual behavior. It needs to be referenced and then the
actual behavior is within the context from where it is
referenced.";
          leaf name {
            type bbf-yang:string-ascii64;
            description
              "A name of a template with queues.";
          }

          uses queues-extended-scheduling;
        }  // list template
      }  // container queue-templates
    }  // container tm-profiles

    augment /if:interfaces/if:interface {
      description
        "Augments the interface with traffic management data.";
      uses tm-root;
    }
  }  // module bbf-qos-traffic-mngt