[PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Péter Antal]

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>
---
 man/man8/tc-mqprio.8 | 96 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/man/man8/tc-mqprio.8 b/man/man8/tc-mqprio.8
index 4b9e942e..16ecb9a1 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>
-- 
2.34.1

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Ferenc Fejes]

Hi!

On Mon, 2023-02-20 at 16:05 +0100, Péter Antal wrote:
> The current mqprio manual is not detailed about queue mapping
> and priorities, this patch adds some examples to it.

Thank you Péter for doing this! The same principles however applies to
tc-taprio as well so it would be nice to see a v2 with those included
too.

> 
> Suggested-by: Ferenc Fejes <fejes@inf.elte.hu>
> Signed-off-by: Péter Antal <peti.antal99@gmail.com>
> ---
>  man/man8/tc-mqprio.8 | 96
> ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 96 insertions(+)
> 
> diff --git a/man/man8/tc-mqprio.8 b/man/man8/tc-mqprio.8
> index 4b9e942e..16ecb9a1 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

It especially important when applied to multi TX queue veth.
Vladimir already addressed this in kernel UAPI to give more expressive
error message:
https://lore.kernel.org/netdev/20230220122343.1156614-6-vladimir.oltean@nxp.com/T/#u

But knowing the default parameter from the manpage is still a good
addition IMO.

>  
>  .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>

Best,
Ferenc

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Vladimir Oltean]

On Mon, Feb 20, 2023 at 04:15:43PM +0100, Ferenc Fejes wrote:
> Hi!
> 
> On Mon, 2023-02-20 at 16:05 +0100, Péter Antal wrote:
> > The current mqprio manual is not detailed about queue mapping
> > and priorities, this patch adds some examples to it.
> 
> Thank you Péter for doing this! The same principles however applies to
> tc-taprio as well so it would be nice to see a v2 with those included
> too.

I think that the well-established phrase "See mqprio(8) for more details."
will do just fine.

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Vladimir Oltean]

Hi Péter,

On Mon, Feb 20, 2023 at 04:05:48PM +0100, Péter Antal wrote:
> 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>
> ---

I think it's great that you are doing this. However, with all due respect,
this conflicts with the man page restructuring I am already doing for the
frame preemption work. Do you mind if I fix up some things and I pick your
patch up, and submit it as part of my series? I have some comments below.

>  man/man8/tc-mqprio.8 | 96 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 96 insertions(+)
> 
> diff --git a/man/man8/tc-mqprio.8 b/man/man8/tc-mqprio.8
> index 4b9e942e..16ecb9a1 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

More impersonal: "There cannot be more traffic classes than TX 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 mqprio" is understated I think, this is the mqprio man page

> +with hardware coordination ("hw 1", or does not specified, because 1 is the default value).

Just leave it at that, "hw 1".

> +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.

Would prefer saying TC0, TXQ0 etc if you don't mind.

> +
> +.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.

Would rather say that packets are hashed arbitrarily between TXQ3 and
TXQ4, which have the same scheduling priority.

We should probably clarify what "hardware coordination" means, exactly.
Without hardware coordination, the device driver is not notified of the
number of traffic classes and their mapping to TXQs. The device is not
expected to prioritize between traffic classes without hardware
coordination.

We should also probably clarify that with hardware coordination, the
device driver can install a different TXQ configuration than requested,
and that the default TC to TXQ mapping is:

TC 0: 0 queues @ offset 0
TC 1: 0 queues @ offset 0
...
TC N: 0 queues @ offset 0

Should also probably clarify that there is a default prio:tc map of:

.prio_tc_map = { 0, 1, 2, 3, 4, 5, 6, 7, 0, 1, 1, 1, 3, 3, 3, 3 },

hmm... you gave me more work than I was intending to do :)

> +
> +.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

What would you say if we didn't put the 2 examples side by side, but
kept them separately? Also, I get the feeling that the verbiage above
the tables is a bit too much. Having the tables is already good enough.

> +
> +Another example of queue mapping is the following.
> +There are 5 traffic classes, and there are 8 hardware queues.

I think for maintainability, the examples should be fairly independent,
because they might be moved around in the future. This story-like
"the following example" -> "the next example" -> "another example"
doesn't really work.

> +.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

The formatting here and everywhere doesn't look very well when viewed
with "man -l man/man8/tc-mqprio.8". If you look at tc-taprio.8, it uses
"\\" to render properly. If you don't mind, I'll do that here too.

> +.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>
> -- 
> 2.34.1
>

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Péter Antal]

Hi Vladimir,

Vladimir Oltean <vladimir.oltean@nxp.com> ezt írta (időpont: 2023.
febr. 20., H, 16:29):
>
> Hi Péter,
>
> On Mon, Feb 20, 2023 at 04:05:48PM +0100, Péter Antal wrote:
> > 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>
> > ---
>
> I think it's great that you are doing this. However, with all due respect,
> this conflicts with the man page restructuring I am already doing for the
> frame preemption work. Do you mind if I fix up some things and I pick your
> patch up, and submit it as part of my series? I have some comments below.

That's all right, thank you for doing this, just please carry my
signoff as co-developer if possible.
I agree with most of your suggestions.

>
> >  man/man8/tc-mqprio.8 | 96 ++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 96 insertions(+)
> >
> > diff --git a/man/man8/tc-mqprio.8 b/man/man8/tc-mqprio.8
> > index 4b9e942e..16ecb9a1 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
>
> More impersonal: "There cannot be more traffic classes than TX 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 mqprio" is understated I think, this is the mqprio man page
>
> > +with hardware coordination ("hw 1", or does not specified, because 1 is the default value).
>
> Just leave it at that, "hw 1".
>
> > +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.
>
> Would prefer saying TC0, TXQ0 etc if you don't mind.
>
> > +
> > +.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.
>
> Would rather say that packets are hashed arbitrarily between TXQ3 and
> TXQ4, which have the same scheduling priority.

