Add QoS overview
Change-Id: I36306e09698ec17b0ac393641d0e9020deb0fdb4
diff --git a/advanced/qos.rst b/advanced/qos.rst
index cc7327d..757b56b 100644
--- a/advanced/qos.rst
+++ b/advanced/qos.rst
@@ -3,16 +3,116 @@
.. _qos_configuration:
+Overview
+--------
+
+Network slicing enables sharing the same physical infrastructure between
+independent logical networks, each one targeting different use cases while
+providing isolation and security guarantees. Slicing permits the implementation
+of tailor-made applications with Quality of Service (QoS) specific to the needs
+of each slice, rather than a one-size-fits-all approach.
+
+SD-Fabric supports slicing and QoS using dedicated hardware resources such as
+scheduling queues and meters. Once a packet enters the fabric, it is associated
+with a slice ID and traffic Class (TC). Slice ID is an arbitrary identifier,
+while TC is used to determine the QoS parameters. The combination of slice ID
+and TC is used by SD-Fabric to determine which switch hardware queue to use.
+
+We provide fabric-wide isolation and QoS guarantees. Packets are classified by
+the first leaf switch in the path, we then use a custom DSCP-based marking
+scheme to apply the same treatment on all switches.
+
+Classification can be achieved for both regular traffic via REST APIs, or for
+GTP-U traffic terminated by P4-UPF using PFCP integration.
+
+Traffic Classes
+^^^^^^^^^^^^^^^
+
+We supports the following traffic classes that covers the spectrum of
+applications from latency-sensitive to throughput-intensive.
+
+Control
+"""""""
+For applications demanding ultra-low latency and jitter guarantees, with
+non-bursty, low throughput requirements in the order of 100s of packets per
+second. Examples of such applications are consensus protocols, industrial
+automation, timing, etc. This class uses a queue shared by all slices, serviced
+with the highest priority. To enforce isolation between slices, and to avoid
+starvation of lower priority classes, each slice is processed through a
+single-rate two-color meter. Slices sending at rates higher than the configured
+meter rate might observe packet drops.
+
+Real-Time
+"""""""""
+For applications that require both low-latency and sustained throughput.
+Examples of such applications are video and audio streaming. Each slice gets a
+dedicated Real-Time queue serviced in a Round-Robin fashion to guarantee the
+lowest latency at all times even with bursty senders. To avoid starvation of
+lower priority classes, Real-Time queues are shaped at a maximum rate. Slices
+sending at rates higher than the configured one might observe higher latency
+because of the shaping. Real-Time queues have priority lower than Control, but
+higher than Elastic.
+
+Elastic
+"""""""
+For throughput-intensive applications with no latency requirements. This class
+is best suited for large file transfers, Intranet/enterprise applications,
+prioritized Internet access, etc. Each slice gets a dedicated Elastic queue
+serviced in Weighted Round-Robin (WRR) fashion with configurable weights. During
+congestion, Elastic queues are guaranteed to receive minimum bandwidth that can
+grow up to the link capacity if other queues are empty.
+
+Best-Effort
+"""""""""""
+This is the default traffic class, used by packets not classified with any of
+the above classes All slices share the same best-effort queue with lowest
+priority.
+
+Classification
+^^^^^^^^^^^^^^^
+
+Slice ID and TC classification can be performed in two ways.
+
+Regular traffic
+"""""""""""""""
+We provide an ACL-like APIs that supports specifying wildcard match rules on the
+IPv4 5-tuple.
+
+P4-UPF traffic
+""""""""""""""
+When using the embedded UPF function, for GTP-U mobile traffic terminated by the
+fabric, we support integration with PFCP QoS features such as prioritization via
+QoS Flow Identifier (QFI), Maximum Bitrate (MBR) limits, and Guaranteed Bitrate
+(GBR).
+
+You can configure a static one-to-one mapping between 3GPP’s QFIs and
+SD-Fabric’s TCs using the ONOS netcfg JSON file (work-in-progress), while MBR
+and GBR configuration are translated into meter configurations.
+
+QoS classification uses the same table for GTP-U tunnel termination, for this
+reason, to achieve fabric-wide QoS enforcement, we recommend enabling the UPF
+function on each leaf switch using the distributed UPF mode, such that packets
+are classified as soon as they enter the network.
+
+Support for slicing of mobile traffic is work-in-progress and will be added in
+the next SD-Fabric release.
+
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.
+QoS and slicing uses switch queue configuration provided via the
+``vendor_config`` portion of the Stratum Chassis Config (see
+:ref:`stratum_chassis_config`), where the queues and schedulers can be
+configured. For more information on the format of ``vendor_config``, see the
+`guide for running Stratum on Tofino-based switches
+<https://github.com/stratum/stratum/blob/main/stratum/hal/bin/barefoot/README.run.md>`_
+in the Stratum repository.
+
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.
+This file allows to configure the parameters for the traffic classes listed in the above section.
Here's a list of parameters that you can configure via the YAML QoS configuration file:
@@ -98,7 +198,7 @@
Mutually exclusive with ``sdk_port_ids`` field.
- * ``sdk_port_ids``: List of SDK port numbers (i.e., Tofino DP_ID) using this port template.
+ * ``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.
@@ -130,8 +230,8 @@
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.
+We provide REST APIs with support for adding/removing/querying slices and
+traffic classes, as well as flow classification.
Slice
^^^^^
diff --git a/dict.txt b/dict.txt
index 2247e57..e493cee 100644
--- a/dict.txt
+++ b/dict.txt
@@ -1,5 +1,6 @@
# Please keep lines in ascending case-sensitive order, so it's easier to spot duplicates
# during merge conflict resolution.
+ACL
Aether
Analytics
Broadcom
@@ -54,6 +55,7 @@
bitrate
blackhole
blackholing
+bursty
centric
chipset
codename