Merge pull request #759 from kernelkit/jovatn/doc-vlan-iface-qos

Update QoS documentation (VLAN interface ingress/egress priority)

doc/ChangeLog.md

@@ -4,6 +4,15 @@ Change Log
 All notable changes to the project are documented in this file.
 
 
+[v24.10.2][UNRELEASED]
+-------------------------
+
+### Changes
+
+- Updated QoS documentation with pictures and more information on VLAN
+  interface ingress/egress priority handling.
+
+
 [v24.10.1][] - 2024-10-18
 -------------------------
 
@@ -1244,7 +1253,7 @@ Supported YANG models in addition to those used by sysrepo and netopeer:
  - N/A
 
 [buildroot]:  https://buildroot.org/
-[UNRELEASED]: https://github.com/kernelkit/infix/compare/v24.10.0...HEAD
+[UNRELEASED]: https://github.com/kernelkit/infix/compare/v24.10.1...HEAD
 [v24.10.1]:   https://github.com/kernelkit/infix/compare/v24.10.0...v24.10.1
 [v24.10.0]:   https://github.com/kernelkit/infix/compare/v24.09.0...v24.10.0
 [v24.09.0]:   https://github.com/kernelkit/infix/compare/v24.08.0...v24.09.0

doc/qos.md

@@ -12,14 +12,6 @@ packets to drop and which ones to prioritize, such that critical
 services remain operational.
 
 
-## Software Forwarded Traffic
-
-For packets which are processed by a CPU, i.e. typically routed
-traffic, and bridged traffic between interfaces that do not belong to
-the same hardware switching domain, an [nftables container][1] can be
-used to define a QoS policy.
-
-
 ## Hardware Forwarded Traffic
 
 The default QoS policy for flows which are offloaded to a switching
@@ -34,6 +26,14 @@ chips in this family where limited to 4 output queues per port, this
 documentation is _only_ valid for newer generations with 8 output
 queues per port.
 
+![Hardware offloading for Marvell Link Street](img/qos-hw-mvls.svg)
+
+The picture illustrates packets having their priority determined at
+ingress, here interface _e1_ and _e3_. In this example, both packets
+are forwarded to the same outgoing interface (_e2_), subject to output
+queueing. The sections below provides more information on these
+topics. 
+
 #### Default Policy
 
 ##### Queueing
@@ -73,6 +73,41 @@ set to the 3 most significant bits of it. If no priority information
 is available in the frame on ingress (i.e. untagged non-IP), then
 packets will egress out of tagged ports with PCP set to 0.
 
+## Software Forwarded Traffic
+
+For packets which are processed by a CPU, i.e. typically routed
+traffic, and bridged traffic between interfaces that do not belong to
+the same hardware switching domain, an [nftables container][1] can be
+used to define a QoS policy.
+
+For VLAN interfaces, Infix provides support for mapping the Priority
+Code Point (PCP) to internal priority on ingress, and the reverse on
+egress. 
+
+![Ingress and Egress Priority mapping for VLAN interfaces](img/qos-vlan-iface.svg)
+
+
+These `ingress-qos` and `egress-qos` settings are done per VLAN, both
+defaulting to '0'. The example below shows how to keep the PCP priority 
+for packets being routed between two VLAN interfaces.
+
+```
+admin@example:/config/> edit interface e1.10
+admin@example:/config/interface/e1.10/> set vlan ingress-qos priority from-pcp 
+admin@example:/config/interface/e1.10/> up
+admin@example:/config/> edit interface e1.20
+admin@example:/config/interface/e1.20/> set vlan egress-qos pcp from-priority 
+admin@example:/config/interface/e1.20/> leave
+admin@example:/> 
+```
+
+## A complex example
+
+The picture below shows a packet flow being subject both to software
+forwarding and hardware offloading.
+
+![Hardware and Software QoS Handling](img/qos-complex.svg)
+
 
 [1]: container.md#application-container-nftables
 [2]: https://en.wikipedia.org/wiki/IEEE_802.1Q