If I understand it correctly, this depends on the "hw" parameter.
So if the driver handles this (hw 1), then it may prioritize a queue
over another,
even if they have the same priority.

>
> We should probably clarify what "hardware coordination" means, exactly.
> Without hardware coordination, the device driver is not notified of the
> number of traffic classes and their mapping to TXQs. The device is not
> expected to prioritize between traffic classes without hardware
> coordination.
>
> We should also probably clarify that with hardware coordination, the
> device driver can install a different TXQ configuration than requested,
> and that the default TC to TXQ mapping is:
>
> TC 0: 0 queues @ offset 0
> TC 1: 0 queues @ offset 0
> ...
> TC N: 0 queues @ offset 0
>

First time I see hardware coordination in this manual is the hw parameter,
so I think we should clarify this there.

> Should also probably clarify that there is a default prio:tc map of:
>
> .prio_tc_map = { 0, 1, 2, 3, 4, 5, 6, 7, 0, 1, 1, 1, 3, 3, 3, 3 },
>
> hmm... you gave me more work than I was intending to do :)

Sorry about that :)

>
> > +
> > +.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
>
> What would you say if we didn't put the 2 examples side by side, but
> kept them separately? Also, I get the feeling that the verbiage above
> the tables is a bit too much. Having the tables is already good enough.
>
> > +
> > +Another example of queue mapping is the following.
> > +There are 5 traffic classes, and there are 8 hardware queues.
>
> I think for maintainability, the examples should be fairly independent,
> because they might be moved around in the future. This story-like
> "the following example" -> "the next example" -> "another example"
> doesn't really work.
>
> > +.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
>
> The formatting here and everywhere doesn't look very well when viewed
> with "man -l man/man8/tc-mqprio.8". If you look at tc-taprio.8, it uses
> "\\" to render properly. If you don't mind, I'll do that here too.
>
> > +.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>
> > --
> > 2.34.1
> >

Best,
Peter

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Ferenc Fejes]

Hi Vladimir!

On Mon, 2023-02-20 at 17:01 +0100, Péter Antal wrote:
> Hi Vladimir,
> 
> Vladimir Oltean <vladimir.oltean@nxp.com> ezt írta (időpont: 2023.
> febr. 20., H, 16:29):
> > 
> > Hi Péter,
> > 
> > On Mon, Feb 20, 2023 at 04:05:48PM +0100, Péter Antal wrote:
> > > 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>
> > > ---
> > 
> > I think it's great that you are doing this. However, with all due
> > respect,
> > this conflicts with the man page restructuring I am already doing
> > for the
> > frame preemption work. Do you mind if I fix up some things and I
> > pick your
> > patch up, and submit it as part of my series? I have some comments
> > below.
> 
> That's all right, thank you for doing this, just please carry my
> signoff as co-developer if possible.
> I agree with most of your suggestions.
> 
> > 
> > >  man/man8/tc-mqprio.8 | 96
> > > ++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 96 insertions(+)
> > > 
> > > diff --git a/man/man8/tc-mqprio.8 b/man/man8/tc-mqprio.8
> > > index 4b9e942e..16ecb9a1 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
> > 
> > More impersonal: "There cannot be more traffic classes than TX
> > 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 mqprio" is understated I think, this is the mqprio man page
> > 
> > > +with hardware coordination ("hw 1", or does not specified,
> > > because 1 is the default value).
> > 
> > Just leave it at that, "hw 1".
> > 
> > > +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.
> > 
> > Would prefer saying TC0, TXQ0 etc if you don't mind.

+1, also taprio's manpage using capitals too, but with a space between
TC and the index like "TC 0". Great think if they would harmonize.

> > 
> > > +
> > > +.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.
> > 
> > Would rather say that packets are hashed arbitrarily between TXQ3
> > and
> > TXQ4, which have the same scheduling priority.
> 
> If I understand it correctly, this depends on the "hw" parameter.
> So if the driver handles this (hw 1), then it may prioritize a queue
> over another,
> even if they have the same priority.
> 
> > 
> > We should probably clarify what "hardware coordination" means,
> > exactly.
> > Without hardware coordination, the device driver is not notified of
> > the
> > number of traffic classes and their mapping to TXQs. The device is
> > not
> > expected to prioritize between traffic classes without hardware
> > coordination.
> > 
> > We should also probably clarify that with hardware coordination,
> > the
> > device driver can install a different TXQ configuration than
> > requested,
> > and that the default TC to TXQ mapping is:
> > 
> > TC 0: 0 queues @ offset 0
> > TC 1: 0 queues @ offset 0
> > ...
> > TC N: 0 queues @ offset 0
> > 
> 
> First time I see hardware coordination in this manual is the hw
> parameter,
> so I think we should clarify this there.
> 
> > Should also probably clarify that there is a default prio:tc map
> > of:
> > 
> > .prio_tc_map = { 0, 1, 2, 3, 4, 5, 6, 7, 0, 1, 1, 1, 3, 3, 3, 3 },
> > 
> > hmm... you gave me more work than I was intending to do :)
> 
> Sorry about that :)
> 
> > 
> > > +
> > > +.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
> > 
> > What would you say if we didn't put the 2 examples side by side,
> > but
> > kept them separately? Also, I get the feeling that the verbiage
> > above
> > the tables is a bit too much. Having the tables is already good
> > enough.

I think thats just saving some space and not to scare the mqprio
manpage reader even more :-)
But yes, having tables itself good enough.

> > 
> > > +
> > > +Another example of queue mapping is the following.
> > > +There are 5 traffic classes, and there are 8 hardware queues.
> > 
> > I think for maintainability, the examples should be fairly
> > independent,
> > because they might be moved around in the future. This story-like
> > "the following example" -> "the next example" -> "another example"
> > doesn't really work.

Yes, if you carry this forward in your patches I think just better to
omit the storytelling. Péter probably ACK it too.

