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 from different
46 * users and traffic classes according to the Service Level Agreements (SLAs) defined
47 * for the current network node.
49 * The scheduler supports thousands of packet queues grouped under a 5-level hierarchy:
51 * - Typical usage: output Ethernet port;
52 * - Multiple ports are scheduled in round robin order with equal priority;
54 * - Typical usage: group of users;
55 * - Traffic shaping using the token bucket algorithm (one bucket per subport);
56 * - Upper limit enforced per traffic class at subport level;
57 * - Lower priority traffic classes able to reuse subport bandwidth currently
58 * unused by higher priority traffic classes of the same subport;
59 * - When any subport traffic class is oversubscribed (configuration time
60 * event), the usage of subport member pipes with high demand for that
61 * traffic class pipes is truncated to a dynamically adjusted value with no
62 * impact to low demand pipes;
64 * - Typical usage: individual user/subscriber;
65 * - Traffic shaping using the token bucket algorithm (one bucket per pipe);
67 * - Traffic classes of the same pipe handled in strict priority order;
68 * - Upper limit enforced per traffic class at the pipe level;
69 * - Lower priority traffic classes able to reuse pipe bandwidth currently
70 * unused by higher priority traffic classes of the same pipe;
72 * - Typical usage: queue hosting packets from one or multiple connections
73 * of same traffic class belonging to the same user;
74 * - Weighted Round Robin (WRR) is used to service the queues within same
79 #include <sys/types.h>
81 #include <rte_meter.h>
83 /** Random Early Detection (RED) */
88 /** Number of traffic classes per pipe (as well as subport). Cannot be changed. */
89 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE 4
91 /** Number of queues per pipe traffic class. Cannot be changed. */
92 #define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS 4
94 /** Number of queues per pipe. */
95 #define RTE_SCHED_QUEUES_PER_PIPE \
96 (RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE * \
97 RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS)
99 /** Maximum number of pipe profiles that can be defined per port. Compile-time configurable.*/
100 #ifndef RTE_SCHED_PIPE_PROFILES_PER_PORT
101 #define RTE_SCHED_PIPE_PROFILES_PER_PORT 256
104 /** Ethernet framing overhead. Overhead fields per Ethernet frame:
105 1. Preamble: 7 bytes;
106 2. Start of Frame Delimiter (SFD): 1 byte;
107 3. Frame Check Sequence (FCS): 4 bytes;
108 4. Inter Frame Gap (IFG): 12 bytes.
109 The FCS is considered overhead only if not included in the packet length (field pkt_len
110 of struct rte_mbuf). */
111 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
112 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT 24
115 /** Subport configuration parameters. The period and credits_per_period parameters are measured
116 in bytes, with one byte meaning the time duration associated with the transmission of one byte
117 on the physical medium of the output port, with pipe or pipe traffic class rate (measured as
118 percentage of output port rate) determined as credits_per_period divided by period. One credit
119 represents one byte. */
120 struct rte_sched_subport_params {
121 /* Subport token bucket */
122 uint32_t tb_rate; /**< Subport token bucket rate (measured in bytes per second) */
123 uint32_t tb_size; /**< Subport token bucket size (measured in credits) */
125 /* Subport traffic classes */
126 uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Subport traffic class rates (measured in bytes per second) */
127 uint32_t tc_period; /**< Enforcement period for traffic class rates (measured in milliseconds) */
130 /** Subport statistics */
131 struct rte_sched_subport_stats {
133 uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Number of packets successfully written to current
134 subport for each traffic class */
135 uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Number of packets dropped by the current
136 subport for each traffic class due to subport queues being full or congested*/
139 uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Number of bytes successfully written to current
140 subport for each traffic class*/
141 uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Number of bytes dropped by the current
142 subport for each traffic class due to subport queues being full or congested */
145 /** Pipe configuration parameters. The period and credits_per_period parameters are measured
146 in bytes, with one byte meaning the time duration associated with the transmission of one byte
147 on the physical medium of the output port, with pipe or pipe traffic class rate (measured as
148 percentage of output port rate) determined as credits_per_period divided by period. One credit
149 represents one byte. */
150 struct rte_sched_pipe_params {
151 /* Pipe token bucket */
152 uint32_t tb_rate; /**< Pipe token bucket rate (measured in bytes per second) */
153 uint32_t tb_size; /**< Pipe token bucket size (measured in credits) */
155 /* Pipe traffic classes */
156 uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Pipe traffic class rates (measured in bytes per second) */
157 uint32_t tc_period; /**< Enforcement period for pipe traffic class rates (measured in milliseconds) */
158 #ifdef RTE_SCHED_SUBPORT_TC_OV
159 uint8_t tc_ov_weight; /**< Weight for the current pipe in the event of subport traffic class 3 oversubscription */
163 uint8_t wrr_weights[RTE_SCHED_QUEUES_PER_PIPE]; /**< WRR weights for the queues of the current pipe */
166 /** Queue statistics */
167 struct rte_sched_queue_stats {
169 uint32_t n_pkts; /**< Number of packets successfully written to current queue */
170 uint32_t n_pkts_dropped; /**< Number of packets dropped due to current queue being full or congested */
173 uint32_t n_bytes; /**< Number of bytes successfully written to current queue */
174 uint32_t n_bytes_dropped; /**< Number of bytes dropped due to current queue being full or congested */
177 /** Port configuration parameters. */
178 struct rte_sched_port_params {
179 const char *name; /**< Literal string to be associated to the current port scheduler instance */
180 int socket; /**< CPU socket ID where the memory for port scheduler should be allocated */
181 uint32_t rate; /**< Output port rate (measured in bytes per second) */
182 uint32_t mtu; /**< Maximum Ethernet frame size (measured in bytes). Should not include the framing overhead. */
183 uint32_t frame_overhead; /**< Framing overhead per packet (measured in bytes) */
184 uint32_t n_subports_per_port; /**< Number of subports for the current port scheduler instance*/
185 uint32_t n_pipes_per_subport; /**< Number of pipes for each port scheduler subport */
186 uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE]; /**< Packet queue size for each traffic class. All queues
187 within the same pipe traffic class have the same size. Queues from
188 different pipes serving the same traffic class have the same size. */
189 struct rte_sched_pipe_params *pipe_profiles; /**< Pipe profile table defined for current port scheduler instance.
190 Every pipe of the current port scheduler is configured using one of the
191 profiles from this table. */
192 uint32_t n_pipe_profiles; /**< Number of profiles in the pipe profile table */
194 struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][e_RTE_METER_COLORS]; /**< RED parameters */
199 * Path through scheduler hierarchy
201 * Note: direct access to internal bitfields is deprecated to allow for future expansion.
202 * Use rte_sched_port_pkt_read/write API instead
204 struct rte_sched_port_hierarchy {
205 uint32_t queue:2; /**< Queue ID (0 .. 3) */
206 uint32_t traffic_class:2; /**< Traffic class ID (0 .. 3)*/
207 uint32_t pipe:20; /**< Pipe ID */
208 uint32_t subport:6; /**< Subport ID */
209 uint32_t color:2; /**< Color */
210 } __attribute__ ((deprecated));
218 * Hierarchical scheduler port configuration
221 * Port scheduler configuration parameter structure
223 * Handle to port scheduler instance upon success or NULL otherwise.
225 struct rte_sched_port *
226 rte_sched_port_config(struct rte_sched_port_params *params);
229 * Hierarchical scheduler port free
232 * Handle to port scheduler instance
235 rte_sched_port_free(struct rte_sched_port *port);
238 * Hierarchical scheduler subport configuration
241 * Handle to port scheduler instance
245 * Subport configuration parameters
247 * 0 upon success, error code otherwise
250 rte_sched_subport_config(struct rte_sched_port *port,
252 struct rte_sched_subport_params *params);
255 * Hierarchical scheduler pipe configuration
258 * Handle to port scheduler instance
262 * Pipe ID within subport
263 * @param pipe_profile
264 * ID of port-level pre-configured pipe profile
266 * 0 upon success, error code otherwise
269 rte_sched_pipe_config(struct rte_sched_port *port,
272 int32_t pipe_profile);
275 * Hierarchical scheduler memory footprint size per port
278 * Port scheduler configuration parameter structure
280 * Memory footprint size in bytes upon success, 0 otherwise
283 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params);
291 * Hierarchical scheduler subport statistics read
294 * Handle to port scheduler instance
298 * Pointer to pre-allocated subport statistics structure where the statistics
299 * counters should be stored
301 * Pointer to pre-allocated 4-entry array where the oversubscription status for
302 * each of the 4 subport traffic classes should be stored.
304 * 0 upon success, error code otherwise
307 rte_sched_subport_read_stats(struct rte_sched_port *port,
309 struct rte_sched_subport_stats *stats,
313 * Hierarchical scheduler queue statistics read
316 * Handle to port scheduler instance
318 * Queue ID within port scheduler
320 * Pointer to pre-allocated subport statistics structure where the statistics
321 * counters should be stored
323 * Pointer to pre-allocated variable where the current queue length should be stored.
325 * 0 upon success, error code otherwise
328 rte_sched_queue_read_stats(struct rte_sched_port *port,
330 struct rte_sched_queue_stats *stats,
334 * Scheduler hierarchy path write to packet descriptor. Typically called by the
335 * packet classification stage.
338 * Packet descriptor handle
342 * Pipe ID within subport
343 * @param traffic_class
344 * Traffic class ID within pipe (0 .. 3)
346 * Queue ID within pipe traffic class (0 .. 3)
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);
356 * Scheduler hierarchy path read from packet descriptor (struct rte_mbuf). Typically
357 * called as part of the hierarchical scheduler enqueue operation. The subport,
358 * pipe, traffic class and queue parameters need to be pre-allocated by the caller.
361 * Packet descriptor handle
365 * Pipe ID within subport
366 * @param traffic_class
367 * Traffic class ID within pipe (0 .. 3)
369 * Queue ID within pipe traffic class (0 .. 3)
373 rte_sched_port_pkt_read_tree_path(const struct rte_mbuf *pkt,
374 uint32_t *subport, uint32_t *pipe,
375 uint32_t *traffic_class, uint32_t *queue);
378 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
381 * Hierarchical scheduler port enqueue. Writes up to n_pkts to port scheduler and
382 * returns the number of packets actually written. For each packet, the port scheduler
383 * queue to write the packet to is identified by reading the hierarchy path from the
384 * packet descriptor; if the queue is full or congested and the packet is not written
385 * to the queue, then the packet is automatically dropped without any action required
389 * Handle to port scheduler instance
391 * Array storing the packet descriptor handles
393 * Number of packets to enqueue from the pkts array into the port scheduler
395 * Number of packets successfully enqueued
398 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
401 * Hierarchical scheduler port dequeue. Reads up to n_pkts from the port scheduler
402 * and stores them in the pkts array and returns the number of packets actually read.
403 * The pkts array needs to be pre-allocated by the caller with at least n_pkts entries.
406 * Handle to port scheduler instance
408 * Pre-allocated packet descriptor array where the packets dequeued from the port
409 * scheduler should be stored
411 * Number of packets to dequeue from the port scheduler
413 * Number of packets successfully dequeued and placed in the pkts array
416 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
422 #endif /* __INCLUDE_RTE_SCHED_H__ */