1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2010-2014 Intel Corporation
5 #ifndef __INCLUDE_RTE_SCHED_H__
6 #define __INCLUDE_RTE_SCHED_H__
14 * RTE Hierarchical Scheduler
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.
20 * The scheduler supports thousands of packet queues grouped under a
23 * - Typical usage: output Ethernet port;
24 * - Multiple ports are scheduled in round robin order with
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;
40 * - Typical usage: individual user/subscriber;
41 * - Traffic shaping using the token bucket algorithm
42 * (one bucket per pipe);
44 * - Traffic classes of the same pipe handled in strict
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;
51 * - Typical usage: queue hosting packets from one or
52 * multiple connections of same traffic class belonging to
54 * - Weighted Round Robin (WRR) is used to service the
55 * queues within same pipe traffic class.
59 #include <sys/types.h>
60 #include <rte_compat.h>
62 #include <rte_meter.h>
64 /** Random Early Detection (RED) */
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.
75 * @see struct rte_sched_port_params
77 #define RTE_SCHED_QUEUES_PER_PIPE 16
79 /** Number of WRR queues for best-effort traffic class per pipe.
81 * @see struct rte_sched_pipe_params
83 #define RTE_SCHED_BE_QUEUES_PER_PIPE 4
85 /** Number of traffic classes per pipe (as well as subport).
88 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE 4
90 /** Best-effort traffic class ID
93 #define RTE_SCHED_TRAFFIC_CLASS_BE (RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE - 1)
95 /** Number of queues per pipe traffic class. Cannot be changed. */
96 #define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS 4
99 /** Maximum number of pipe profiles that can be defined per port.
100 * Compile-time configurable.
102 #ifndef RTE_SCHED_PIPE_PROFILES_PER_PORT
103 #define RTE_SCHED_PIPE_PROFILES_PER_PORT 256
107 * Ethernet framing overhead. Overhead fields per Ethernet frame:
108 * 1. Preamble: 7 bytes;
109 * 2. Start of Frame Delimiter (SFD): 1 byte;
110 * 3. Frame Check Sequence (FCS): 4 bytes;
111 * 4. Inter Frame Gap (IFG): 12 bytes.
113 * The FCS is considered overhead only if not included in the packet
114 * length (field pkt_len of struct rte_mbuf).
116 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
117 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT 24
121 * Subport configuration parameters. The period and credits_per_period
122 * parameters are measured in bytes, with one byte meaning the time
123 * duration associated with the transmission of one byte on the
124 * physical medium of the output port, with pipe or pipe traffic class
125 * rate (measured as percentage of output port rate) determined as
126 * credits_per_period divided by period. One credit represents one
129 struct rte_sched_subport_params {
130 /* Subport token bucket */
131 uint32_t tb_rate; /**< Rate (measured in bytes per second) */
132 uint32_t tb_size; /**< Size (measured in credits) */
134 /* Subport traffic classes */
135 uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
136 /**< Traffic class rates (measured in bytes per second) */
138 /**< Enforcement period for rates (measured in milliseconds) */
141 /** Subport statistics */
142 struct rte_sched_subport_stats {
144 uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
145 /**< Number of packets successfully written */
146 uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
147 /**< Number of packets dropped */
150 uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
151 /**< Number of bytes successfully written for each traffic class */
152 uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
153 /**< Number of bytes dropped for each traffic class */
156 uint32_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
157 /**< Number of packets dropped by red */
162 * Pipe configuration parameters. The period and credits_per_period
163 * parameters are measured in bytes, with one byte meaning the time
164 * duration associated with the transmission of one byte on the
165 * physical medium of the output port, with pipe or pipe traffic class
166 * rate (measured as percentage of output port rate) determined as
167 * credits_per_period divided by period. One credit represents one
170 struct rte_sched_pipe_params {
171 /* Pipe token bucket */
172 uint32_t tb_rate; /**< Rate (measured in bytes per second) */
173 uint32_t tb_size; /**< Size (measured in credits) */
175 /* Pipe traffic classes */
176 uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
177 /**< Traffic class rates (measured in bytes per second) */
179 /**< Enforcement period (measured in milliseconds) */
180 #ifdef RTE_SCHED_SUBPORT_TC_OV
181 uint8_t tc_ov_weight; /**< Weight Traffic class 3 oversubscription */
185 uint8_t wrr_weights[RTE_SCHED_BE_QUEUES_PER_PIPE]; /**< WRR weights */
188 /** Queue statistics */
189 struct rte_sched_queue_stats {
191 uint32_t n_pkts; /**< Packets successfully written */
192 uint32_t n_pkts_dropped; /**< Packets dropped */
194 uint32_t n_pkts_red_dropped; /**< Packets dropped by RED */
198 uint32_t n_bytes; /**< Bytes successfully written */
199 uint32_t n_bytes_dropped; /**< Bytes dropped */
202 /** Port configuration parameters. */
203 struct rte_sched_port_params {
204 const char *name; /**< String to be associated */
205 int socket; /**< CPU socket ID */
206 uint32_t rate; /**< Output port rate
207 * (measured in bytes per second) */
208 uint32_t mtu; /**< Maximum Ethernet frame size
209 * (measured in bytes).
210 * Should not include the framing overhead. */
211 uint32_t frame_overhead; /**< Framing overhead per packet
212 * (measured in bytes) */
213 uint32_t n_subports_per_port; /**< Number of subports */
214 uint32_t n_pipes_per_subport; /**< Number of pipes per subport */
215 uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
216 /**< Packet queue size for each traffic class.
217 * All queues within the same pipe traffic class have the same
218 * size. Queues from different pipes serving the same traffic
219 * class have the same size. */
220 struct rte_sched_pipe_params *pipe_profiles;
221 /**< Pipe profile table.
222 * Every pipe is configured using one of the profiles from this table. */
223 uint32_t n_pipe_profiles; /**< Profiles in the pipe profile table */
225 struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][RTE_COLORS]; /**< RED parameters */
235 * Hierarchical scheduler port configuration
238 * Port scheduler configuration parameter structure
240 * Handle to port scheduler instance upon success or NULL otherwise.
242 struct rte_sched_port *
243 rte_sched_port_config(struct rte_sched_port_params *params);
246 * Hierarchical scheduler port free
249 * Handle to port scheduler instance
252 rte_sched_port_free(struct rte_sched_port *port);
256 * @b EXPERIMENTAL: this API may change without prior notice.
258 * Hierarchical scheduler pipe profile add
261 * Handle to port scheduler instance
263 * Pipe profile parameters
264 * @param pipe_profile_id
265 * Set to valid profile id when profile is added successfully.
267 * 0 upon success, error code otherwise
271 rte_sched_port_pipe_profile_add(struct rte_sched_port *port,
272 struct rte_sched_pipe_params *params,
273 uint32_t *pipe_profile_id);
276 * Hierarchical scheduler subport configuration
279 * Handle to port scheduler instance
283 * Subport configuration parameters
285 * 0 upon success, error code otherwise
288 rte_sched_subport_config(struct rte_sched_port *port,
290 struct rte_sched_subport_params *params);
293 * Hierarchical scheduler pipe configuration
296 * Handle to port scheduler instance
300 * Pipe ID within subport
301 * @param pipe_profile
302 * ID of port-level pre-configured pipe profile
304 * 0 upon success, error code otherwise
307 rte_sched_pipe_config(struct rte_sched_port *port,
310 int32_t pipe_profile);
313 * Hierarchical scheduler memory footprint size per port
316 * Port scheduler configuration parameter structure
318 * Memory footprint size in bytes upon success, 0 otherwise
321 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params);
329 * Hierarchical scheduler subport statistics read
332 * Handle to port scheduler instance
336 * Pointer to pre-allocated subport statistics structure where the statistics
337 * counters should be stored
339 * Pointer to pre-allocated 4-entry array where the oversubscription status for
340 * each of the 4 subport traffic classes should be stored.
342 * 0 upon success, error code otherwise
345 rte_sched_subport_read_stats(struct rte_sched_port *port,
347 struct rte_sched_subport_stats *stats,
351 * Hierarchical scheduler queue statistics read
354 * Handle to port scheduler instance
356 * Queue ID within port scheduler
358 * Pointer to pre-allocated subport statistics structure where the statistics
359 * counters should be stored
361 * Pointer to pre-allocated variable where the current queue length
364 * 0 upon success, error code otherwise
367 rte_sched_queue_read_stats(struct rte_sched_port *port,
369 struct rte_sched_queue_stats *stats,
373 * Scheduler hierarchy path write to packet descriptor. Typically
374 * called by the packet classification stage.
377 * Handle to port scheduler instance
379 * Packet descriptor handle
383 * Pipe ID within subport
384 * @param traffic_class
385 * Traffic class ID within pipe (0 .. 3)
387 * Queue ID within pipe traffic class (0 .. 3)
392 rte_sched_port_pkt_write(struct rte_sched_port *port,
393 struct rte_mbuf *pkt,
394 uint32_t subport, uint32_t pipe, uint32_t traffic_class,
395 uint32_t queue, enum rte_color color);
398 * Scheduler hierarchy path read from packet descriptor (struct
399 * rte_mbuf). Typically called as part of the hierarchical scheduler
400 * enqueue operation. The subport, pipe, traffic class and queue
401 * parameters need to be pre-allocated by the caller.
404 * Handle to port scheduler instance
406 * Packet descriptor handle
410 * Pipe ID within subport
411 * @param traffic_class
412 * Traffic class ID within pipe (0 .. 3)
414 * Queue ID within pipe traffic class (0 .. 3)
418 rte_sched_port_pkt_read_tree_path(struct rte_sched_port *port,
419 const struct rte_mbuf *pkt,
420 uint32_t *subport, uint32_t *pipe,
421 uint32_t *traffic_class, uint32_t *queue);
424 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
427 * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
428 * scheduler and returns the number of packets actually written. For
429 * each packet, the port scheduler queue to write the packet to is
430 * identified by reading the hierarchy path from the packet
431 * descriptor; if the queue is full or congested and the packet is not
432 * written to the queue, then the packet is automatically dropped
433 * without any action required from the caller.
436 * Handle to port scheduler instance
438 * Array storing the packet descriptor handles
440 * Number of packets to enqueue from the pkts array into the port scheduler
442 * Number of packets successfully enqueued
445 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
448 * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
449 * port scheduler and stores them in the pkts array and returns the
450 * number of packets actually read. The pkts array needs to be
451 * pre-allocated by the caller with at least n_pkts entries.
454 * Handle to port scheduler instance
456 * Pre-allocated packet descriptor array where the packets dequeued
458 * scheduler should be stored
460 * Number of packets to dequeue from the port scheduler
462 * Number of packets successfully dequeued and placed in the pkts array
465 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
471 #endif /* __INCLUDE_RTE_SCHED_H__ */