> > 
> > > +.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
> > 
> > The formatting here and everywhere doesn't look very well when
> > viewed
> > with "man -l man/man8/tc-mqprio.8". If you look at tc-taprio.8, it
> > uses
> > "\\" to render properly. If you don't mind, I'll do that here too.
> > 
> > > +.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>
> > > --
> > > 2.34.1
> > > 
> 
> Best,
> Peter

Best,
Ferenc

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Vladimir Oltean]

On Mon, Feb 20, 2023 at 05:01:57PM +0100, Péter Antal wrote:
> Hi Vladimir,
> 
> Vladimir Oltean <vladimir.oltean@nxp.com> ezt írta (időpont: 2023.
> febr. 20., H, 16:29):
> >
> > Hi Péter,
> >
> > On Mon, Feb 20, 2023 at 04:05:48PM +0100, Péter Antal wrote:
> > > 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>
> > > ---
> >
> > I think it's great that you are doing this. However, with all due respect,
> > this conflicts with the man page restructuring I am already doing for the
> > frame preemption work. Do you mind if I fix up some things and I pick your
> > patch up, and submit it as part of my series? I have some comments below.
> 
> That's all right, thank you for doing this, just please carry my
> signoff as co-developer if possible.

Absolutely, this is implied.

> I agree with most of your suggestions.

I've applied your changes on top of mine. Can you and Ferenc please
review the end result? I'll take a small break of a couple of hours,
and continue working on this when I come back.

$ cat man/man8/tc-mqprio.8
.TH MQPRIO 8 "24 Sept 2013" "iproute2" "Linux"
.SH NAME
MQPRIO \- Multiqueue Priority Qdisc (Offloaded Hardware QOS)
.SH SYNOPSIS
.B tc qdisc ... dev
dev (
.B parent
classid | root) [
.B handle
major: ]
.B mqprio
.ti +8
[
.B num_tc
tcs ] [
.B map
P0 P1 P2... ] [
.B queues
count1@offset1 count2@offset2 ... ]
.ti +8
[
.B hw
1|0 ] [
.B mode
dcb|channel ] [
.B shaper
dcb|bw_rlimit ]
.ti +8
[
.B min_rate
min_rate1 min_rate2 ... ] [
.B max_rate
max_rate1 max_rate2 ... ]
.ti +8
[
.B fp
FP0 FP1 FP2 ... ]

.SH DESCRIPTION
The MQPRIO qdisc is a simple queuing discipline that allows mapping
traffic flows to hardware queue ranges using priorities and a configurable
priority to traffic class mapping. A traffic class in this context is
a set of contiguous qdisc classes which map 1:1 to a set of hardware
exposed queues.

By default the qdisc allocates a pfifo qdisc (packet limited first in, first
out queue) per TX queue exposed by the lower layer device. Other queuing
disciplines may be added subsequently. Packets are enqueued using the
.B map
parameter and hashed across the indicated queues in the
.B offset
and
.B count.
By default these parameters are configured by the hardware
driver to match the hardware QOS structures.

.B Channel
mode supports full offload of the mqprio options, the traffic classes, the queue
configurations and QOS attributes to the hardware. Enabled hardware can provide
hardware QOS with the ability to steer traffic flows to designated traffic
classes provided by this qdisc. Hardware based QOS is configured using the
.B shaper
parameter.
.B bw_rlimit
with minimum and maximum bandwidth rates can be used for setting
transmission rates on each traffic class. Also further qdiscs may be added
to the classes of MQPRIO to create more complex configurations.

.SH ALGORITHM
On creation with 'tc qdisc add', eight traffic classes are created mapping
priorities 0..7 to traffic classes 0..7 and priorities greater than 7 to
traffic class 0. This requires base driver support and the creation will
fail on devices that do not support hardware QOS schemes.

These defaults can be overridden using the qdisc parameters. Providing
the 'hw 0' flag allows software to run without hardware coordination.

If hardware coordination is being used and arguments are provided that
the hardware can not support then an error is returned. For many users
hardware defaults should work reasonably well.

As one specific example numerous Ethernet cards support the 802.1Q
link strict priority transmission selection algorithm (TSA). MQPRIO
enabled hardware in conjunction with the classification methods below
can provide hardware offloaded support for this TSA.

.SH CLASSIFICATION
Multiple methods are available to set the SKB priority which MQPRIO
uses to select which traffic class to enqueue the packet.
.TP
From user space
A process with sufficient privileges can encode the destination class
directly with SO_PRIORITY, see
.BR socket(7).
.TP
with iptables/nftables
An iptables/nftables rule can be created to match traffic flows and
set the priority.
.BR iptables(8)
.TP
with net_prio cgroups
The net_prio cgroup can be used to set the priority of all sockets
belong to an application. See kernel and cgroup documentation for details.

.SH QDISC PARAMETERS
.TP
num_tc
Number of traffic classes to use. Up to 16 classes supported.
There cannot be more traffic classes than TX queues.

.TP
map
The priority to traffic class map. Maps priorities 0..15 to a specified
traffic class. The default value for this argument is

  ┌────┬────┐
  │Prio│ tc │
  ├────┼────┤
  │  0 │  0 │
  │  1 │  1 │
  │  2 │  2 │
  │  3 │  3 │
  │  4 │  4 │
  │  5 │  5 │
  │  6 │  6 │
  │  7 │  7 │
  │  8 │  0 │
  │  9 │  1 │
  │ 10 │  1 │
  │ 11 │  1 │
  │ 12 │  3 │
  │ 13 │  3 │
  │ 14 │  3 │
  │ 15 │  3 │
  └────┴────┘

