QoS and Slicing
===============

.. _qos_configuration:

Configuration
-------------
.. note:: QoS and slicing configuration is currently statically configured at switch startup.
   Dynamic configuration will be supported in a next SD-Fabric release.

QoS and Slicing is configured via the ``vendor_config`` portion of the Stratum Chassis Config (see :ref:`stratum_chassis_config`),
where the queues and schedulers can be configured.
We provide a convenient `script <https://github.com/stratum/fabric-tna/blob/main/util/gen-stratum-qos-config.py>`_
to generate the configuration starting from a higher-level description provided via a YAML file.
This file allows to configure the parameters for the traffic classes listed in the previous sections.

Here's a list of parameters that you can configure via the YAML QoS configuration file:

* ``max_cells``: Maximum number of buffer cells, depends on the ASIC SKU/revision.

* ``pool_allocations``: Percentage of buffer cells allocated to each traffic class.
  The sum should be 100. Usually, we leave a portion of the buffer ``unassigned``
  for queues that do not have a pool (yet).
  Example of such queues are those for the recirculation port, CPU port, etc.

  .. code-block:: yaml

    pool_allocations:
      control: 1
      realtime: 9
      elastic: 80
      besteffort: 9
      unassigned: 1

* **Control** Traffic Class: The available bandwidth dedicated to Control traffic is divided in *slots*.
  Each slot has a maximum rate and burst (in packets of the given MTU).
  A slice can use one or more slots by appropriately configuring meters in the fabric ingress pipeline.

  * ``control_slot_count``: Number of slots.
  * ``control_slot_rate_pps``: Packet per second rate of each slot.
  * ``control_slot_burst_pkts``: Number of packets per burst of each slot.
  * ``control_mtu_bytes``: MTU of packets for the PPS and burst values.

  .. code-block:: yaml

    control_slot_count: 50
    control_slot_rate_pps: 100
    control_slot_burst_pkts: 10
    control_mtu_bytes: 1500

* **Real-Time** Traffic Class Configuration:

  * ``realtime_max_rates_bps``: List of maximum shaping rates for Real-Time queues,
    one per slice requesting such service.

  * ``realtime_max_burst_s``: Maximum amount of time that a Real-Time queue can
    burst at the port speed. This parameter is used to limit delay for Elastic
    queues.

  .. code-block:: yaml

    realtime_max_rates_bps:
      - 45000000 # 45 Mbps
      - 30000000 # 30 Mbps
      - 25000000 # 25 Mbps
    realtime_max_burst_s: 0.005 # 5 ms

* **Elastic** Traffic Class Configuration:

  * ``elastic_min_rates_bps``: List of minimum guaranteed rates for Elastic queues,
    one per slice requesting such service.

  .. code-block:: yaml

    elastic_min_rates_bps:
      - 100000000 # 100 Mbps
      - 200000000 # 200 Mbps

* ``port_templates`` section: List of switch port for which we want to configure
  queues.

  Every ``port_templates`` element contains:

    * ``descr``: Description of the port purpose.

    * ``rate_bps``: Port speed in bit per second.

    * ``is_shaping_enabled``: ``true`` if the rate is enforced using shaping,
      ``false`` if the rate is the channel speed.

    * ``shaping_burst_bytes``: Burst size in bytes, meaningful only if port speed
      is shaped (when ``is_shaping_enabled: true``).

    * ``queue_count``: Number of queues assigned to the port.

    * ``port_ids``: List of Stratum port IDs (:ref:`singleton_port` from Stratum Chassis Config),
      using this port template. Used for port that corresponds to switch front-panel ports.

      Mutually exclusive with ``sdk_port_ids`` field.

    * ``sdk_port_ids``: List of SDK port numbers (i.e., Tofino DP_ID) using this port template.
      Used for internal ports (e.g., recirculation ports).

      Mutually exclusive with ``port_ids`` field.

  .. code-block:: yaml

    port_templates:
      - descr: "Base station"
        rate_bps: 1000000000 # 1 Gbps
        is_shaping_enabled: true
        shaping_burst_bytes: 18000 # 2x jumbo frames
        queue_count: 16
        port_ids:
          - 100
      - descr: "Servers"
        port_ids:
          - 200
        rate_bps: 40000000000 # 40 Gbps
        is_shaping_enabled: false
        queue_count: 16
      - descr: "Recirculation"
        sdk_port_ids:
          - 68
        rate_bps: 100000000000 # 100 Gbps
        is_shaping_enabled: false
        queue_count: 16

