Debian Codegraph @

upstream/debian-unstable/man8/tc-mqprio.8

raw
1 .TH MQPRIO 8 "24 Sept 2013" "iproute2" "Linux"
2 .SH NAME
3 MQPRIO \- Multiqueue Priority Qdisc (Offloaded Hardware QOS)
4 .SH SYNOPSIS
5 .B tc qdisc ... dev
6 dev (
7 .B parent
8 classid | root) [
9 .B handle
10 major: ]
11 .B mqprio
12 .ti +8
13 [
14 .B num_tc
15 tcs ] [
16 .B map
17 P0 P1 P2... ] [
18 .B queues
19 count1@offset1 count2@offset2 ... ]
20 .ti +8
21 [
22 .B hw
23 1|0 ] [
24 .B mode
25 dcb|channel ] [
26 .B shaper
27 dcb|bw_rlimit ]
28 .ti +8
29 [
30 .B min_rate
31 min_rate1 min_rate2 ... ] [
32 .B max_rate
33 max_rate1 max_rate2 ... ]
34 .ti +8
35 [
36 .B fp
37 FP0 FP1 FP2 ... ]
38
39 .SH DESCRIPTION
40 The MQPRIO qdisc is a simple queuing discipline that allows mapping
41 traffic flows to hardware queue ranges using priorities and a configurable
42 priority to traffic class mapping. A traffic class in this context is
43 a set of contiguous qdisc classes which map 1:1 to a set of hardware
44 exposed queues.
45
46 By default the qdisc allocates a pfifo qdisc (packet limited first in, first
47 out queue) per TX queue exposed by the lower layer device. Other queuing
48 disciplines may be added subsequently. Packets are enqueued using the
49 .B map
50 parameter and hashed across the indicated queues in the
51 .B offset
52 and
53 .B count.
54 By default these parameters are configured by the hardware
55 driver to match the hardware QOS structures.
56
57 .B Channel
58 mode supports full offload of the mqprio options, the traffic classes, the queue
59 configurations and QOS attributes to the hardware. Enabled hardware can provide
60 hardware QOS with the ability to steer traffic flows to designated traffic
61 classes provided by this qdisc. Hardware based QOS is configured using the
62 .B shaper
63 parameter.
64 .B bw_rlimit
65 with minimum and maximum bandwidth rates can be used for setting
66 transmission rates on each traffic class. Also further qdiscs may be added
67 to the classes of MQPRIO to create more complex configurations.
68
69 .SH ALGORITHM
70 On creation with 'tc qdisc add', eight traffic classes are created mapping
71 priorities 0..7 to traffic classes 0..7 and priorities greater than 7 to
72 traffic class 0. This requires base driver support and the creation will
73 fail on devices that do not support hardware QOS schemes.
74
75 These defaults can be overridden using the qdisc parameters. Providing
76 the 'hw 0' flag allows software to run without hardware coordination.
77
78 If hardware coordination is being used and arguments are provided that
79 the hardware can not support then an error is returned. For many users
80 hardware defaults should work reasonably well.
81
82 As one specific example numerous Ethernet cards support the 802.1Q
83 link strict priority transmission selection algorithm (TSA). MQPRIO
84 enabled hardware in conjunction with the classification methods below
85 can provide hardware offloaded support for this TSA.
86
87 .SH CLASSIFICATION
88 Multiple methods are available to set the SKB priority which MQPRIO
89 uses to select which traffic class to enqueue the packet.
90 .TP
91 From user space
92 A process with sufficient privileges can encode the destination class
93 directly with SO_PRIORITY, see
94 .BR socket(7).
95 .TP
96 with iptables/nftables
97 An iptables/nftables rule can be created to match traffic flows and
98 set the priority.
99 .BR iptables(8)
100 .TP
101 with net_prio cgroups
102 The net_prio cgroup can be used to set the priority of all sockets
103 belong to an application. See kernel and cgroup documentation for details.
104
105 .SH QDISC PARAMETERS
106 .TP
107 num_tc
108 Number of traffic classes to use. Up to 16 classes supported.
109 You cannot have more classes than queues
110
111 .TP
112 map
113 The priority to traffic class map. Maps priorities 0..15 to a specified
114 traffic class.
115
116 .TP
117 queues
118 Provide count and offset of queue range for each traffic class. In the
119 format,
120 .B count@offset.
121 Queue ranges for each traffic classes cannot overlap and must be a
122 contiguous range of queues.
123
124 .TP
125 hw
126 Set to
127 .B 1
128 to support hardware offload. Set to
129 .B 0
130 to configure user specified values in software only.
131 The default value of this parameter is
132 .B 1
133
134 .TP
135 mode
136 Set to
137 .B channel
138 for full use of the mqprio options. Use
139 .B dcb
140 to offload only TC values and use hardware QOS defaults. Supported with 'hw'
141 set to 1 only.
142
143 .TP
144 shaper
145 Use
146 .B bw_rlimit
147 to set bandwidth rate limits for a traffic class. Use
148 .B dcb
149 for hardware QOS defaults. Supported with 'hw' set to 1 only.
150
151 .TP
152 min_rate
153 Minimum value of bandwidth rate limit for a traffic class. Supported only when
154 the
155 .B 'shaper'
156 argument is set to
157 .B 'bw_rlimit'.
158
159 .TP
160 max_rate
161 Maximum value of bandwidth rate limit for a traffic class. Supported only when
162 the
163 .B 'shaper'
164 argument is set to
165 .B 'bw_rlimit'.
166
167 .TP
168 fp
169 Selects whether traffic classes are express (deliver packets via the eMAC) or
170 preemptible (deliver packets via the pMAC), according to IEEE 802.1Q-2018
171 clause 6.7.2 Frame preemption. Takes the form of an array (one element per
172 traffic class) with values being
173 .B 'E'
174 (for express) or
175 .B 'P'
176 (for preemptible).
177
178 Multiple priorities which map to the same traffic class, as well as multiple
179 TXQs which map to the same traffic class, must have the same FP attributes.
180 To interpret the FP as an attribute per priority, the
181 .B 'map'
182 argument can be used for translation. To interpret FP as an attribute per TXQ,
183 the
184 .B 'queues'
185 argument can be used for translation.
186
187 Traffic classes are express by default. The argument is supported only with
188 .B 'hw'
189 set to 1. Preemptible traffic classes are accepted only if the device has a MAC
190 Merge layer configurable through
191 .BR ethtool(8).
192
193 .SH SEE ALSO
194 .BR ethtool(8)
195
196 .SH EXAMPLE
197
198 The following example shows how to attach priorities to 4 traffic classes ("num_tc 4"),
199 and then how to pair these traffic classes with 4 hardware queues with mqprio,
200 with hardware coordination ("hw 1", or does not specified, because 1 is the default value).
201 Traffic class 0 (tc0) is mapped to hardware queue 0 (q0), tc1 is mapped to q1,
202 tc2 is mapped to q2, and tc3 is mapped q3.
203
204 .EX
205 # tc qdisc add dev eth0 root mqprio \
206 num_tc 4 \
207 map 0 0 0 0 1 1 1 1 2 2 2 2 3 3 3 3 \
208 queues 1@0 1@1 1@2 1@3 \
209 hw 1
210 .EE
211
212 The next example shows how to attach priorities to 3 traffic classes ("num_tc 3"),
213 and how to pair these traffic classes with 4 queues,
214 without hardware coordination ("hw 0").
215 Traffic class 0 (tc0) is mapped to hardware queue 0 (q0), tc1 is mapped to q1,
216 tc2 and is mapped to q2 and q3, where the queue selection between these
217 two queues is somewhat randomly decided.
218
219 .EX
220 # tc qdisc add dev eth0 root mqprio \
221 num_tc 3 \
222 map 0 0 0 0 1 1 1 1 2 2 2 2 2 2 2 2 \
223 queues 1@0 1@1 2@2 \
224 hw 0
225 .EE
226
227
228 In both cases from above the priority values from 0 to 3 (prio0-3) are
229 mapped to tc0, prio4-7 are mapped to tc1, and the
230 prio8-11 are mapped to tc2 ("map" attribute). The last four priority values
231 (prio12-15) are mapped in different ways in the two examples.
232 They are mapped to tc3 in the first example and mapped to tc2 in the second example.
233 The values of these two examples are the following:
234
235 ┌────┬────┬───────┐ ┌────┬────┬────────┐
236 │Prio│ tc │ queue │ │Prio│ tc │ queue │
237 ├────┼────┼───────┤ ├────┼────┼────────┤
238 │ 0 │ 0 │ 0 │ │ 0 │ 0 │ 0 │
239 │ 1 │ 0 │ 0 │ │ 1 │ 0 │ 0 │
240 │ 2 │ 0 │ 0 │ │ 2 │ 0 │ 0 │
241 │ 3 │ 0 │ 0 │ │ 3 │ 0 │ 0 │
242 │ 4 │ 1 │ 1 │ │ 4 │ 1 │ 1 │
243 │ 5 │ 1 │ 1 │ │ 5 │ 1 │ 1 │
244 │ 6 │ 1 │ 1 │ │ 6 │ 1 │ 1 │
245 │ 7 │ 1 │ 1 │ │ 7 │ 1 │ 1 │
246 │ 8 │ 2 │ 2 │ │ 8 │ 2 │ 2 or 3 │
247 │ 9 │ 2 │ 2 │ │ 9 │ 2 │ 2 or 3 │
248 │ 10 │ 2 │ 2 │ │ 10 │ 2 │ 2 or 3 │
249 │ 11 │ 2 │ 2 │ │ 11 │ 2 │ 2 or 3 │
250 │ 12 │ 3 │ 3 │ │ 12 │ 2 │ 2 or 3 │
251 │ 13 │ 3 │ 3 │ │ 13 │ 2 │ 2 or 3 │
252 │ 14 │ 3 │ 3 │ │ 14 │ 2 │ 2 or 3 │
253 │ 15 │ 3 │ 3 │ │ 15 │ 2 │ 2 or 3 │
254 └────┴────┴───────┘ └────┴────┴────────┘
255 example1 example2
256
257
258 Another example of queue mapping is the following.
259 There are 5 traffic classes, and there are 8 hardware queues.
260
261 .EX
262 # tc qdisc add dev eth0 root mqprio \
263 num_tc 5 \
264 map 0 0 0 1 1 1 1 2 2 3 3 4 4 4 4 4 \
265 queues 1@0 2@1 1@3 1@4 3@5
266 .EE
267
268 The value mapping is the following for this example:
269
270 ┌───────┐
271 tc0────┤Queue 0│◄────1@0
272 ├───────┤
273 ┌─┤Queue 1│◄────2@1
274 tc1──┤ ├───────┤
275 └─┤Queue 2│
276 ├───────┤
277 tc2────┤Queue 3│◄────1@3
278 ├───────┤
279 tc3────┤Queue 4│◄────1@4
280 ├───────┤
281 ┌─┤Queue 5│◄────3@5
282 │ ├───────┤
283 tc4──┼─┤Queue 6│
284 │ ├───────┤
285 └─┤Queue 7│
286 └───────┘
287
288
289 .SH AUTHORS
290 John Fastabend, <[email protected]>