.TP
queues
Provide count and offset of queue range for each traffic class. In the
format,
.B count@offset.
Without hardware coordination, queue ranges for each traffic classes cannot
overlap and must be a contiguous range of queues. With hardware coordination,
the device driver may apply a different queue configuration than requested,
and the requested queue configuration may overlap (but the one which is applied
may not). The default value for this argument is:

  ┌────┬───────┬────────┐
  │ tc │ count │ offset │
  ├────┼───────┼────────┤
  │  0 │    0  │    0   │
  │  1 │    0  │    0   │
  │  2 │    0  │    0   │
  │  3 │    0  │    0   │
  │  4 │    0  │    0   │
  │  5 │    0  │    0   │
  │  6 │    0  │    0   │
  │  7 │    0  │    0   │
  │  8 │    0  │    0   │
  │  9 │    0  │    0   │
  │ 10 │    0  │    0   │
  │ 11 │    0  │    0   │
  │ 12 │    0  │    0   │
  │ 13 │    0  │    0   │
  │ 14 │    0  │    0   │
  │ 15 │    0  │    0   │
  └────┴───────┴────────┘

.TP
hw
Set to
.B 1
to support hardware offload. Set to
.B 0
to configure user specified values in software only.
Without hardware coordination, the device driver is not notified of the number
of traffic classes and their mapping to TXQs. The device is not expected to
prioritize between traffic classes without hardware coordination.
The default value of this parameter is
.B 1.

.TP
mode
Set to
.B channel
for full use of the mqprio options. Use
.B dcb
to offload only TC values and use hardware QOS defaults. Supported with 'hw'
set to 1 only.

.TP
shaper
Use
.B bw_rlimit
to set bandwidth rate limits for a traffic class. Use
.B dcb
for hardware QOS defaults. Supported with 'hw' set to 1 only.

.TP
min_rate
Minimum value of bandwidth rate limit for a traffic class. Supported only when
the
.B 'shaper'
argument is set to
.B 'bw_rlimit'.

.TP
max_rate
Maximum value of bandwidth rate limit for a traffic class. Supported only when
the
.B 'shaper'
argument is set to
.B 'bw_rlimit'.

.TP
fp
Selects whether traffic classes are express (deliver packets via the eMAC) or
preemptible (deliver packets via the pMAC), according to IEEE 802.1Q-2018
clause 6.7.2 Frame preemption. Takes the form of an array (one element per
traffic class) with values being
.B 'E'
(for express) or
.B 'P'
(for preemptible).

Multiple priorities which map to the same traffic class, as well as multiple
TXQs which map to the same traffic class, must have the same FP attributes.
To interpret the FP as an attribute per priority, the
.B 'map'
argument can be used for translation. To interpret FP as an attribute per TXQ,
the
.B 'queues'
argument can be used for translation.

Traffic classes are express by default. The argument is supported only with
.B 'hw'
set to 1. Preemptible traffic classes are accepted only if the device has a MAC
Merge layer configurable through
.BR ethtool(8).

.SH SEE ALSO
.BR ethtool(8)

.SH EXAMPLE

The following example shows how to attach priorities to 4 traffic classes
('num_tc 4'), and how to pair these traffic classes with 4 hardware queues,
with hardware coordination ('hw 1'), according to the following configuration.

  ┌────┬────┬───────┐
  │Prio│ tc │ queue │
  ├────┼────┼───────┤
  │  0 │  0 │     0 │
  │  1 │  0 │     0 │
  │  2 │  0 │     0 │
  │  3 │  0 │     0 │
  │  4 │  1 │     1 │
  │  5 │  1 │     1 │
  │  6 │  1 │     1 │
  │  7 │  1 │     1 │
  │  8 │  2 │     2 │
  │  9 │  2 │     2 │
  │ 10 │  2 │     2 │
  │ 11 │  2 │     2 │
  │ 12 │  3 │     3 │
  │ 13 │  3 │     3 │
  │ 14 │  3 │     3 │
  │ 15 │  3 │     3 │
  └────┴────┴───────┘

Traffic class 0 (TC0) is mapped to hardware queue 0 (TXQ0), TC1 is mapped to
TXQ1, TC2 is mapped to TXQ2, and TC3 to TXQ3.

.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 following 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'), according to the following configuration:

  ┌────┬────┬────────┐
  │Prio│ tc │  queue │
  ├────┼────┼────────┤
  │  0 │  0 │      0 │
  │  1 │  0 │      0 │
  │  2 │  0 │      0 │
  │  3 │  0 │      0 │
  │  4 │  1 │      1 │
  │  5 │  1 │      1 │
  │  6 │  1 │      1 │
  │  7 │  1 │      1 │
  │  8 │  2 │ 2 or 3 │
  │  9 │  2 │ 2 or 3 │
  │ 10 │  2 │ 2 or 3 │
  │ 11 │  2 │ 2 or 3 │
  │ 12 │  2 │ 2 or 3 │
  │ 13 │  2 │ 2 or 3 │
  │ 14 │  2 │ 2 or 3 │
  │ 15 │  2 │ 2 or 3 │
  └────┴────┴────────┘

TC0 is mapped to hardware TXQ0, TC1 to TXQ1, and TC2 is mapped to TXQ2 and
TXQ3, where the queue selection between these two queues is arbitrary.

.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 the following example, there are 8 hardware queues mapped to 5 traffic
classes according to the configuration below:

        ┌───────┐
 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│
        └───────┘

.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


.SH AUTHORS
John Fastabend, <john.r.fastabend@intel.com>

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Ferenc Fejes]

Hi Vladimir!

