4 * Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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
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.
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.
34 #ifndef __INCLUDE_RTE_SCHED_H__
35 #define __INCLUDE_RTE_SCHED_H__
43 * RTE Hierarchical Scheduler
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.
49 * The scheduler supports thousands of packet queues grouped under a
52 * - Typical usage: output Ethernet port;
53 * - Multiple ports are scheduled in round robin order with
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;
69 * - Typical usage: individual user/subscriber;
70 * - Traffic shaping using the token bucket algorithm
71 * (one bucket per pipe);
73 * - Traffic classes of the same pipe handled in strict
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;
80 * - Typical usage: queue hosting packets from one or
81 * multiple connections of same traffic class belonging to
83 * - Weighted Round Robin (WRR) is used to service the
84 * queues within same pipe traffic class.
88 #include <sys/types.h>
90 #include <rte_meter.h>
92 /** Random Early Detection (RED) */
97 /** Number of traffic classes per pipe (as well as subport).
100 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE 4
102 /** Number of queues per pipe traffic class. Cannot be changed. */
103 #define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS 4
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)
110 /** Maximum number of pipe profiles that can be defined per port.
111 * Compile-time configurable.
113 #ifndef RTE_SCHED_PIPE_PROFILES_PER_PORT
114 #define RTE_SCHED_PIPE_PROFILES_PER_PORT 256
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.
124 * The FCS is considered overhead only if not included in the packet
125 * length (field pkt_len of struct rte_mbuf).
127 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
128 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT 24
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
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) */
145 /* Subport traffic classes */
146 uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
147 /**< Traffic class rates (measured in bytes per second) */
149 /**< Enforcement period for rates (measured in milliseconds) */
152 /** Subport statistics */
153 struct rte_sched_subport_stats {
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 */
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 */
168 * Pipe configuration parameters. The period and credits_per_period
169 * parameters are measured in bytes, with one byte meaning the time
170 * duration associated with the transmission of one byte on the
171 * physical medium of the output port, with pipe or pipe traffic class
172 * rate (measured as percentage of output port rate) determined as
173 * credits_per_period divided by period. One credit represents one
176 struct rte_sched_pipe_params {
177 /* Pipe token bucket */
178 uint32_t tb_rate; /**< Rate (measured in bytes per second) */
179 uint32_t tb_size; /**< Size (measured in credits) */
181 /* Pipe traffic classes */
182 uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
183 /**< Traffic class rates (measured in bytes per second) */
185 /**< Enforcement period (measured in milliseconds) */
186 #ifdef RTE_SCHED_SUBPORT_TC_OV
187 uint8_t tc_ov_weight; /**< Weight Traffic class 3 oversubscription */
191 uint8_t wrr_weights[RTE_SCHED_QUEUES_PER_PIPE]; /**< WRR weights */
194 /** Queue statistics */
195 struct rte_sched_queue_stats {
197 uint32_t n_pkts; /**< Packets successfully written */
198 uint32_t n_pkts_dropped; /**< Packets dropped */
201 uint32_t n_bytes; /**< Bytes successfully written */
202 uint32_t n_bytes_dropped; /**< Bytes dropped */
205 /** Port configuration parameters. */
206 struct rte_sched_port_params {
207 const char *name; /**< String to be associated */
208 int socket; /**< CPU socket ID */
209 uint32_t rate; /**< Output port rate
210 * (measured in bytes per second) */
211 uint32_t mtu; /**< Maximum Ethernet frame size
212 * (measured in bytes).
213 * Should not include the framing overhead. */
214 uint32_t frame_overhead; /**< Framing overhead per packet
215 * (measured in bytes) */
216 uint32_t n_subports_per_port; /**< Number of subports */
217 uint32_t n_pipes_per_subport; /**< Number of pipes per subport */
218 uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
219 /**< Packet queue size for each traffic class.
220 * All queues within the same pipe traffic class have the same
221 * size. Queues from different pipes serving the same traffic
222 * class have the same size. */
223 struct rte_sched_pipe_params *pipe_profiles;
224 /**< Pipe profile table.
225 * Every pipe is configured using one of the profiles from this table. */
226 uint32_t n_pipe_profiles; /**< Profiles in the pipe profile table */
228 struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][e_RTE_METER_COLORS]; /**< RED parameters */
238 * Hierarchical scheduler port configuration
241 * Port scheduler configuration parameter structure
243 * Handle to port scheduler instance upon success or NULL otherwise.
245 struct rte_sched_port *
246 rte_sched_port_config(struct rte_sched_port_params *params);
249 * Hierarchical scheduler port free
252 * Handle to port scheduler instance
255 rte_sched_port_free(struct rte_sched_port *port);
258 * Hierarchical scheduler subport configuration
261 * Handle to port scheduler instance
265 * Subport configuration parameters
267 * 0 upon success, error code otherwise
270 rte_sched_subport_config(struct rte_sched_port *port,
272 struct rte_sched_subport_params *params);
275 * Hierarchical scheduler pipe configuration
278 * Handle to port scheduler instance
282 * Pipe ID within subport
283 * @param pipe_profile
284 * ID of port-level pre-configured pipe profile
286 * 0 upon success, error code otherwise
289 rte_sched_pipe_config(struct rte_sched_port *port,
292 int32_t pipe_profile);
295 * Hierarchical scheduler memory footprint size per port
298 * Port scheduler configuration parameter structure
300 * Memory footprint size in bytes upon success, 0 otherwise
303 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params);
311 * Hierarchical scheduler subport statistics read
314 * Handle to port scheduler instance
318 * Pointer to pre-allocated subport statistics structure where the statistics
319 * counters should be stored
321 * Pointer to pre-allocated 4-entry array where the oversubscription status for
322 * each of the 4 subport traffic classes should be stored.
324 * 0 upon success, error code otherwise
327 rte_sched_subport_read_stats(struct rte_sched_port *port,
329 struct rte_sched_subport_stats *stats,
333 * Hierarchical scheduler queue statistics read
336 * Handle to port scheduler instance
338 * Queue ID within port scheduler
340 * Pointer to pre-allocated subport statistics structure where the statistics
341 * counters should be stored
343 * Pointer to pre-allocated variable where the current queue length
346 * 0 upon success, error code otherwise
349 rte_sched_queue_read_stats(struct rte_sched_port *port,
351 struct rte_sched_queue_stats *stats,
355 * Scheduler hierarchy path write to packet descriptor. Typically
356 * called by the packet classification stage.
359 * Packet descriptor handle
363 * Pipe ID within subport
364 * @param traffic_class
365 * Traffic class ID within pipe (0 .. 3)
367 * Queue ID within pipe traffic class (0 .. 3)
372 rte_sched_port_pkt_write(struct rte_mbuf *pkt,
373 uint32_t subport, uint32_t pipe, uint32_t traffic_class,
374 uint32_t queue, enum rte_meter_color color);
377 * Scheduler hierarchy path read from packet descriptor (struct
378 * rte_mbuf). Typically called as part of the hierarchical scheduler
379 * enqueue operation. The subport, pipe, traffic class and queue
380 * parameters need to be pre-allocated by the caller.
383 * Packet descriptor handle
387 * Pipe ID within subport
388 * @param traffic_class
389 * Traffic class ID within pipe (0 .. 3)
391 * Queue ID within pipe traffic class (0 .. 3)
395 rte_sched_port_pkt_read_tree_path(const struct rte_mbuf *pkt,
396 uint32_t *subport, uint32_t *pipe,
397 uint32_t *traffic_class, uint32_t *queue);
400 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
403 * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
404 * scheduler and returns the number of packets actually written. For
405 * each packet, the port scheduler queue to write the packet to is
406 * identified by reading the hierarchy path from the packet
407 * descriptor; if the queue is full or congested and the packet is not
408 * written to the queue, then the packet is automatically dropped
409 * without any action required from the caller.
412 * Handle to port scheduler instance
414 * Array storing the packet descriptor handles
416 * Number of packets to enqueue from the pkts array into the port scheduler
418 * Number of packets successfully enqueued
421 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
424 * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
425 * port scheduler and stores them in the pkts array and returns the
426 * number of packets actually read. The pkts array needs to be
427 * pre-allocated by the caller with at least n_pkts entries.
430 * Handle to port scheduler instance
432 * Pre-allocated packet descriptor array where the packets dequeued
434 * scheduler should be stored
436 * Number of packets to dequeue from the port scheduler
438 * Number of packets successfully dequeued and placed in the pkts array
441 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
447 #endif /* __INCLUDE_RTE_SCHED_H__ */