man: tc-mqprio: extend prio-tc-queue mapping with examples

The current mqprio manual is not detailed about queue mapping
and priorities, this patch adds some examples to it.

Suggested-by: Ferenc Fejes <fejes@inf.elte.hu>
Signed-off-by: Péter Antal <peti.antal99@gmail.com>
Acked-by: Ferenc Fejes <fejes@inf.elte.hu>
Acked-by: Péter Antal <peti.antal99@gmail.com>
Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>

1 files changed, 96 insertions, 0 deletions

diff --git a/man/man8/tc-mqprio.8 b/man/man8/tc-mqprio.8
index 4b9e942ef..16ecb9a1d 100644
--- a/man/man8/tc-mqprio.8
+++ b/man/man8/tc-mqprio.8
@@ -98,6 +98,7 @@ belong to an application. See kernel and cgroup documentation for details.
 .TP
 num_tc
 Number of traffic classes to use. Up to 16 classes supported.
+You cannot have more classes than queues
 
 .TP
 map
@@ -119,6 +120,8 @@ Set to
 to support hardware offload. Set to
 .B 0
 to configure user specified values in software only.
+The default value of this parameter is
+.B 1
 
 .TP
 mode
@@ -146,5 +149,98 @@ max_rate
 Maximum value of bandwidth rate limit for a traffic class.
 
 
+.SH EXAMPLE
+
+The following example shows how to attach priorities to 4 traffic classes ("num_tc 4"),
+and then how to pair these traffic classes with 4 hardware queues with mqprio,
+with hardware coordination ("hw 1", or does not specified, because 1 is the default value).
+Traffic class 0 (tc0) is mapped to hardware queue 0 (q0), tc1 is mapped to q1,
+tc2 is mapped to q2, and tc3 is mapped q3.
+
+.EX
+# tc qdisc add dev eth0 root mqprio \
+              num_tc 4 \
+              map 0 0 0 0 1 1 1 1 2 2 2 2 3 3 3 3 \
+              queues 1@0 1@1 1@2 1@3 \
+              hw 1
+.EE
+
+The next example shows how to attach priorities to 3 traffic classes ("num_tc 3"),
+and how to pair these traffic classes with 4 queues,
+without hardware coordination ("hw 0").
+Traffic class 0 (tc0) is mapped to hardware queue 0 (q0), tc1 is mapped to q1,
+tc2 and is mapped to q2 and q3, where the queue selection between these
+two queues is somewhat randomly decided.
+
+.EX
+# tc qdisc add dev eth0 root mqprio \
+              num_tc 3 \
+              map 0 0 0 0 1 1 1 1 2 2 2 2 2 2 2 2 \
+              queues 1@0 1@1 2@2 \
+              hw 0
+.EE
+
+
+In both cases from above the priority values from 0 to 3 (prio0-3) are
+mapped to tc0, prio4-7 are mapped to tc1, and the
+prio8-11 are mapped to tc2 ("map" attribute). The last four priority values
+(prio12-15) are mapped in different ways in the two examples.
+They are mapped to tc3 in the first example and mapped to tc2 in the second example.
+The values of these two examples are the following:
+
+ ┌────┬────┬───────┐  ┌────┬────┬────────┐
+ │Prio│ tc │ queue │  │Prio│ tc │  queue │
+ ├────┼────┼───────┤  ├────┼────┼────────┤
+ │  0 │  0 │     0 │  │  0 │  0 │      0 │
+ │  1 │  0 │     0 │  │  1 │  0 │      0 │
+ │  2 │  0 │     0 │  │  2 │  0 │      0 │
+ │  3 │  0 │     0 │  │  3 │  0 │      0 │
+ │  4 │  1 │     1 │  │  4 │  1 │      1 │
+ │  5 │  1 │     1 │  │  5 │  1 │      1 │
+ │  6 │  1 │     1 │  │  6 │  1 │      1 │
+ │  7 │  1 │     1 │  │  7 │  1 │      1 │
+ │  8 │  2 │     2 │  │  8 │  2 │ 2 or 3 │
+ │  9 │  2 │     2 │  │  9 │  2 │ 2 or 3 │
+ │ 10 │  2 │     2 │  │ 10 │  2 │ 2 or 3 │
+ │ 11 │  2 │     2 │  │ 11 │  2 │ 2 or 3 │
+ │ 12 │  3 │     3 │  │ 12 │  2 │ 2 or 3 │
+ │ 13 │  3 │     3 │  │ 13 │  2 │ 2 or 3 │
+ │ 14 │  3 │     3 │  │ 14 │  2 │ 2 or 3 │
+ │ 15 │  3 │     3 │  │ 15 │  2 │ 2 or 3 │
+ └────┴────┴───────┘  └────┴────┴────────┘
+       example1             example2
+
+
+Another example of queue mapping is the following.
+There are 5 traffic classes, and there are 8 hardware queues.
+
+.EX
+# tc qdisc add dev eth0 root mqprio \
+              num_tc 5 \
+              map 0 0 0 1 1 1 1 2 2 3 3 4 4 4 4 4 \
+              queues 1@0 2@1 1@3 1@4 3@5
+.EE
+
+The value mapping is the following for this example:
+
+        ┌───────┐
+ tc0────┤Queue 0│◄────1@0
+        ├───────┤
+      ┌─┤Queue 1│◄────2@1
+ tc1──┤ ├───────┤
+      └─┤Queue 2│
+        ├───────┤
+ tc2────┤Queue 3│◄────1@3
+        ├───────┤
+ tc3────┤Queue 4│◄────1@4
+        ├───────┤
+      ┌─┤Queue 5│◄────3@5
+      │ ├───────┤
+ tc4──┼─┤Queue 6│
+      │ ├───────┤
+      └─┤Queue 7│
+        └───────┘
+
+
 .SH AUTHORS
 John Fastabend, <john.r.fastabend@intel.com>