On Mon, 2023-02-20 at 18:18 +0200, Vladimir Oltean wrote:
> On Mon, Feb 20, 2023 at 05:01:57PM +0100, Péter Antal wrote:
> > Hi Vladimir,
> > 
> > Vladimir Oltean <vladimir.oltean@nxp.com> ezt írta (időpont: 2023.
> > febr. 20., H, 16:29):
> > > 
> > > Hi Péter,
> > > 
> > > On Mon, Feb 20, 2023 at 04:05:48PM +0100, Péter Antal wrote:
> > > > 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>
> > > > ---
> > > 
> > > I think it's great that you are doing this. However, with all due
> > > respect,
> > > this conflicts with the man page restructuring I am already doing
> > > for the
> > > frame preemption work. Do you mind if I fix up some things and I
> > > pick your
> > > patch up, and submit it as part of my series? I have some
> > > comments below.
> > 
> > That's all right, thank you for doing this, just please carry my
> > signoff as co-developer if possible.
> 
> Absolutely, this is implied.
> 
> > I agree with most of your suggestions.
> 
> I've applied your changes on top of mine. Can you and Ferenc please
> review the end result? I'll take a small break of a couple of hours,
> and continue working on this when I come back.
> 
> $ cat man/man8/tc-mqprio.8
> .TH MQPRIO 8 "24 Sept 2013" "iproute2" "Linux"
> .SH NAME
> MQPRIO \- Multiqueue Priority Qdisc (Offloaded Hardware QOS)
> .SH SYNOPSIS
> .B tc qdisc ... dev
> dev (
> .B parent
> classid | root) [
> .B handle
> major: ]
> .B mqprio
> .ti +8
> [
> .B num_tc
> tcs ] [
> .B map
> P0 P1 P2... ] [
> .B queues
> count1@offset1 count2@offset2 ... ]
> .ti +8
> [
> .B hw
> 1|0 ] [
> .B mode
> dcb|channel ] [
> .B shaper
> dcb|bw_rlimit ]
> .ti +8
> [
> .B min_rate
> min_rate1 min_rate2 ... ] [
> .B max_rate
> max_rate1 max_rate2 ... ]
> .ti +8
> [
> .B fp
> FP0 FP1 FP2 ... ]
> 
> .SH DESCRIPTION
> The MQPRIO qdisc is a simple queuing discipline that allows mapping
> traffic flows to hardware queue ranges using priorities and a
> configurable
> priority to traffic class mapping. A traffic class in this context is
> a set of contiguous qdisc classes which map 1:1 to a set of hardware
> exposed queues.
> 
> By default the qdisc allocates a pfifo qdisc (packet limited first
> in, first
> out queue) per TX queue exposed by the lower layer device. Other
> queuing
> disciplines may be added subsequently. Packets are enqueued using the
> .B map
> parameter and hashed across the indicated queues in the
> .B offset
> and
> .B count.
> By default these parameters are configured by the hardware
> driver to match the hardware QOS structures.
> 
> .B Channel
> mode supports full offload of the mqprio options, the traffic
> classes, the queue
> configurations and QOS attributes to the hardware. Enabled hardware
> can provide
> hardware QOS with the ability to steer traffic flows to designated
> traffic
> classes provided by this qdisc. Hardware based QOS is configured
> using the
> .B shaper
> parameter.
> .B bw_rlimit
> with minimum and maximum bandwidth rates can be used for setting
> transmission rates on each traffic class. Also further qdiscs may be
> added
> to the classes of MQPRIO to create more complex configurations.
> 
> .SH ALGORITHM
> On creation with 'tc qdisc add', eight traffic classes are created
> mapping
> priorities 0..7 to traffic classes 0..7 and priorities greater than 7
> to
> traffic class 0. This requires base driver support and the creation
> will
> fail on devices that do not support hardware QOS schemes.
> 
> These defaults can be overridden using the qdisc parameters.
> Providing
> the 'hw 0' flag allows software to run without hardware coordination.
> 
> If hardware coordination is being used and arguments are provided
> that
> the hardware can not support then an error is returned. For many
> users
> hardware defaults should work reasonably well.
> 
> As one specific example numerous Ethernet cards support the 802.1Q
> link strict priority transmission selection algorithm (TSA). MQPRIO
> enabled hardware in conjunction with the classification methods below
> can provide hardware offloaded support for this TSA.
> 
> .SH CLASSIFICATION
> Multiple methods are available to set the SKB priority which MQPRIO
> uses to select which traffic class to enqueue the packet.
> .TP
> From user space
> A process with sufficient privileges can encode the destination class
> directly with SO_PRIORITY, see
> .BR socket(7).
> .TP
> with iptables/nftables
> An iptables/nftables rule can be created to match traffic flows and
> set the priority.
> .BR iptables(8)
> .TP
> with net_prio cgroups
> The net_prio cgroup can be used to set the priority of all sockets
> belong to an application. See kernel and cgroup documentation for
> details.
> 
> .SH QDISC PARAMETERS
> .TP
> num_tc
> Number of traffic classes to use. Up to 16 classes supported.
> There cannot be more traffic classes than TX queues.
> 
> .TP
> map
> The priority to traffic class map. Maps priorities 0..15 to a
> specified
> traffic class. The default value for this argument is
> 
>   ┌────┬────┐
>   │Prio│ tc │
>   ├────┼────┤
>   │  0 │  0 │
>   │  1 │  1 │
>   │  2 │  2 │
>   │  3 │  3 │
>   │  4 │  4 │
>   │  5 │  5 │
>   │  6 │  6 │
>   │  7 │  7 │
>   │  8 │  0 │
>   │  9 │  1 │
>   │ 10 │  1 │
>   │ 11 │  1 │
>   │ 12 │  3 │
>   │ 13 │  3 │
>   │ 14 │  3 │
>   │ 15 │  3 │
>   └────┴────┘
> 
> .TP
> queues
> Provide count and offset of queue range for each traffic class. In
> the
> format,
> .B count@offset.
> Without hardware coordination, queue ranges for each traffic classes
> cannot
> overlap and must be a contiguous range of queues. With hardware
> coordination,
> the device driver may apply a different queue configuration than
> requested,
> and the requested queue configuration may overlap (but the one which
> is applied
> may not). The default value for this argument is:
> 
>   ┌────┬───────┬────────┐
>   │ tc │ count │ offset │
>   ├────┼───────┼────────┤
>   │  0 │    0  │    0   │
>   │  1 │    0  │    0   │
>   │  2 │    0  │    0   │
>   │  3 │    0  │    0   │
>   │  4 │    0  │    0   │
>   │  5 │    0  │    0   │
>   │  6 │    0  │    0   │
>   │  7 │    0  │    0   │
>   │  8 │    0  │    0   │
>   │  9 │    0  │    0   │
>   │ 10 │    0  │    0   │
>   │ 11 │    0  │    0   │
>   │ 12 │    0  │    0   │
>   │ 13 │    0  │    0   │
>   │ 14 │    0  │    0   │
>   │ 15 │    0  │    0   │
>   └────┴───────┴────────┘
> 
> .TP
> hw
> Set to
> .B 1
> to support hardware offload. Set to
> .B 0
> to configure user specified values in software only.
> Without hardware coordination, the device driver is not notified of
> the number
> of traffic classes and their mapping to TXQs. The device is not
> expected to
> prioritize between traffic classes without hardware coordination.
> The default value of this parameter is
> .B 1.
> 
> .TP
> mode
> Set to
> .B channel
> for full use of the mqprio options. Use
> .B dcb
> to offload only TC values and use hardware QOS defaults. Supported
> with 'hw'
> set to 1 only.
> 
> .TP
> shaper
> Use
> .B bw_rlimit
> to set bandwidth rate limits for a traffic class. Use
> .B dcb
> for hardware QOS defaults. Supported with 'hw' set to 1 only.
> 
> .TP
> min_rate
> Minimum value of bandwidth rate limit for a traffic class. Supported
> only when
> the
> .B 'shaper'
> argument is set to
> .B 'bw_rlimit'.
> 
> .TP
> max_rate
> Maximum value of bandwidth rate limit for a traffic class. Supported
> only when
> the
> .B 'shaper'
> argument is set to
> .B 'bw_rlimit'.
> 
> .TP
> fp
> Selects whether traffic classes are express (deliver packets via the
> eMAC) or
> preemptible (deliver packets via the pMAC), according to IEEE 802.1Q-
> 2018
> clause 6.7.2 Frame preemption. Takes the form of an array (one
> element per
> traffic class) with values being
> .B 'E'
> (for express) or
> .B 'P'
> (for preemptible).
> 
> Multiple priorities which map to the same traffic class, as well as
> multiple
> TXQs which map to the same traffic class, must have the same FP
> attributes.
> To interpret the FP as an attribute per priority, the
> .B 'map'
> argument can be used for translation. To interpret FP as an attribute
> per TXQ,
> the
> .B 'queues'
> argument can be used for translation.
> 
> Traffic classes are express by default. The argument is supported
> only with
> .B 'hw'
> set to 1. Preemptible traffic classes are accepted only if the device
> has a MAC
> Merge layer configurable through
> .BR ethtool(8).
> 
> .SH SEE ALSO
> .BR ethtool(8)
> 
> .SH EXAMPLE
> 
> The following example shows how to attach priorities to 4 traffic
> classes
> ('num_tc 4'), and how to pair these traffic classes with 4 hardware
> queues,
> with hardware coordination ('hw 1'), according to the following
> configuration.
> 
>   ┌────┬────┬───────┐
>   │Prio│ tc │ queue │
>   ├────┼────┼───────┤
>   │  0 │  0 │     0 │
>   │  1 │  0 │     0 │
>   │  2 │  0 │     0 │
>   │  3 │  0 │     0 │
>   │  4 │  1 │     1 │
>   │  5 │  1 │     1 │
>   │  6 │  1 │     1 │
>   │  7 │  1 │     1 │
>   │  8 │  2 │     2 │
>   │  9 │  2 │     2 │
>   │ 10 │  2 │     2 │
>   │ 11 │  2 │     2 │
>   │ 12 │  3 │     3 │
>   │ 13 │  3 │     3 │
>   │ 14 │  3 │     3 │
>   │ 15 │  3 │     3 │
>   └────┴────┴───────┘
> 
> Traffic class 0 (TC0) is mapped to hardware queue 0 (TXQ0), TC1 is
> mapped to
> TXQ1, TC2 is mapped to TXQ2, and TC3 to TXQ3.
> 
> .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 following 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'), according to the following
> configuration:
> 
>   ┌────┬────┬────────┐
>   │Prio│ tc │  queue │
>   ├────┼────┼────────┤
>   │  0 │  0 │      0 │
>   │  1 │  0 │      0 │
>   │  2 │  0 │      0 │
>   │  3 │  0 │      0 │
>   │  4 │  1 │      1 │
>   │  5 │  1 │      1 │
>   │  6 │  1 │      1 │
>   │  7 │  1 │      1 │
>   │  8 │  2 │ 2 or 3 │
>   │  9 │  2 │ 2 or 3 │
>   │ 10 │  2 │ 2 or 3 │
>   │ 11 │  2 │ 2 or 3 │
>   │ 12 │  2 │ 2 or 3 │
>   │ 13 │  2 │ 2 or 3 │
>   │ 14 │  2 │ 2 or 3 │
>   │ 15 │  2 │ 2 or 3 │
>   └────┴────┴────────┘
> 
> TC0 is mapped to hardware TXQ0, TC1 to TXQ1, and TC2 is mapped to
> TXQ2 and
> TXQ3, where the queue selection between these two queues is
> arbitrary.
> 
> .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 the following example, there are 8 hardware queues mapped to 5
> traffic
> classes according to the configuration below:
> 
>         ┌───────┐
>  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│
>         └───────┘
> 
> .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
> 
> 
> .SH AUTHORS
> John Fastabend, <john.r.fastabend@intel.com>

