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 lowest priority traffic class (best-effort).
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).
86 * @see struct rte_sched_subport_params
87 * @see struct rte_sched_pipe_params
89 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE \
90 (RTE_SCHED_QUEUES_PER_PIPE - RTE_SCHED_BE_QUEUES_PER_PIPE + 1)
92 /** Best-effort traffic class ID
95 #define RTE_SCHED_TRAFFIC_CLASS_BE (RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE - 1)
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.
104 * The FCS is considered overhead only if not included in the packet
105 * length (field pkt_len of struct rte_mbuf).
107 * @see struct rte_sched_port_params
109 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
110 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT 24
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
122 struct rte_sched_pipe_params {
123 /** Token bucket rate (measured in bytes per second) */
126 /** Token bucket size (measured in credits) */
129 /** Traffic class rates (measured in bytes per second) */
130 uint64_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
132 /** Enforcement period (measured in milliseconds) */
135 /** Best-effort traffic class oversubscription weight */
136 uint8_t tc_ov_weight;
138 /** WRR weights of best-effort traffic class queues */
139 uint8_t wrr_weights[RTE_SCHED_BE_QUEUES_PER_PIPE];
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
151 struct rte_sched_subport_params {
152 /** Number of subport pipes.
153 * The subport can enable/allocate fewer pipes than the maximum
154 * number set through struct port_params::n_max_pipes_per_subport,
155 * as needed, to avoid memory allocation for the queues of the
156 * pipes that are not really needed.
158 uint32_t n_pipes_per_subport_enabled;
160 /** Packet queue size for each traffic class.
161 * All the pipes within the same subport share the similar
162 * configuration for the queues.
164 uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
166 /** Pipe profile table.
167 * Every pipe is configured using one of the profiles from this table.
169 struct rte_sched_pipe_params *pipe_profiles;
171 /** Profiles in the pipe profile table */
172 uint32_t n_pipe_profiles;
174 /** Max allowed profiles in the pipe profile table */
175 uint32_t n_max_pipe_profiles;
178 /** RED parameters */
179 struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][RTE_COLORS];
183 struct rte_sched_subport_profile_params {
184 /** Token bucket rate (measured in bytes per second) */
187 /** Token bucket size (measured in credits) */
190 /** Traffic class rates (measured in bytes per second) */
191 uint64_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
193 /** Enforcement period for rates (measured in milliseconds) */
197 /** Subport statistics */
198 struct rte_sched_subport_stats {
199 /** Number of packets successfully written */
200 uint64_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
202 /** Number of packets dropped */
203 uint64_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
205 /** Number of bytes successfully written for each traffic class */
206 uint64_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
208 /** Number of bytes dropped for each traffic class */
209 uint64_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
212 /** Number of packets dropped by red */
213 uint64_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
217 /** Queue statistics */
218 struct rte_sched_queue_stats {
219 /** Packets successfully written */
222 /** Packets dropped */
223 uint64_t n_pkts_dropped;
226 /** Packets dropped by RED */
227 uint64_t n_pkts_red_dropped;
230 /** Bytes successfully written */
234 uint64_t n_bytes_dropped;
237 /** Port configuration parameters. */
238 struct rte_sched_port_params {
239 /** Name of the port to be associated */
245 /** Output port rate (measured in bytes per second) */
248 /** Maximum Ethernet frame size (measured in bytes).
249 * Should not include the framing overhead.
253 /** Framing overhead per packet (measured in bytes) */
254 uint32_t frame_overhead;
256 /** Number of subports */
257 uint32_t n_subports_per_port;
259 /** subport profile table.
260 * Every pipe is configured using one of the profiles from this table.
262 struct rte_sched_subport_profile_params *subport_profiles;
264 /** Profiles in the pipe profile table */
265 uint32_t n_subport_profiles;
267 /** Max allowed profiles in the pipe profile table */
268 uint32_t n_max_subport_profiles;
270 /** Maximum number of subport pipes.
271 * This parameter is used to reserve a fixed number of bits
272 * in struct rte_mbuf::sched.queue_id for the pipe_id for all
273 * the subports of the same port.
275 uint32_t n_pipes_per_subport;
284 * Hierarchical scheduler port configuration
287 * Port scheduler configuration parameter structure
289 * Handle to port scheduler instance upon success or NULL otherwise.
291 struct rte_sched_port *
292 rte_sched_port_config(struct rte_sched_port_params *params);
295 * Hierarchical scheduler port free
298 * Handle to port scheduler instance
301 rte_sched_port_free(struct rte_sched_port *port);
304 * Hierarchical scheduler pipe profile add
307 * Handle to port scheduler instance
311 * Pipe profile parameters
312 * @param pipe_profile_id
313 * Set to valid profile id when profile is added successfully.
315 * 0 upon success, error code otherwise
318 rte_sched_subport_pipe_profile_add(struct rte_sched_port *port,
320 struct rte_sched_pipe_params *params,
321 uint32_t *pipe_profile_id);
325 * @b EXPERIMENTAL: this API may change without prior notice.
327 * Hierarchical scheduler subport bandwidth profile add
328 * Note that this function is safe to use in runtime for adding new
329 * subport bandwidth profile as it doesn't have any impact on hiearchical
330 * structure of the scheduler.
332 * Handle to port scheduler instance
334 * Subport bandwidth profile
335 * @param subport_profile_id
338 * 0 upon success, error code otherwise
342 rte_sched_port_subport_profile_add(struct rte_sched_port *port,
343 struct rte_sched_subport_profile_params *profile,
344 uint32_t *subport_profile_id);
347 * Hierarchical scheduler subport configuration
348 * Note that this function is safe to use at runtime
349 * to configure subport bandwidth profile.
351 * Handle to port scheduler instance
355 * Subport configuration parameters. Must be non-NULL
356 * for first invocation (i.e initialization) for a given
357 * subport. Ignored (recommended value is NULL) for all
358 * subsequent invocation on the same subport.
359 * @param subport_profile_id
360 * ID of subport bandwidth profile
362 * 0 upon success, error code otherwise
365 rte_sched_subport_config(struct rte_sched_port *port,
367 struct rte_sched_subport_params *params,
368 uint32_t subport_profile_id);
371 * Hierarchical scheduler pipe configuration
374 * Handle to port scheduler instance
378 * Pipe ID within subport
379 * @param pipe_profile
380 * ID of subport-level pre-configured pipe profile
382 * 0 upon success, error code otherwise
385 rte_sched_pipe_config(struct rte_sched_port *port,
388 int32_t pipe_profile);
391 * Hierarchical scheduler memory footprint size per port
394 * Port scheduler configuration parameter structure
395 * @param subport_params
396 * Array of subport parameter structures
398 * Memory footprint size in bytes upon success, 0 otherwise
401 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *port_params,
402 struct rte_sched_subport_params **subport_params);
409 * Hierarchical scheduler subport statistics read
412 * Handle to port scheduler instance
416 * Pointer to pre-allocated subport statistics structure where the statistics
417 * counters should be stored
419 * Pointer to pre-allocated RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE-entry array
420 * where the oversubscription status for each of the subport traffic classes
423 * 0 upon success, error code otherwise
426 rte_sched_subport_read_stats(struct rte_sched_port *port,
428 struct rte_sched_subport_stats *stats,
432 * Hierarchical scheduler queue statistics read
435 * Handle to port scheduler instance
437 * Queue ID within port scheduler
439 * Pointer to pre-allocated subport statistics structure where the statistics
440 * counters should be stored
442 * Pointer to pre-allocated variable where the current queue length
445 * 0 upon success, error code otherwise
448 rte_sched_queue_read_stats(struct rte_sched_port *port,
450 struct rte_sched_queue_stats *stats,
454 * Scheduler hierarchy path write to packet descriptor. Typically
455 * called by the packet classification stage.
458 * Handle to port scheduler instance
460 * Packet descriptor handle
464 * Pipe ID within subport
465 * @param traffic_class
466 * Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
468 * Queue ID within pipe traffic class, 0 for high priority TCs, and
469 * 0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
474 rte_sched_port_pkt_write(struct rte_sched_port *port,
475 struct rte_mbuf *pkt,
476 uint32_t subport, uint32_t pipe, uint32_t traffic_class,
477 uint32_t queue, enum rte_color color);
480 * Scheduler hierarchy path read from packet descriptor (struct
481 * rte_mbuf). Typically called as part of the hierarchical scheduler
482 * enqueue operation. The subport, pipe, traffic class and queue
483 * parameters need to be pre-allocated by the caller.
486 * Handle to port scheduler instance
488 * Packet descriptor handle
492 * Pipe ID within subport
493 * @param traffic_class
494 * Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
496 * Queue ID within pipe traffic class, 0 for high priority TCs, and
497 * 0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
500 rte_sched_port_pkt_read_tree_path(struct rte_sched_port *port,
501 const struct rte_mbuf *pkt,
502 uint32_t *subport, uint32_t *pipe,
503 uint32_t *traffic_class, uint32_t *queue);
506 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
509 * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
510 * scheduler and returns the number of packets actually written. For
511 * each packet, the port scheduler queue to write the packet to is
512 * identified by reading the hierarchy path from the packet
513 * descriptor; if the queue is full or congested and the packet is not
514 * written to the queue, then the packet is automatically dropped
515 * without any action required from the caller.
518 * Handle to port scheduler instance
520 * Array storing the packet descriptor handles
522 * Number of packets to enqueue from the pkts array into the port scheduler
524 * Number of packets successfully enqueued
527 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
530 * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
531 * port scheduler and stores them in the pkts array and returns the
532 * number of packets actually read. The pkts array needs to be
533 * pre-allocated by the caller with at least n_pkts entries.
536 * Handle to port scheduler instance
538 * Pre-allocated packet descriptor array where the packets dequeued
540 * scheduler should be stored
542 * Number of packets to dequeue from the port scheduler
544 * Number of packets successfully dequeued and placed in the pkts array
547 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
553 #endif /* __INCLUDE_RTE_SCHED_H__ */