Debian Codegraph @

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

raw
1 .TH TAPRIO 8 "25 Sept 2018" "iproute2" "Linux"
2 .SH NAME
3 TAPRIO \- Time Aware Priority Shaper
4 .SH SYNOPSIS
5 .B tc qdisc ... dev
6 dev
7 .B parent
8 classid
9 .B [ handle
10 major:
11 .B ] taprio num_tc
12 tcs
13 .ti +8
14 .B map
15 P0 P1 P2 ...
16 .B queues
17 count1@offset1 count2@offset2 ...
18 .ti +8
19 .B base-time
20 base-time
21 .B clockid
22 clockid
23 .ti +8
24 .B sched-entry
25 <command 1> <gate mask 1> <interval 1>
26 .ti +8
27 .B sched-entry
28 <command 2> <gate mask 2> <interval 2>
29 .ti +8
30 .B sched-entry
31 <command 3> <gate mask 3> <interval 3>
32 .ti +8
33 .B sched-entry
34 <command N> <gate mask N> <interval N>
35 .ti +8
36 [
37 .B max-sdu
38 <queueMaxSDU[TC 0]> <queueMaxSDU[TC 1]> <queueMaxSDU[TC N]> ]
39 .ti +8
40 [
41 .B fp
42 <adminStatus[TC 0]> <adminStatus[TC 1]> <adminStatus[TC N]> ]
43
44 .SH DESCRIPTION
45 The TAPRIO qdisc implements a simplified version of the scheduling
46 state machine defined by IEEE 802.1Q-2018 Section 8.6.9, which allows
47 configuration of a sequence of gate states, where each gate state
48 allows outgoing traffic for a subset (potentially empty) of traffic
49 classes.
50
51 How traffic is mapped to different hardware queues is similar to
52 .BR mqprio(8)
53 and so the
54 .B map
55 and
56 .B queues
57 parameters have the same meaning.
58
59 The other parameters specify the schedule, and at what point in time
60 it should start (it can behave as the schedule started in the past).
61
62 .SH PARAMETERS
63 .TP
64 num_tc
65 .BR
66 Number of traffic classes to use. Up to 16 classes supported.
67
68 .TP
69 map
70 .br
71 The priority to traffic class map. Maps priorities 0..15 to a specified
72 traffic class. See
73 .BR mqprio(8)
74 for more details.
75
76 .TP
77 queues
78 .br
79 Provide count and offset of queue range for each traffic class. In the
80 format,
81 .B count@offset.
82 Queue ranges for each traffic classes cannot overlap and must be a
83 contiguous range of queues.
84
85 .TP
86 base-time
87 .br
88 Specifies the instant in nanoseconds, using the reference of
89 .B clockid,
90 defining the time when the schedule starts. If 'base-time' is a time
91 in the past, the schedule will start at
92
93 base-time + (N * cycle-time)
94
95 where N is the smallest integer so the resulting time is greater than
96 "now", and "cycle-time" is the sum of all the intervals of the entries
97 in the schedule;
98
99 .TP
100 clockid
101 .br
102 Specifies the clock to be used by qdisc's internal timer for measuring
103 time and scheduling events. This argument must be omitted when using the
104 full-offload feature (flags 0x2), since in that case, the clockid is
105 implicitly /dev/ptpN (where N is given by
106 .B ethtool -T eth0 | grep 'PTP Hardware Clock'
107 ), and therefore not necessarily synchronized with the system's CLOCK_TAI.
108
109 .TP
110 sched-entry
111 .br
112 There may multiple
113 .B sched-entry
114 parameters in a single schedule. Each one has the
115
116 sched-entry <command> <gatemask> <interval>
117
118 format.
119
120 <command> support the following values:
121 .br
122 .I "S"
123 for SetGateStates
124 .br
125 .I "H"
126 for Set-And-Hold-MAC
127 .br
128 .I "R"
129 for Set-And-Release-MAC
130 .br
131 These commands follow the IEEE 802.1Q-2018 definition (Table 8-7).
132
133 <gate mask> is a bitmask where each bit is associated with a traffic class, so
134 bit 0 (the least significant bit) being "on" means that traffic class 0 is
135 "active" for that schedule entry.
136
137 <interval> is a time duration, in nanoseconds, that specifies for how long that
138 state defined by <command> and <gate mask> should be held before moving to
139 the next entry.
140
141 .TP
142 flags
143 .br
144 This is a bit mask which specifies different modes for taprio.
145 .RS
146 .TP
147 .I 0x1
148 Enables the txtime-assist feature. In this mode, taprio will set the transmit
149 timestamp depending on the interval in which the packet needs to be
150 transmitted. It will then utililize the
151 .BR etf(8)
152 qdisc to sort and transmit the packets at the right time. The second example
153 can be used as a reference to configure this mode.
154 .TP
155 .I 0x2
156 Enables the full-offload feature. In this mode, taprio will pass the gate
157 control list to the NIC which will execute it cyclically in hardware.
158 When using full-offload, there is no need to specify the
159 .B clockid
160 argument.
161
162 The txtime-assist and full-offload features are mutually exclusive, i.e.
163 setting flags to 0x3 is invalid.
164 .RE
165
166 .TP
167 txtime-delay
168 .br
169 This parameter is specific to the txtime offload mode. It specifies the maximum
170 time a packet might take to reach the network card from the taprio qdisc. The
171 value should always be greater than the delta specified in the
172 .BR etf(8)
173 qdisc.
174
175 .TP
176 max-sdu
177 .br
178 Specifies an array containing at most 16 elements, one per traffic class, which
179 corresponds to the queueMaxSDU table from IEEE 802.1Q-2018. Each array element
180 represents the maximum L2 payload size that can egress that traffic class.
181 Elements that are not filled in default to 0. The value 0 means that the
182 traffic class can send packets up to the port's maximum MTU in size.
183
184 .TP
185 fp
186 .br
187 Selects whether traffic classes are express or preemptible. See
188 .BR tc-mqprio(8)
189 for details.
190
191 .SH EXAMPLES
192
193 The following example shows how an traffic schedule with three traffic
194 classes ("num_tc 3"), which are separated different traffic classes,
195 we are going to call these TC 0, TC 1 and TC 2. We could read the
196 "map" parameter below as: traffic with priority 3 is classified as TC
197 0, priority 2 is classified as TC 1 and the rest is classified as TC
198 2.
199
200 The schedule will start at instant 1528743495910289987 using the
201 reference CLOCK_TAI. The schedule is composed of three entries each of
202 300us duration.
203
204 .EX
205 # tc qdisc replace dev eth0 parent root handle 100 stab overhead 24 taprio \\
206 num_tc 3 \\
207 map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \\
208 queues 1@0 1@1 2@2 \\
209 base-time 1528743495910289987 \\
210 sched-entry S 01 300000 \\
211 sched-entry S 02 300000 \\
212 sched-entry S 04 300000 \\
213 clockid CLOCK_TAI
214 .EE
215
216 Following is an example to enable the txtime offload mode in taprio. See
217 .BR etf(8)
218 for more information about configuring the ETF qdisc.
219
220 .EX
221 # tc qdisc replace dev eth0 parent root handle 100 stab overhead 24 taprio \\
222 num_tc 3 \\
223 map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \\
224 queues 1@0 1@0 1@0 \\
225 base-time 1528743495910289987 \\
226 sched-entry S 01 300000 \\
227 sched-entry S 02 300000 \\
228 sched-entry S 04 400000 \\
229 flags 0x1 \\
230 txtime-delay 200000 \\
231 clockid CLOCK_TAI
232
233 # tc qdisc replace dev $IFACE parent 100:1 etf skip_skb_check \\
234 offload delta 200000 clockid CLOCK_TAI
235 .EE
236
237 The following is a schedule in full offload mode. The
238 .B base-time
239 is 200 ns and the
240 .B cycle-time
241 is implicitly calculated as the sum of all
242 .B sched-entry
243 durations (i.e. 20 us + 20 us + 60 us = 100 us). Although the base-time is in
244 the past, the hardware will start executing the schedule at a PTP time equal to
245 the smallest integer multiple of 100 us, plus 200 ns, that is larger than the
246 NIC's current PTP time. In addition, the MTU for traffic class 5 is limited to
247 200 octets, so that the interference this creates upon traffic class 7 during
248 the time window when their gates are both open is bounded. The interference is
249 determined by the transmit time of the max SDU, plus the L2 header length, plus
250 the L1 overhead (determined from the size table specified using
251 .BR tc-stab(8)).
252
253 .EX
254 # tc qdisc add dev eth0 parent root stab overhead 24 taprio \\
255 num_tc 8 \\
256 map 0 1 2 3 4 5 6 7 \\
257 queues 1@0 1@1 1@2 1@3 1@4 1@5 1@6 1@7 \\
258 max-sdu 0 0 0 0 0 200 0 0 \\
259 base-time 200 \\
260 sched-entry S 80 20000 \\
261 sched-entry S a0 20000 \\
262 sched-entry S 5f 60000 \\
263 flags 0x2
264 .EE
265
266 .SH SEE ALSO
267 .BR tc-stab(8)
268
269 .SH AUTHORS
270 Vinicius Costa Gomes <[email protected]>