LGTM!

Acked-by: Ferenc Fejes <fejes@inf.elte.hu>

Thank you!
Ferenc

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[Péter Antal]

Hi

Vladimir Oltean <vladimir.oltean@nxp.com> ezt írta (időpont: 2023.
febr. 20., H, 17:18):
>
> On Mon, Feb 20, 2023 at 05:01:57PM +0100, Péter Antal wrote:
> > Hi Vladimir,
> >
> > Vladimir Oltean <vladimir.oltean@nxp.com> ezt írta (időpont: 2023.
> > febr. 20., H, 16:29):
> > >
> > > Hi Péter,
> > >
> > > On Mon, Feb 20, 2023 at 04:05:48PM +0100, Péter Antal wrote:
> > > > 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>
> > > > ---
> > >
> > > I think it's great that you are doing this. However, with all due respect,
> > > this conflicts with the man page restructuring I am already doing for the
> > > frame preemption work. Do you mind if I fix up some things and I pick your
> > > patch up, and submit it as part of my series? I have some comments below.
> >
> > That's all right, thank you for doing this, just please carry my
> > signoff as co-developer if possible.
>
> Absolutely, this is implied.
>
> > I agree with most of your suggestions.
>
> I've applied your changes on top of mine. Can you and Ferenc please
> review the end result? I'll take a small break of a couple of hours,
> and continue working on this when I come back.
>
> $ cat man/man8/tc-mqprio.8
> .TH MQPRIO 8 "24 Sept 2013" "iproute2" "Linux"
> .SH NAME
> MQPRIO \- Multiqueue Priority Qdisc (Offloaded Hardware QOS)
> .SH SYNOPSIS
> .B tc qdisc ... dev
> dev (
> .B parent
> classid | root) [
> .B handle
> major: ]
> .B mqprio
> .ti +8
> [
> .B num_tc
> tcs ] [
> .B map
> P0 P1 P2... ] [
> .B queues
> count1@offset1 count2@offset2 ... ]
> .ti +8
> [
> .B hw
> 1|0 ] [
> .B mode
> dcb|channel ] [
> .B shaper
> dcb|bw_rlimit ]
> .ti +8
> [
> .B min_rate
> min_rate1 min_rate2 ... ] [
> .B max_rate
> max_rate1 max_rate2 ... ]
> .ti +8
> [
> .B fp
> FP0 FP1 FP2 ... ]
>
> .SH DESCRIPTION
> The MQPRIO qdisc is a simple queuing discipline that allows mapping
> traffic flows to hardware queue ranges using priorities and a configurable
> priority to traffic class mapping. A traffic class in this context is
> a set of contiguous qdisc classes which map 1:1 to a set of hardware
> exposed queues.
>
> By default the qdisc allocates a pfifo qdisc (packet limited first in, first
> out queue) per TX queue exposed by the lower layer device. Other queuing
> disciplines may be added subsequently. Packets are enqueued using the
> .B map
> parameter and hashed across the indicated queues in the
> .B offset
> and
> .B count.
> By default these parameters are configured by the hardware
> driver to match the hardware QOS structures.
>
> .B Channel
> mode supports full offload of the mqprio options, the traffic classes, the queue
> configurations and QOS attributes to the hardware. Enabled hardware can provide
> hardware QOS with the ability to steer traffic flows to designated traffic
> classes provided by this qdisc. Hardware based QOS is configured using the
> .B shaper
> parameter.
> .B bw_rlimit
> with minimum and maximum bandwidth rates can be used for setting
> transmission rates on each traffic class. Also further qdiscs may be added
> to the classes of MQPRIO to create more complex configurations.
>
> .SH ALGORITHM
> On creation with 'tc qdisc add', eight traffic classes are created mapping
> priorities 0..7 to traffic classes 0..7 and priorities greater than 7 to
> traffic class 0. This requires base driver support and the creation will
> fail on devices that do not support hardware QOS schemes.
>
> These defaults can be overridden using the qdisc parameters. Providing
> the 'hw 0' flag allows software to run without hardware coordination.
>
> If hardware coordination is being used and arguments are provided that
> the hardware can not support then an error is returned. For many users
> hardware defaults should work reasonably well.
>
> As one specific example numerous Ethernet cards support the 802.1Q
> link strict priority transmission selection algorithm (TSA). MQPRIO
> enabled hardware in conjunction with the classification methods below
> can provide hardware offloaded support for this TSA.
>
> .SH CLASSIFICATION
> Multiple methods are available to set the SKB priority which MQPRIO
> uses to select which traffic class to enqueue the packet.
> .TP
> From user space
> A process with sufficient privileges can encode the destination class
> directly with SO_PRIORITY, see
> .BR socket(7).
> .TP
> with iptables/nftables
> An iptables/nftables rule can be created to match traffic flows and
> set the priority.
> .BR iptables(8)
> .TP
> with net_prio cgroups
> The net_prio cgroup can be used to set the priority of all sockets
> belong to an application. See kernel and cgroup documentation for details.
>
> .SH QDISC PARAMETERS
> .TP
> num_tc
> Number of traffic classes to use. Up to 16 classes supported.
> There cannot be more traffic classes than TX queues.
>
> .TP
> map
> The priority to traffic class map. Maps priorities 0..15 to a specified
> traffic class. The default value for this argument is
>
>   ┌────┬────┐
>   │Prio│ tc │
>   ├────┼────┤
>   │  0 │  0 │
>   │  1 │  1 │
>   │  2 │  2 │
>   │  3 │  3 │
>   │  4 │  4 │
>   │  5 │  5 │
>   │  6 │  6 │
>   │  7 │  7 │
>   │  8 │  0 │
>   │  9 │  1 │
>   │ 10 │  1 │
>   │ 11 │  1 │
>   │ 12 │  3 │
>   │ 13 │  3 │
>   │ 14 │  3 │
>   │ 15 │  3 │
>   └────┴────┘
>
> .TP
> queues
> Provide count and offset of queue range for each traffic class. In the
> format,
> .B count@offset.
> Without hardware coordination, queue ranges for each traffic classes cannot
> overlap and must be a contiguous range of queues. With hardware coordination,
> the device driver may apply a different queue configuration than requested,
> and the requested queue configuration may overlap (but the one which is applied
> may not). The default value for this argument is:
>
>   ┌────┬───────┬────────┐
>   │ tc │ count │ offset │
>   ├────┼───────┼────────┤
>   │  0 │    0  │    0   │
>   │  1 │    0  │    0   │
>   │  2 │    0  │    0   │
>   │  3 │    0  │    0   │
>   │  4 │    0  │    0   │
>   │  5 │    0  │    0   │
>   │  6 │    0  │    0   │
>   │  7 │    0  │    0   │
>   │  8 │    0  │    0   │
>   │  9 │    0  │    0   │
>   │ 10 │    0  │    0   │
>   │ 11 │    0  │    0   │
>   │ 12 │    0  │    0   │
>   │ 13 │    0  │    0   │
>   │ 14 │    0  │    0   │
>   │ 15 │    0  │    0   │
>   └────┴───────┴────────┘
>

