]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright(c) 2010-2014 Intel Corporation. All rights reserved. | |
5 | * All rights reserved. | |
6 | * | |
7 | * Redistribution and use in source and binary forms, with or without | |
8 | * modification, are permitted provided that the following conditions | |
9 | * are met: | |
10 | * | |
11 | * * Redistributions of source code must retain the above copyright | |
12 | * notice, this list of conditions and the following disclaimer. | |
13 | * * Redistributions in binary form must reproduce the above copyright | |
14 | * notice, this list of conditions and the following disclaimer in | |
15 | * the documentation and/or other materials provided with the | |
16 | * distribution. | |
17 | * * Neither the name of Intel Corporation nor the names of its | |
18 | * contributors may be used to endorse or promote products derived | |
19 | * from this software without specific prior written permission. | |
20 | * | |
21 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
22 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
23 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
24 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
25 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
26 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
27 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
28 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
29 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
30 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
31 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
32 | */ | |
33 | ||
34 | #ifndef __INCLUDE_RTE_SCHED_H__ | |
35 | #define __INCLUDE_RTE_SCHED_H__ | |
36 | ||
37 | #ifdef __cplusplus | |
38 | extern "C" { | |
39 | #endif | |
40 | ||
41 | /** | |
42 | * @file | |
43 | * RTE Hierarchical Scheduler | |
44 | * | |
45 | * The hierarchical scheduler prioritizes the transmission of packets | |
46 | * from different users and traffic classes according to the Service | |
47 | * Level Agreements (SLAs) defined for the current network node. | |
48 | * | |
49 | * The scheduler supports thousands of packet queues grouped under a | |
50 | * 5-level hierarchy: | |
51 | * 1. Port: | |
52 | * - Typical usage: output Ethernet port; | |
53 | * - Multiple ports are scheduled in round robin order with | |
54 | * equal priority; | |
55 | * 2. Subport: | |
56 | * - Typical usage: group of users; | |
57 | * - Traffic shaping using the token bucket algorithm | |
58 | * (one bucket per subport); | |
59 | * - Upper limit enforced per traffic class at subport level; | |
60 | * - Lower priority traffic classes able to reuse subport | |
61 | * bandwidth currently unused by higher priority traffic | |
62 | * classes of the same subport; | |
63 | * - When any subport traffic class is oversubscribed | |
64 | * (configuration time event), the usage of subport member | |
65 | * pipes with high demand for thattraffic class pipes is | |
66 | * truncated to a dynamically adjusted value with no | |
67 | * impact to low demand pipes; | |
68 | * 3. Pipe: | |
69 | * - Typical usage: individual user/subscriber; | |
70 | * - Traffic shaping using the token bucket algorithm | |
71 | * (one bucket per pipe); | |
72 | * 4. Traffic class: | |
73 | * - Traffic classes of the same pipe handled in strict | |
74 | * priority order; | |
75 | * - Upper limit enforced per traffic class at the pipe level; | |
76 | * - Lower priority traffic classes able to reuse pipe | |
77 | * bandwidth currently unused by higher priority traffic | |
78 | * classes of the same pipe; | |
79 | * 5. Queue: | |
80 | * - Typical usage: queue hosting packets from one or | |
81 | * multiple connections of same traffic class belonging to | |
82 | * the same user; | |
83 | * - Weighted Round Robin (WRR) is used to service the | |
84 | * queues within same pipe traffic class. | |
85 | * | |
86 | */ | |
87 | ||
88 | #include <sys/types.h> | |
89 | #include <rte_mbuf.h> | |
90 | #include <rte_meter.h> | |
91 | ||
92 | /** Random Early Detection (RED) */ | |
93 | #ifdef RTE_SCHED_RED | |
94 | #include "rte_red.h" | |
95 | #endif | |
96 | ||
97 | /** Number of traffic classes per pipe (as well as subport). | |
98 | * Cannot be changed. | |
99 | */ | |
100 | #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE 4 | |
101 | ||
102 | /** Number of queues per pipe traffic class. Cannot be changed. */ | |
103 | #define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS 4 | |
104 | ||
105 | /** Number of queues per pipe. */ | |
106 | #define RTE_SCHED_QUEUES_PER_PIPE \ | |
107 | (RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE * \ | |
108 | RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS) | |
109 | ||
110 | /** Maximum number of pipe profiles that can be defined per port. | |
111 | * Compile-time configurable. | |
112 | */ | |
113 | #ifndef RTE_SCHED_PIPE_PROFILES_PER_PORT | |
114 | #define RTE_SCHED_PIPE_PROFILES_PER_PORT 256 | |
115 | #endif | |
116 | ||
117 | /* | |
118 | * Ethernet framing overhead. Overhead fields per Ethernet frame: | |
119 | * 1. Preamble: 7 bytes; | |
120 | * 2. Start of Frame Delimiter (SFD): 1 byte; | |
121 | * 3. Frame Check Sequence (FCS): 4 bytes; | |
122 | * 4. Inter Frame Gap (IFG): 12 bytes. | |
123 | * | |
124 | * The FCS is considered overhead only if not included in the packet | |
125 | * length (field pkt_len of struct rte_mbuf). | |
126 | */ | |
127 | #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT | |
128 | #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT 24 | |
129 | #endif | |
130 | ||
131 | /* | |
132 | * Subport configuration parameters. The period and credits_per_period | |
133 | * parameters are measured in bytes, with one byte meaning the time | |
134 | * duration associated with the transmission of one byte on the | |
135 | * physical medium of the output port, with pipe or pipe traffic class | |
136 | * rate (measured as percentage of output port rate) determined as | |
137 | * credits_per_period divided by period. One credit represents one | |
138 | * byte. | |
139 | */ | |
140 | struct rte_sched_subport_params { | |
141 | /* Subport token bucket */ | |
142 | uint32_t tb_rate; /**< Rate (measured in bytes per second) */ | |
143 | uint32_t tb_size; /**< Size (measured in credits) */ | |
144 | ||
145 | /* Subport traffic classes */ | |
146 | uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; | |
147 | /**< Traffic class rates (measured in bytes per second) */ | |
148 | uint32_t tc_period; | |
149 | /**< Enforcement period for rates (measured in milliseconds) */ | |
150 | }; | |
151 | ||
152 | /** Subport statistics */ | |
153 | struct rte_sched_subport_stats { | |
154 | /* Packets */ | |
155 | uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; | |
156 | /**< Number of packets successfully written */ | |
157 | uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; | |
158 | /**< Number of packets dropped */ | |
159 | ||
160 | /* Bytes */ | |
161 | uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; | |
162 | /**< Number of bytes successfully written for each traffic class */ | |
163 | uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; | |
164 | /**< Number of bytes dropped for each traffic class */ | |
165 | ||
166 | #ifdef RTE_SCHED_RED | |
167 | uint32_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; | |
168 | /**< Number of packets dropped by red */ | |
169 | #endif | |
170 | }; | |
171 | ||
172 | /* | |
173 | * Pipe configuration parameters. The period and credits_per_period | |
174 | * parameters are measured in bytes, with one byte meaning the time | |
175 | * duration associated with the transmission of one byte on the | |
176 | * physical medium of the output port, with pipe or pipe traffic class | |
177 | * rate (measured as percentage of output port rate) determined as | |
178 | * credits_per_period divided by period. One credit represents one | |
179 | * byte. | |
180 | */ | |
181 | struct rte_sched_pipe_params { | |
182 | /* Pipe token bucket */ | |
183 | uint32_t tb_rate; /**< Rate (measured in bytes per second) */ | |
184 | uint32_t tb_size; /**< Size (measured in credits) */ | |
185 | ||
186 | /* Pipe traffic classes */ | |
187 | uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; | |
188 | /**< Traffic class rates (measured in bytes per second) */ | |
189 | uint32_t tc_period; | |
190 | /**< Enforcement period (measured in milliseconds) */ | |
191 | #ifdef RTE_SCHED_SUBPORT_TC_OV | |
192 | uint8_t tc_ov_weight; /**< Weight Traffic class 3 oversubscription */ | |
193 | #endif | |
194 | ||
195 | /* Pipe queues */ | |
196 | uint8_t wrr_weights[RTE_SCHED_QUEUES_PER_PIPE]; /**< WRR weights */ | |
197 | }; | |
198 | ||
199 | /** Queue statistics */ | |
200 | struct rte_sched_queue_stats { | |
201 | /* Packets */ | |
202 | uint32_t n_pkts; /**< Packets successfully written */ | |
203 | uint32_t n_pkts_dropped; /**< Packets dropped */ | |
204 | #ifdef RTE_SCHED_RED | |
205 | uint32_t n_pkts_red_dropped; /**< Packets dropped by RED */ | |
206 | #endif | |
207 | ||
208 | /* Bytes */ | |
209 | uint32_t n_bytes; /**< Bytes successfully written */ | |
210 | uint32_t n_bytes_dropped; /**< Bytes dropped */ | |
211 | }; | |
212 | ||
213 | /** Port configuration parameters. */ | |
214 | struct rte_sched_port_params { | |
215 | const char *name; /**< String to be associated */ | |
216 | int socket; /**< CPU socket ID */ | |
217 | uint32_t rate; /**< Output port rate | |
218 | * (measured in bytes per second) */ | |
219 | uint32_t mtu; /**< Maximum Ethernet frame size | |
220 | * (measured in bytes). | |
221 | * Should not include the framing overhead. */ | |
222 | uint32_t frame_overhead; /**< Framing overhead per packet | |
223 | * (measured in bytes) */ | |
224 | uint32_t n_subports_per_port; /**< Number of subports */ | |
225 | uint32_t n_pipes_per_subport; /**< Number of pipes per subport */ | |
226 | uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; | |
227 | /**< Packet queue size for each traffic class. | |
228 | * All queues within the same pipe traffic class have the same | |
229 | * size. Queues from different pipes serving the same traffic | |
230 | * class have the same size. */ | |
231 | struct rte_sched_pipe_params *pipe_profiles; | |
232 | /**< Pipe profile table. | |
233 | * Every pipe is configured using one of the profiles from this table. */ | |
234 | uint32_t n_pipe_profiles; /**< Profiles in the pipe profile table */ | |
235 | #ifdef RTE_SCHED_RED | |
236 | struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][e_RTE_METER_COLORS]; /**< RED parameters */ | |
237 | #endif | |
238 | }; | |
239 | ||
240 | /* | |
241 | * Configuration | |
242 | * | |
243 | ***/ | |
244 | ||
245 | /** | |
246 | * Hierarchical scheduler port configuration | |
247 | * | |
248 | * @param params | |
249 | * Port scheduler configuration parameter structure | |
250 | * @return | |
251 | * Handle to port scheduler instance upon success or NULL otherwise. | |
252 | */ | |
253 | struct rte_sched_port * | |
254 | rte_sched_port_config(struct rte_sched_port_params *params); | |
255 | ||
256 | /** | |
257 | * Hierarchical scheduler port free | |
258 | * | |
259 | * @param port | |
260 | * Handle to port scheduler instance | |
261 | */ | |
262 | void | |
263 | rte_sched_port_free(struct rte_sched_port *port); | |
264 | ||
265 | /** | |
266 | * Hierarchical scheduler subport configuration | |
267 | * | |
268 | * @param port | |
269 | * Handle to port scheduler instance | |
270 | * @param subport_id | |
271 | * Subport ID | |
272 | * @param params | |
273 | * Subport configuration parameters | |
274 | * @return | |
275 | * 0 upon success, error code otherwise | |
276 | */ | |
277 | int | |
278 | rte_sched_subport_config(struct rte_sched_port *port, | |
279 | uint32_t subport_id, | |
280 | struct rte_sched_subport_params *params); | |
281 | ||
282 | /** | |
283 | * Hierarchical scheduler pipe configuration | |
284 | * | |
285 | * @param port | |
286 | * Handle to port scheduler instance | |
287 | * @param subport_id | |
288 | * Subport ID | |
289 | * @param pipe_id | |
290 | * Pipe ID within subport | |
291 | * @param pipe_profile | |
292 | * ID of port-level pre-configured pipe profile | |
293 | * @return | |
294 | * 0 upon success, error code otherwise | |
295 | */ | |
296 | int | |
297 | rte_sched_pipe_config(struct rte_sched_port *port, | |
298 | uint32_t subport_id, | |
299 | uint32_t pipe_id, | |
300 | int32_t pipe_profile); | |
301 | ||
302 | /** | |
303 | * Hierarchical scheduler memory footprint size per port | |
304 | * | |
305 | * @param params | |
306 | * Port scheduler configuration parameter structure | |
307 | * @return | |
308 | * Memory footprint size in bytes upon success, 0 otherwise | |
309 | */ | |
310 | uint32_t | |
311 | rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params); | |
312 | ||
313 | /* | |
314 | * Statistics | |
315 | * | |
316 | ***/ | |
317 | ||
318 | /** | |
319 | * Hierarchical scheduler subport statistics read | |
320 | * | |
321 | * @param port | |
322 | * Handle to port scheduler instance | |
323 | * @param subport_id | |
324 | * Subport ID | |
325 | * @param stats | |
326 | * Pointer to pre-allocated subport statistics structure where the statistics | |
327 | * counters should be stored | |
328 | * @param tc_ov | |
329 | * Pointer to pre-allocated 4-entry array where the oversubscription status for | |
330 | * each of the 4 subport traffic classes should be stored. | |
331 | * @return | |
332 | * 0 upon success, error code otherwise | |
333 | */ | |
334 | int | |
335 | rte_sched_subport_read_stats(struct rte_sched_port *port, | |
336 | uint32_t subport_id, | |
337 | struct rte_sched_subport_stats *stats, | |
338 | uint32_t *tc_ov); | |
339 | ||
340 | /** | |
341 | * Hierarchical scheduler queue statistics read | |
342 | * | |
343 | * @param port | |
344 | * Handle to port scheduler instance | |
345 | * @param queue_id | |
346 | * Queue ID within port scheduler | |
347 | * @param stats | |
348 | * Pointer to pre-allocated subport statistics structure where the statistics | |
349 | * counters should be stored | |
350 | * @param qlen | |
351 | * Pointer to pre-allocated variable where the current queue length | |
352 | * should be stored. | |
353 | * @return | |
354 | * 0 upon success, error code otherwise | |
355 | */ | |
356 | int | |
357 | rte_sched_queue_read_stats(struct rte_sched_port *port, | |
358 | uint32_t queue_id, | |
359 | struct rte_sched_queue_stats *stats, | |
360 | uint16_t *qlen); | |
361 | ||
362 | /** | |
363 | * Scheduler hierarchy path write to packet descriptor. Typically | |
364 | * called by the packet classification stage. | |
365 | * | |
366 | * @param pkt | |
367 | * Packet descriptor handle | |
368 | * @param subport | |
369 | * Subport ID | |
370 | * @param pipe | |
371 | * Pipe ID within subport | |
372 | * @param traffic_class | |
373 | * Traffic class ID within pipe (0 .. 3) | |
374 | * @param queue | |
375 | * Queue ID within pipe traffic class (0 .. 3) | |
376 | * @param color | |
377 | * Packet color set | |
378 | */ | |
379 | void | |
380 | rte_sched_port_pkt_write(struct rte_mbuf *pkt, | |
381 | uint32_t subport, uint32_t pipe, uint32_t traffic_class, | |
382 | uint32_t queue, enum rte_meter_color color); | |
383 | ||
384 | /** | |
385 | * Scheduler hierarchy path read from packet descriptor (struct | |
386 | * rte_mbuf). Typically called as part of the hierarchical scheduler | |
387 | * enqueue operation. The subport, pipe, traffic class and queue | |
388 | * parameters need to be pre-allocated by the caller. | |
389 | * | |
390 | * @param pkt | |
391 | * Packet descriptor handle | |
392 | * @param subport | |
393 | * Subport ID | |
394 | * @param pipe | |
395 | * Pipe ID within subport | |
396 | * @param traffic_class | |
397 | * Traffic class ID within pipe (0 .. 3) | |
398 | * @param queue | |
399 | * Queue ID within pipe traffic class (0 .. 3) | |
400 | * | |
401 | */ | |
402 | void | |
403 | rte_sched_port_pkt_read_tree_path(const struct rte_mbuf *pkt, | |
404 | uint32_t *subport, uint32_t *pipe, | |
405 | uint32_t *traffic_class, uint32_t *queue); | |
406 | ||
407 | enum rte_meter_color | |
408 | rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt); | |
409 | ||
410 | /** | |
411 | * Hierarchical scheduler port enqueue. Writes up to n_pkts to port | |
412 | * scheduler and returns the number of packets actually written. For | |
413 | * each packet, the port scheduler queue to write the packet to is | |
414 | * identified by reading the hierarchy path from the packet | |
415 | * descriptor; if the queue is full or congested and the packet is not | |
416 | * written to the queue, then the packet is automatically dropped | |
417 | * without any action required from the caller. | |
418 | * | |
419 | * @param port | |
420 | * Handle to port scheduler instance | |
421 | * @param pkts | |
422 | * Array storing the packet descriptor handles | |
423 | * @param n_pkts | |
424 | * Number of packets to enqueue from the pkts array into the port scheduler | |
425 | * @return | |
426 | * Number of packets successfully enqueued | |
427 | */ | |
428 | int | |
429 | rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts); | |
430 | ||
431 | /** | |
432 | * Hierarchical scheduler port dequeue. Reads up to n_pkts from the | |
433 | * port scheduler and stores them in the pkts array and returns the | |
434 | * number of packets actually read. The pkts array needs to be | |
435 | * pre-allocated by the caller with at least n_pkts entries. | |
436 | * | |
437 | * @param port | |
438 | * Handle to port scheduler instance | |
439 | * @param pkts | |
440 | * Pre-allocated packet descriptor array where the packets dequeued | |
441 | * from the port | |
442 | * scheduler should be stored | |
443 | * @param n_pkts | |
444 | * Number of packets to dequeue from the port scheduler | |
445 | * @return | |
446 | * Number of packets successfully dequeued and placed in the pkts array | |
447 | */ | |
448 | int | |
449 | rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts); | |
450 | ||
451 | #ifdef __cplusplus | |
452 | } | |
453 | #endif | |
454 | ||
455 | #endif /* __INCLUDE_RTE_SCHED_H__ */ |