An example of a complete QoS and Slicing configuration can be found `here <https://github.com/stratum/fabric-tna/blob/main/util/sample-qos-config.yaml>`_.

REST API
--------
REST API supports adding/removing/querying slices and traffic classes.
We can also classify a flow (identified by five tuples) via REST API.

Slice
^^^^^

Add a slice
"""""""""""
A POST request with Slice ID as path parameter.
``/slicing/slice/{sliceId}``

.. image:: ../images/qos-rest-slice-add.png
    :width: 700px

Remove a slice
"""""""""""""""
A DELETE request with Slice ID as path parameter.
``/slicing/slice/{sliceId}``

.. image:: ../images/qos-rest-slice-remove.png
    :width: 700px

Get all slices
""""""""""""""
A GET request.
Returns a collection of slice id.
/slicing/slice

.. image:: ../images/qos-rest-slice-get.png
    :width: 700px

Traffic Class
^^^^^^^^^^^^^
.. tip::
    Traffic Class has following attributes: ``BEST_EFFORT``, ``CONTROL``, ``REAL_TIME``, ``ELASTIC``.

Add a traffic class to a slice
""""""""""""""""""""""""""""""
A POST request with Slice ID and Traffic Class as path parameters.
``/slicing/tc/{sliceId}/{tc}``

.. image:: ../images/qos-rest-tc-add.png
    :width: 700px

Remove a traffic class from a slice
"""""""""""""""""""""""""""""""""""
A DELETE request with Slice ID and Traffic Class as path parameters.
``/slicing/tc/{sliceId}/{tc}``

.. image:: ../images/qos-rest-tc-remove.png
    :width: 700px

Get all traffic classes from a slice
""""""""""""""""""""""""""""""""""""
A GET request with Slice ID as path parameters.
Returns a collection of traffic class.
``/slicing/tc/{sliceId}``

.. image:: ../images/qos-rest-tc-get.png
    :width: 700px

Classify Flow
^^^^^^^^^^^^^

A flow can be defined as

.. code-block:: json

  {
    "criteria": [
      {
        "type": "IPV4_SRC",
        "ip": "10.0.0.1/32"
      },
      {
        "type": "IPV4_DST",
        "ip": "10.0.0.2/32"
      },
      {
        "type": "IP_PROTO",
        "protocol": 6
      },
      {
        "type": "TCP_SRC",
        "tcpPort": 1000
      },
      {
        "type": "TCP_DST",
        "tcpPort": 80
      },
      {
        "type": "UDP_SRC",
        "udpPort": 1000
      },
      {
        "type": "UDP_DST",
        "udpPort": 1812
      }
    ]
  }

- ``IPV4_SRC``: Source IPv4 prefix

- ``IPV4_DST``: Destination IPv4 prefix

- ``IP_PROTO``: IP Protocol, accept 6 (TCP) and 17 (UDP)

- ``TCP_SRC``: Source L4 (TCP) port

- ``TCP_DST``: Destination L4 (TCP) port

- ``UDP_SRC``: Source L4 (UDP) port

- ``UDP_DST``: Destination L4 (UDP) port

.. note::
    SD-Fabric currently supports 5-tuple only.

Classify a flow to a slice and traffic class
""""""""""""""""""""""""""""""""""""""""""""
A POST request with Slice ID and Traffic Class as path parameters.
And a Json of a flow as body parameters.
``/slicing/flow/{sliceId}/{tc}``

.. image:: ../images/qos-rest-classifier-add.png
    :width: 700px

Remove a flow from a slice and traffic class
""""""""""""""""""""""""""""""""""""""""""""
A DELETE request with Slice ID and Traffic Class as path parameters.
And a Json of a flow as body parameters.
``/slicing/flow/{sliceId}/{tc}``

.. image:: ../images/qos-rest-classifier-remove.png
    :width: 700px

Get all classified flows from a slice and traffic class
"""""""""""""""""""""""""""""""""""""""""""""""""""""""
A GET request with Slice ID and Traffic Class as path parameters.
Returns a collection of flow.
``/slicing/flow/{sliceId}``

.. image:: ../images/qos-rest-classifier-get.png
    :width: 700px