examples: use new API to create control threads
[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 thattraffic 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 traffic class.
56  *
57  */
58
59 #include <sys/types.h>
60 #include <rte_mbuf.h>
61 #include <rte_meter.h>
62
63 /** Random Early Detection (RED) */
64 #ifdef RTE_SCHED_RED
65 #include "rte_red.h"
66 #endif
67
68 /** Number of traffic classes per pipe (as well as subport).
69  * Cannot be changed.
70  */
71 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE    4
72
73 /** Number of queues per pipe traffic class. Cannot be changed. */
74 #define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS    4
75
76 /** Number of queues per pipe. */
77 #define RTE_SCHED_QUEUES_PER_PIPE             \
78         (RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE *     \
79         RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS)
80
81 /** Maximum number of pipe profiles that can be defined per port.
82  * Compile-time configurable.
83  */
84 #ifndef RTE_SCHED_PIPE_PROFILES_PER_PORT
85 #define RTE_SCHED_PIPE_PROFILES_PER_PORT      256
86 #endif
87
88 /*
89  * Ethernet framing overhead. Overhead fields per Ethernet frame:
90  * 1. Preamble:                             7 bytes;
91  * 2. Start of Frame Delimiter (SFD):       1 byte;
92  * 3. Frame Check Sequence (FCS):           4 bytes;
93  * 4. Inter Frame Gap (IFG):               12 bytes.
94  *
95  * The FCS is considered overhead only if not included in the packet
96  * length (field pkt_len of struct rte_mbuf).
97  */
98 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
99 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT      24
100 #endif
101
102 /*
103  * Subport configuration parameters. The period and credits_per_period
104  * parameters are measured in bytes, with one byte meaning the time
105  * duration associated with the transmission of one byte on the
106  * physical medium of the output port, with pipe or pipe traffic class
107  * rate (measured as percentage of output port rate) determined as
108  * credits_per_period divided by period. One credit represents one
109  * byte.
110  */
111 struct rte_sched_subport_params {
112         /* Subport token bucket */
113         uint32_t tb_rate;                /**< Rate (measured in bytes per second) */
114         uint32_t tb_size;                /**< Size (measured in credits) */
115
116         /* Subport traffic classes */
117         uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
118         /**< Traffic class rates (measured in bytes per second) */
119         uint32_t tc_period;
120         /**< Enforcement period for rates (measured in milliseconds) */
121 };
122
123 /** Subport statistics */
124 struct rte_sched_subport_stats {
125         /* Packets */
126         uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
127         /**< Number of packets successfully written */
128         uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
129         /**< Number of packets dropped */
130
131         /* Bytes */
132         uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
133         /**< Number of bytes successfully written for each traffic class */
134         uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
135         /**< Number of bytes dropped for each traffic class */
136
137 #ifdef RTE_SCHED_RED
138         uint32_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
139         /**< Number of packets dropped by red */
140 #endif
141 };
142
143 /*
144  * Pipe configuration parameters. The period and credits_per_period
145  * parameters are measured in bytes, with one byte meaning the time
146  * duration associated with the transmission of one byte on the
147  * physical medium of the output port, with pipe or pipe traffic class
148  * rate (measured as percentage of output port rate) determined as
149  * credits_per_period divided by period. One credit represents one
150  * byte.
151  */
152 struct rte_sched_pipe_params {
153         /* Pipe token bucket */
154         uint32_t tb_rate;                /**< Rate (measured in bytes per second) */
155         uint32_t tb_size;                /**< Size (measured in credits) */
156
157         /* Pipe traffic classes */
158         uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
159         /**< Traffic class rates (measured in bytes per second) */
160         uint32_t tc_period;
161         /**< Enforcement period (measured in milliseconds) */
162 #ifdef RTE_SCHED_SUBPORT_TC_OV
163         uint8_t tc_ov_weight;            /**< Weight Traffic class 3 oversubscription */
164 #endif
165
166         /* Pipe queues */
167         uint8_t  wrr_weights[RTE_SCHED_QUEUES_PER_PIPE]; /**< WRR weights */
168 };
169
170 /** Queue statistics */
171 struct rte_sched_queue_stats {
172         /* Packets */
173         uint32_t n_pkts;                 /**< Packets successfully written */
174         uint32_t n_pkts_dropped;         /**< Packets dropped */
175 #ifdef RTE_SCHED_RED
176         uint32_t n_pkts_red_dropped;     /**< Packets dropped by RED */
177 #endif
178
179         /* Bytes */
180         uint32_t n_bytes;                /**< Bytes successfully written */
181         uint32_t n_bytes_dropped;        /**< Bytes dropped */
182 };
183
184 /** Port configuration parameters. */
185 struct rte_sched_port_params {
186         const char *name;                /**< String to be associated */
187         int socket;                      /**< CPU socket ID */
188         uint32_t rate;                   /**< Output port rate
189                                           * (measured in bytes per second) */
190         uint32_t mtu;                    /**< Maximum Ethernet frame size
191                                           * (measured in bytes).
192                                           * Should not include the framing overhead. */
193         uint32_t frame_overhead;         /**< Framing overhead per packet
194                                           * (measured in bytes) */
195         uint32_t n_subports_per_port;    /**< Number of subports */
196         uint32_t n_pipes_per_subport;    /**< Number of pipes per subport */
197         uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
198         /**< Packet queue size for each traffic class.
199          * All queues within the same pipe traffic class have the same
200          * size. Queues from different pipes serving the same traffic
201          * class have the same size. */
202         struct rte_sched_pipe_params *pipe_profiles;
203         /**< Pipe profile table.
204          * Every pipe is configured using one of the profiles from this table. */
205         uint32_t n_pipe_profiles;        /**< Profiles in the pipe profile table */
206 #ifdef RTE_SCHED_RED
207         struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][e_RTE_METER_COLORS]; /**< RED parameters */
208 #endif
209 };
210
211 /*
212  * Configuration
213  *
214  ***/
215
216 /**
217  * Hierarchical scheduler port configuration
218  *
219  * @param params
220  *   Port scheduler configuration parameter structure
221  * @return
222  *   Handle to port scheduler instance upon success or NULL otherwise.
223  */
224 struct rte_sched_port *
225 rte_sched_port_config(struct rte_sched_port_params *params);
226
227 /**
228  * Hierarchical scheduler port free
229  *
230  * @param port
231  *   Handle to port scheduler instance
232  */
233 void
234 rte_sched_port_free(struct rte_sched_port *port);
235
236 /**
237  * Hierarchical scheduler subport configuration
238  *
239  * @param port
240  *   Handle to port scheduler instance
241  * @param subport_id
242  *   Subport ID
243  * @param params
244  *   Subport configuration parameters
245  * @return
246  *   0 upon success, error code otherwise
247  */
248 int
249 rte_sched_subport_config(struct rte_sched_port *port,
250         uint32_t subport_id,
251         struct rte_sched_subport_params *params);
252
253 /**
254  * Hierarchical scheduler pipe configuration
255  *
256  * @param port
257  *   Handle to port scheduler instance
258  * @param subport_id
259  *   Subport ID
260  * @param pipe_id
261  *   Pipe ID within subport
262  * @param pipe_profile
263  *   ID of port-level pre-configured pipe profile
264  * @return
265  *   0 upon success, error code otherwise
266  */
267 int
268 rte_sched_pipe_config(struct rte_sched_port *port,
269         uint32_t subport_id,
270         uint32_t pipe_id,
271         int32_t pipe_profile);
272
273 /**
274  * Hierarchical scheduler memory footprint size per port
275  *
276  * @param params
277  *   Port scheduler configuration parameter structure
278  * @return
279  *   Memory footprint size in bytes upon success, 0 otherwise
280  */
281 uint32_t
282 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params);
283
284 /*
285  * Statistics
286  *
287  ***/
288
289 /**
290  * Hierarchical scheduler subport statistics read
291  *
292  * @param port
293  *   Handle to port scheduler instance
294  * @param subport_id
295  *   Subport ID
296  * @param stats
297  *   Pointer to pre-allocated subport statistics structure where the statistics
298  *   counters should be stored
299  * @param tc_ov
300  *   Pointer to pre-allocated 4-entry array where the oversubscription status for
301  *   each of the 4 subport traffic classes should be stored.
302  * @return
303  *   0 upon success, error code otherwise
304  */
305 int
306 rte_sched_subport_read_stats(struct rte_sched_port *port,
307         uint32_t subport_id,
308         struct rte_sched_subport_stats *stats,
309         uint32_t *tc_ov);
310
311 /**
312  * Hierarchical scheduler queue statistics read
313  *
314  * @param port
315  *   Handle to port scheduler instance
316  * @param queue_id
317  *   Queue ID within port scheduler
318  * @param stats
319  *   Pointer to pre-allocated subport statistics structure where the statistics
320  *   counters should be stored
321  * @param qlen
322  *   Pointer to pre-allocated variable where the current queue length
323  *   should be stored.
324  * @return
325  *   0 upon success, error code otherwise
326  */
327 int
328 rte_sched_queue_read_stats(struct rte_sched_port *port,
329         uint32_t queue_id,
330         struct rte_sched_queue_stats *stats,
331         uint16_t *qlen);
332
333 /**
334  * Scheduler hierarchy path write to packet descriptor. Typically
335  * called by the packet classification stage.
336  *
337  * @param pkt
338  *   Packet descriptor handle
339  * @param subport
340  *   Subport ID
341  * @param pipe
342  *   Pipe ID within subport
343  * @param traffic_class
344  *   Traffic class ID within pipe (0 .. 3)
345  * @param queue
346  *   Queue ID within pipe traffic class (0 .. 3)
347  * @param color
348  *   Packet color set
349  */
350 void
351 rte_sched_port_pkt_write(struct rte_mbuf *pkt,
352                          uint32_t subport, uint32_t pipe, uint32_t traffic_class,
353                          uint32_t queue, enum rte_meter_color color);
354
355 /**
356  * Scheduler hierarchy path read from packet descriptor (struct
357  * rte_mbuf). Typically called as part of the hierarchical scheduler
358  * enqueue operation. The subport, pipe, traffic class and queue
359  * parameters need to be pre-allocated by the caller.
360  *
361  * @param pkt
362  *   Packet descriptor handle
363  * @param subport
364  *   Subport ID
365  * @param pipe
366  *   Pipe ID within subport
367  * @param traffic_class
368  *   Traffic class ID within pipe (0 .. 3)
369  * @param queue
370  *   Queue ID within pipe traffic class (0 .. 3)
371  *
372  */
373 void
374 rte_sched_port_pkt_read_tree_path(const struct rte_mbuf *pkt,
375                                   uint32_t *subport, uint32_t *pipe,
376                                   uint32_t *traffic_class, uint32_t *queue);
377
378 enum rte_meter_color
379 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
380
381 /**
382  * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
383  * scheduler and returns the number of packets actually written. For
384  * each packet, the port scheduler queue to write the packet to is
385  * identified by reading the hierarchy path from the packet
386  * descriptor; if the queue is full or congested and the packet is not
387  * written to the queue, then the packet is automatically dropped
388  * without any action required from the caller.
389  *
390  * @param port
391  *   Handle to port scheduler instance
392  * @param pkts
393  *   Array storing the packet descriptor handles
394  * @param n_pkts
395  *   Number of packets to enqueue from the pkts array into the port scheduler
396  * @return
397  *   Number of packets successfully enqueued
398  */
399 int
400 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
401
402 /**
403  * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
404  * port scheduler and stores them in the pkts array and returns the
405  * number of packets actually read.  The pkts array needs to be
406  * pre-allocated by the caller with at least n_pkts entries.
407  *
408  * @param port
409  *   Handle to port scheduler instance
410  * @param pkts
411  *   Pre-allocated packet descriptor array where the packets dequeued
412  *   from the port
413  *   scheduler should be stored
414  * @param n_pkts
415  *   Number of packets to dequeue from the port scheduler
416  * @return
417  *   Number of packets successfully dequeued and placed in the pkts array
418  */
419 int
420 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
421
422 #ifdef __cplusplus
423 }
424 #endif
425
426 #endif /* __INCLUDE_RTE_SCHED_H__ */