Maybe this default table is obvious, and stating that "by default the
traffic classes are mapped to 0@0" could be enough.
But feel free to ignore this.

> .TP
> hw
> Set to
> .B 1
> to support hardware offload. Set to
> .B 0
> to configure user specified values in software only.
> Without hardware coordination, the device driver is not notified of the number
> of traffic classes and their mapping to TXQs. The device is not expected to
> prioritize between traffic classes without hardware coordination.
> The default value of this parameter is
> .B 1.
>
> .TP
> mode
> Set to
> .B channel
> for full use of the mqprio options. Use
> .B dcb
> to offload only TC values and use hardware QOS defaults. Supported with 'hw'
> set to 1 only.
>
> .TP
> shaper
> Use
> .B bw_rlimit
> to set bandwidth rate limits for a traffic class. Use
> .B dcb
> for hardware QOS defaults. Supported with 'hw' set to 1 only.
>
> .TP
> min_rate
> Minimum value of bandwidth rate limit for a traffic class. Supported only when
> the
> .B 'shaper'
> argument is set to
> .B 'bw_rlimit'.
>
> .TP
> max_rate
> Maximum value of bandwidth rate limit for a traffic class. Supported only when
> the
> .B 'shaper'
> argument is set to
> .B 'bw_rlimit'.
>
> .TP
> fp
> Selects whether traffic classes are express (deliver packets via the eMAC) or
> preemptible (deliver packets via the pMAC), according to IEEE 802.1Q-2018
> clause 6.7.2 Frame preemption. Takes the form of an array (one element per
> traffic class) with values being
> .B 'E'
> (for express) or
> .B 'P'
> (for preemptible).
>
> Multiple priorities which map to the same traffic class, as well as multiple
> TXQs which map to the same traffic class, must have the same FP attributes.
> To interpret the FP as an attribute per priority, the
> .B 'map'
> argument can be used for translation. To interpret FP as an attribute per TXQ,
> the
> .B 'queues'
> argument can be used for translation.
>
> Traffic classes are express by default. The argument is supported only with
> .B 'hw'
> set to 1. Preemptible traffic classes are accepted only if the device has a MAC
> Merge layer configurable through
> .BR ethtool(8).
>
> .SH SEE ALSO
> .BR ethtool(8)
>
> .SH EXAMPLE
>
> The following example shows how to attach priorities to 4 traffic classes
> ('num_tc 4'), and how to pair these traffic classes with 4 hardware queues,
> with hardware coordination ('hw 1'), according to the following configuration.
>
>   ┌────┬────┬───────┐
>   │Prio│ tc │ queue │
>   ├────┼────┼───────┤
>   │  0 │  0 │     0 │
>   │  1 │  0 │     0 │
>   │  2 │  0 │     0 │
>   │  3 │  0 │     0 │
>   │  4 │  1 │     1 │
>   │  5 │  1 │     1 │
>   │  6 │  1 │     1 │
>   │  7 │  1 │     1 │
>   │  8 │  2 │     2 │
>   │  9 │  2 │     2 │
>   │ 10 │  2 │     2 │
>   │ 11 │  2 │     2 │
>   │ 12 │  3 │     3 │
>   │ 13 │  3 │     3 │
>   │ 14 │  3 │     3 │
>   │ 15 │  3 │     3 │
>   └────┴────┴───────┘
>
> Traffic class 0 (TC0) is mapped to hardware queue 0 (TXQ0), TC1 is mapped to
> TXQ1, TC2 is mapped to TXQ2, and TC3 to TXQ3.
>
> .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 following 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'), according to the following configuration:
>
>   ┌────┬────┬────────┐
>   │Prio│ tc │  queue │
>   ├────┼────┼────────┤
>   │  0 │  0 │      0 │
>   │  1 │  0 │      0 │
>   │  2 │  0 │      0 │
>   │  3 │  0 │      0 │
>   │  4 │  1 │      1 │
>   │  5 │  1 │      1 │
>   │  6 │  1 │      1 │
>   │  7 │  1 │      1 │
>   │  8 │  2 │ 2 or 3 │
>   │  9 │  2 │ 2 or 3 │
>   │ 10 │  2 │ 2 or 3 │
>   │ 11 │  2 │ 2 or 3 │
>   │ 12 │  2 │ 2 or 3 │
>   │ 13 │  2 │ 2 or 3 │
>   │ 14 │  2 │ 2 or 3 │
>   │ 15 │  2 │ 2 or 3 │
>   └────┴────┴────────┘
>
> TC0 is mapped to hardware TXQ0, TC1 to TXQ1, and TC2 is mapped to TXQ2 and
> TXQ3, where the queue selection between these two queues is arbitrary.
>
> .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 the following example, there are 8 hardware queues mapped to 5 traffic
> classes according to the configuration below:
>
>         ┌───────┐
>  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│
>         └───────┘
>
> .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
>
>
> .SH AUTHORS
> John Fastabend, <john.r.fastabend@intel.com>

Aside from that LGTM!

Acked-by: Péter Antal <peti.antal99@gmail.com>

Thanks!
Péter

Re: [PATCH iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples

[patchwork-bot+netdevbpf]

Hello:

This patch was applied to iproute2/iproute2.git (main)
by Stephen Hemminger <stephen@networkplumber.org>:

On Mon, 20 Feb 2023 16:05:48 +0100 you wrote:
> 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>
> ---
>  man/man8/tc-mqprio.8 | 96 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 96 insertions(+)

Here is the summary with links:
  - [iproute2] man: tc-mqprio: extend prio-tc-queue mapping with examples
    https://git.kernel.org/pub/scm/network/iproute2/iproute2.git/commit/?id=ce4068f22db4

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html