aede2e9865b5ed0922108350f88351d36d1d66b2
[dpdk.git] / lib / librte_sched / rte_sched.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2010-2014 Intel Corporation
3  */
4
5 #ifndef __INCLUDE_RTE_SCHED_H__
6 #define __INCLUDE_RTE_SCHED_H__
7
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11
12 /**
13  * @file
14  * RTE Hierarchical Scheduler
15  *
16  * The hierarchical scheduler prioritizes the transmission of packets
17  * from different users and traffic classes according to the Service
18  * Level Agreements (SLAs) defined for the current network node.
19  *
20  * The scheduler supports thousands of packet queues grouped under a
21  * 5-level hierarchy:
22  *     1. Port:
23  *           - Typical usage: output Ethernet port;
24  *           - Multiple ports are scheduled in round robin order with
25  *          equal priority;
26  *     2. Subport:
27  *           - Typical usage: group of users;
28  *           - Traffic shaping using the token bucket algorithm
29  *          (one bucket per subport);
30  *           - Upper limit enforced per traffic class at subport level;
31  *           - Lower priority traffic classes able to reuse subport
32  *          bandwidth currently unused by higher priority traffic
33  *          classes of the same subport;
34  *           - When any subport traffic class is oversubscribed
35  *          (configuration time event), the usage of subport member
36  *          pipes with high demand for that traffic class pipes is
37  *          truncated to a dynamically adjusted value with no
38  *             impact to low demand pipes;
39  *     3. Pipe:
40  *           - Typical usage: individual user/subscriber;
41  *           - Traffic shaping using the token bucket algorithm
42  *          (one bucket per pipe);
43  *     4. Traffic class:
44  *           - Traffic classes of the same pipe handled in strict
45  *          priority order;
46  *           - Upper limit enforced per traffic class at the pipe level;
47  *           - Lower priority traffic classes able to reuse pipe
48  *          bandwidth currently unused by higher priority traffic
49  *          classes of the same pipe;
50  *     5. Queue:
51  *           - Typical usage: queue hosting packets from one or
52  *          multiple connections of same traffic class belonging to
53  *          the same user;
54  *           - Weighted Round Robin (WRR) is used to service the
55  *          queues within same pipe lowest priority traffic class (best-effort).
56  *
57  */
58
59 #include <sys/types.h>
60 #include <rte_compat.h>
61 #include <rte_mbuf.h>
62 #include <rte_meter.h>
63
64 /** Random Early Detection (RED) */
65 #ifdef RTE_SCHED_RED
66 #include "rte_red.h"
67 #endif
68
69 /** Maximum number of queues per pipe.
70  * Note that the multiple queues (power of 2) can only be assigned to
71  * lowest priority (best-effort) traffic class. Other higher priority traffic
72  * classes can only have one queue.
73  * Can not change.
74  *
75  * @see struct rte_sched_port_params
76  */
77 #define RTE_SCHED_QUEUES_PER_PIPE    16
78
79 /** Number of WRR queues for best-effort traffic class per pipe.
80  *
81  * @see struct rte_sched_pipe_params
82  */
83 #define RTE_SCHED_BE_QUEUES_PER_PIPE    4
84
85 /** Number of traffic classes per pipe (as well as subport).
86  * @see struct rte_sched_subport_params
87  * @see struct rte_sched_pipe_params
88  */
89 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE    \
90 (RTE_SCHED_QUEUES_PER_PIPE - RTE_SCHED_BE_QUEUES_PER_PIPE + 1)
91
92 /** Best-effort traffic class ID
93  * Can not change.
94  */
95 #define RTE_SCHED_TRAFFIC_CLASS_BE    (RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE - 1)
96
97 /*
98  * Ethernet framing overhead. Overhead fields per Ethernet frame:
99  * 1. Preamble:                             7 bytes;
100  * 2. Start of Frame Delimiter (SFD):       1 byte;
101  * 3. Frame Check Sequence (FCS):           4 bytes;
102  * 4. Inter Frame Gap (IFG):               12 bytes.
103  *
104  * The FCS is considered overhead only if not included in the packet
105  * length (field pkt_len of struct rte_mbuf).
106  *
107  * @see struct rte_sched_port_params
108  */
109 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
110 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT      24
111 #endif
112
113 /*
114  * Pipe configuration parameters. The period and credits_per_period
115  * parameters are measured in bytes, with one byte meaning the time
116  * duration associated with the transmission of one byte on the
117  * physical medium of the output port, with pipe or pipe traffic class
118  * rate (measured as percentage of output port rate) determined as
119  * credits_per_period divided by period. One credit represents one
120  * byte.
121  */
122 struct rte_sched_pipe_params {
123         /** Token bucket rate (measured in bytes per second) */
124         uint64_t tb_rate;
125
126         /** Token bucket size (measured in credits) */
127         uint64_t tb_size;
128
129         /** Traffic class rates (measured in bytes per second) */
130         uint64_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
131
132         /** Enforcement period (measured in milliseconds) */
133         uint64_t tc_period;
134
135         /** Best-effort traffic class oversubscription weight */
136         uint8_t tc_ov_weight;
137
138         /** WRR weights of best-effort traffic class queues */
139         uint8_t wrr_weights[RTE_SCHED_BE_QUEUES_PER_PIPE];
140 };
141
142 /*
143  * Subport configuration parameters. The period and credits_per_period
144  * parameters are measured in bytes, with one byte meaning the time
145  * duration associated with the transmission of one byte on the
146  * physical medium of the output port, with pipe or pipe traffic class
147  * rate (measured as percentage of output port rate) determined as
148  * credits_per_period divided by period. One credit represents one
149  * byte.
150  */
151 struct rte_sched_subport_params {
152         /** Token bucket rate (measured in bytes per second) */
153         uint64_t tb_rate;
154
155         /** Token bucket size (measured in credits) */
156         uint64_t tb_size;
157
158         /** Traffic class rates (measured in bytes per second) */
159         uint64_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
160
161         /** Enforcement period for rates (measured in milliseconds) */
162         uint64_t tc_period;
163
164         /** Number of subport pipes.
165          * The subport can enable/allocate fewer pipes than the maximum
166          * number set through struct port_params::n_max_pipes_per_subport,
167          * as needed, to avoid memory allocation for the queues of the
168          * pipes that are not really needed.
169          */
170         uint32_t n_pipes_per_subport_enabled;
171
172         /** Packet queue size for each traffic class.
173          * All the pipes within the same subport share the similar
174          * configuration for the queues.
175          */
176         uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
177
178         /** Pipe profile table.
179          * Every pipe is configured using one of the profiles from this table.
180          */
181         struct rte_sched_pipe_params *pipe_profiles;
182
183         /** Profiles in the pipe profile table */
184         uint32_t n_pipe_profiles;
185
186         /** Max allowed profiles in the pipe profile table */
187         uint32_t n_max_pipe_profiles;
188
189 #ifdef RTE_SCHED_RED
190         /** RED parameters */
191         struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][RTE_COLORS];
192 #endif
193 };
194
195 struct rte_sched_subport_profile_params {
196         /** Token bucket rate (measured in bytes per second) */
197         uint64_t tb_rate;
198
199         /** Token bucket size (measured in credits) */
200         uint64_t tb_size;
201
202         /** Traffic class rates (measured in bytes per second) */
203         uint64_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
204
205         /** Enforcement period for rates (measured in milliseconds) */
206         uint64_t tc_period;
207 };
208
209 /** Subport statistics */
210 struct rte_sched_subport_stats {
211         /** Number of packets successfully written */
212         uint64_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
213
214         /** Number of packets dropped */
215         uint64_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
216
217         /** Number of bytes successfully written for each traffic class */
218         uint64_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
219
220         /** Number of bytes dropped for each traffic class */
221         uint64_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
222
223 #ifdef RTE_SCHED_RED
224         /** Number of packets dropped by red */
225         uint64_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
226 #endif
227 };
228
229 /** Queue statistics */
230 struct rte_sched_queue_stats {
231         /** Packets successfully written */
232         uint64_t n_pkts;
233
234         /** Packets dropped */
235         uint64_t n_pkts_dropped;
236
237 #ifdef RTE_SCHED_RED
238         /** Packets dropped by RED */
239         uint64_t n_pkts_red_dropped;
240 #endif
241
242         /** Bytes successfully written */
243         uint64_t n_bytes;
244
245         /** Bytes dropped */
246         uint64_t n_bytes_dropped;
247 };
248
249 /** Port configuration parameters. */
250 struct rte_sched_port_params {
251         /** Name of the port to be associated */
252         const char *name;
253
254         /** CPU socket ID */
255         int socket;
256
257         /** Output port rate (measured in bytes per second) */
258         uint64_t rate;
259
260         /** Maximum Ethernet frame size (measured in bytes).
261          * Should not include the framing overhead.
262          */
263         uint32_t mtu;
264
265         /** Framing overhead per packet (measured in bytes) */
266         uint32_t frame_overhead;
267
268         /** Number of subports */
269         uint32_t n_subports_per_port;
270
271         /** subport profile table.
272          * Every pipe is configured using one of the profiles from this table.
273          */
274         struct rte_sched_subport_profile_params *subport_profiles;
275
276         /** Profiles in the pipe profile table */
277         uint32_t n_subport_profiles;
278
279         /** Max allowed profiles in the pipe profile table */
280         uint32_t n_max_subport_profiles;
281
282         /** Maximum number of subport pipes.
283          * This parameter is used to reserve a fixed number of bits
284          * in struct rte_mbuf::sched.queue_id for the pipe_id for all
285          * the subports of the same port.
286          */
287         uint32_t n_pipes_per_subport;
288 };
289
290 /*
291  * Configuration
292  *
293  ***/
294
295 /**
296  * Hierarchical scheduler port configuration
297  *
298  * @param params
299  *   Port scheduler configuration parameter structure
300  * @return
301  *   Handle to port scheduler instance upon success or NULL otherwise.
302  */
303 struct rte_sched_port *
304 rte_sched_port_config(struct rte_sched_port_params *params);
305
306 /**
307  * Hierarchical scheduler port free
308  *
309  * @param port
310  *   Handle to port scheduler instance
311  */
312 void
313 rte_sched_port_free(struct rte_sched_port *port);
314
315 /**
316  * @warning
317  * @b EXPERIMENTAL: this API may change without prior notice.
318  *
319  * Hierarchical scheduler pipe profile add
320  *
321  * @param port
322  *   Handle to port scheduler instance
323  * @param subport_id
324  *   Subport ID
325  * @param params
326  *   Pipe profile parameters
327  * @param pipe_profile_id
328  *   Set to valid profile id when profile is added successfully.
329  * @return
330  *   0 upon success, error code otherwise
331  */
332 __rte_experimental
333 int
334 rte_sched_subport_pipe_profile_add(struct rte_sched_port *port,
335         uint32_t subport_id,
336         struct rte_sched_pipe_params *params,
337         uint32_t *pipe_profile_id);
338
339 /**
340  * @warning
341  * @b EXPERIMENTAL: this API may change without prior notice.
342  *
343  * Hierarchical scheduler subport bandwidth profile add
344  * Note that this function is safe to use in runtime for adding new
345  * subport bandwidth profile as it doesn't have any impact on hiearchical
346  * structure of the scheduler.
347  * @param port
348  *   Handle to port scheduler instance
349  * @param profile
350  *   Subport bandwidth profile
351  * @param subport_profile_id
352  *   Subport profile id
353  * @return
354  *   0 upon success, error code otherwise
355  */
356 __rte_experimental
357 int
358 rte_sched_port_subport_profile_add(struct rte_sched_port *port,
359         struct rte_sched_subport_profile_params *profile,
360         uint32_t *subport_profile_id);
361
362 /**
363  * Hierarchical scheduler subport configuration
364  *
365  * @param port
366  *   Handle to port scheduler instance
367  * @param subport_id
368  *   Subport ID
369  * @param params
370  *   Subport configuration parameters
371  * @return
372  *   0 upon success, error code otherwise
373  */
374 int
375 rte_sched_subport_config(struct rte_sched_port *port,
376         uint32_t subport_id,
377         struct rte_sched_subport_params *params);
378
379 /**
380  * Hierarchical scheduler pipe configuration
381  *
382  * @param port
383  *   Handle to port scheduler instance
384  * @param subport_id
385  *   Subport ID
386  * @param pipe_id
387  *   Pipe ID within subport
388  * @param pipe_profile
389  *   ID of subport-level pre-configured pipe profile
390  * @return
391  *   0 upon success, error code otherwise
392  */
393 int
394 rte_sched_pipe_config(struct rte_sched_port *port,
395         uint32_t subport_id,
396         uint32_t pipe_id,
397         int32_t pipe_profile);
398
399 /**
400  * Hierarchical scheduler memory footprint size per port
401  *
402  * @param port_params
403  *   Port scheduler configuration parameter structure
404  * @param subport_params
405  *   Array of subport parameter structures
406  * @return
407  *   Memory footprint size in bytes upon success, 0 otherwise
408  */
409 uint32_t
410 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *port_params,
411         struct rte_sched_subport_params **subport_params);
412 /*
413  * Statistics
414  *
415  ***/
416
417 /**
418  * Hierarchical scheduler subport statistics read
419  *
420  * @param port
421  *   Handle to port scheduler instance
422  * @param subport_id
423  *   Subport ID
424  * @param stats
425  *   Pointer to pre-allocated subport statistics structure where the statistics
426  *   counters should be stored
427  * @param tc_ov
428  *   Pointer to pre-allocated RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE-entry array
429  *   where the oversubscription status for each of the subport traffic classes
430  *   should be stored.
431  * @return
432  *   0 upon success, error code otherwise
433  */
434 int
435 rte_sched_subport_read_stats(struct rte_sched_port *port,
436         uint32_t subport_id,
437         struct rte_sched_subport_stats *stats,
438         uint32_t *tc_ov);
439
440 /**
441  * Hierarchical scheduler queue statistics read
442  *
443  * @param port
444  *   Handle to port scheduler instance
445  * @param queue_id
446  *   Queue ID within port scheduler
447  * @param stats
448  *   Pointer to pre-allocated subport statistics structure where the statistics
449  *   counters should be stored
450  * @param qlen
451  *   Pointer to pre-allocated variable where the current queue length
452  *   should be stored.
453  * @return
454  *   0 upon success, error code otherwise
455  */
456 int
457 rte_sched_queue_read_stats(struct rte_sched_port *port,
458         uint32_t queue_id,
459         struct rte_sched_queue_stats *stats,
460         uint16_t *qlen);
461
462 /**
463  * Scheduler hierarchy path write to packet descriptor. Typically
464  * called by the packet classification stage.
465  *
466  * @param port
467  *   Handle to port scheduler instance
468  * @param pkt
469  *   Packet descriptor handle
470  * @param subport
471  *   Subport ID
472  * @param pipe
473  *   Pipe ID within subport
474  * @param traffic_class
475  *   Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
476  * @param queue
477  *   Queue ID within pipe traffic class, 0 for high priority TCs, and
478  *   0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
479  * @param color
480  *   Packet color set
481  */
482 void
483 rte_sched_port_pkt_write(struct rte_sched_port *port,
484                          struct rte_mbuf *pkt,
485                          uint32_t subport, uint32_t pipe, uint32_t traffic_class,
486                          uint32_t queue, enum rte_color color);
487
488 /**
489  * Scheduler hierarchy path read from packet descriptor (struct
490  * rte_mbuf). Typically called as part of the hierarchical scheduler
491  * enqueue operation. The subport, pipe, traffic class and queue
492  * parameters need to be pre-allocated by the caller.
493  *
494  * @param port
495  *   Handle to port scheduler instance
496  * @param pkt
497  *   Packet descriptor handle
498  * @param subport
499  *   Subport ID
500  * @param pipe
501  *   Pipe ID within subport
502  * @param traffic_class
503  *   Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
504  * @param queue
505  *   Queue ID within pipe traffic class, 0 for high priority TCs, and
506  *   0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
507  */
508 void
509 rte_sched_port_pkt_read_tree_path(struct rte_sched_port *port,
510                                   const struct rte_mbuf *pkt,
511                                   uint32_t *subport, uint32_t *pipe,
512                                   uint32_t *traffic_class, uint32_t *queue);
513
514 enum rte_color
515 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
516
517 /**
518  * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
519  * scheduler and returns the number of packets actually written. For
520  * each packet, the port scheduler queue to write the packet to is
521  * identified by reading the hierarchy path from the packet
522  * descriptor; if the queue is full or congested and the packet is not
523  * written to the queue, then the packet is automatically dropped
524  * without any action required from the caller.
525  *
526  * @param port
527  *   Handle to port scheduler instance
528  * @param pkts
529  *   Array storing the packet descriptor handles
530  * @param n_pkts
531  *   Number of packets to enqueue from the pkts array into the port scheduler
532  * @return
533  *   Number of packets successfully enqueued
534  */
535 int
536 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
537
538 /**
539  * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
540  * port scheduler and stores them in the pkts array and returns the
541  * number of packets actually read.  The pkts array needs to be
542  * pre-allocated by the caller with at least n_pkts entries.
543  *
544  * @param port
545  *   Handle to port scheduler instance
546  * @param pkts
547  *   Pre-allocated packet descriptor array where the packets dequeued
548  *   from the port
549  *   scheduler should be stored
550  * @param n_pkts
551  *   Number of packets to dequeue from the port scheduler
552  * @return
553  *   Number of packets successfully dequeued and placed in the pkts array
554  */
555 int
556 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
557
558 #ifdef __cplusplus
559 }
560 #endif
561
562 #endif /* __INCLUDE_RTE_SCHED_H__ */