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 * Subport 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_subport_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 uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
132 /** Enforcement period for rates (measured in milliseconds) */
136 /** Subport statistics */
137 struct rte_sched_subport_stats {
138 /** Number of packets successfully written */
139 uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
141 /** Number of packets dropped */
142 uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
144 /** Number of bytes successfully written for each traffic class */
145 uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
147 /** Number of bytes dropped for each traffic class */
148 uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
151 /** Number of packets dropped by red */
152 uint32_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
157 * Pipe configuration parameters. The period and credits_per_period
158 * parameters are measured in bytes, with one byte meaning the time
159 * duration associated with the transmission of one byte on the
160 * physical medium of the output port, with pipe or pipe traffic class
161 * rate (measured as percentage of output port rate) determined as
162 * credits_per_period divided by period. One credit represents one
165 struct rte_sched_pipe_params {
166 /** Token bucket rate (measured in bytes per second) */
169 /** Token bucket size (measured in credits) */
172 /** Traffic class rates (measured in bytes per second) */
173 uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
175 /** Enforcement period (measured in milliseconds) */
178 /** Best-effort traffic class oversubscription weight */
179 uint8_t tc_ov_weight;
181 /** WRR weights of best-effort traffic class queues */
182 uint8_t wrr_weights[RTE_SCHED_BE_QUEUES_PER_PIPE];
185 /** Queue statistics */
186 struct rte_sched_queue_stats {
187 /** Packets successfully written */
190 /** Packets dropped */
191 uint32_t n_pkts_dropped;
194 /** Packets dropped by RED */
195 uint32_t n_pkts_red_dropped;
198 /** Bytes successfully written */
202 uint32_t n_bytes_dropped;
205 /** Port configuration parameters. */
206 struct rte_sched_port_params {
207 /** Name of the port to be associated */
213 /** Output port rate (measured in bytes per second) */
216 /** Maximum Ethernet frame size (measured in bytes).
217 * Should not include the framing overhead.
221 /** Framing overhead per packet (measured in bytes) */
222 uint32_t frame_overhead;
224 /** Number of subports */
225 uint32_t n_subports_per_port;
227 /** Number of subport_pipes */
228 uint32_t n_pipes_per_subport;
230 /** Packet queue size for each traffic class.
231 * All the pipes within the same subport share the similar
232 * configuration for the queues.
234 uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
236 /** Pipe profile table.
237 * Every pipe is configured using one of the profiles from this table.
239 struct rte_sched_pipe_params *pipe_profiles;
241 /** Profiles in the pipe profile table */
242 uint32_t n_pipe_profiles;
244 /** Max profiles allowed in the pipe profile table */
245 uint32_t n_max_pipe_profiles;
248 /** RED parameters */
249 struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][RTE_COLORS];
259 * Hierarchical scheduler port configuration
262 * Port scheduler configuration parameter structure
264 * Handle to port scheduler instance upon success or NULL otherwise.
266 struct rte_sched_port *
267 rte_sched_port_config(struct rte_sched_port_params *params);
270 * Hierarchical scheduler port free
273 * Handle to port scheduler instance
276 rte_sched_port_free(struct rte_sched_port *port);
280 * @b EXPERIMENTAL: this API may change without prior notice.
282 * Hierarchical scheduler pipe profile add
285 * Handle to port scheduler instance
287 * Pipe profile parameters
288 * @param pipe_profile_id
289 * Set to valid profile id when profile is added successfully.
291 * 0 upon success, error code otherwise
295 rte_sched_port_pipe_profile_add(struct rte_sched_port *port,
296 struct rte_sched_pipe_params *params,
297 uint32_t *pipe_profile_id);
300 * Hierarchical scheduler subport configuration
303 * Handle to port scheduler instance
307 * Subport configuration parameters
309 * 0 upon success, error code otherwise
312 rte_sched_subport_config(struct rte_sched_port *port,
314 struct rte_sched_subport_params *params);
317 * Hierarchical scheduler pipe configuration
320 * Handle to port scheduler instance
324 * Pipe ID within subport
325 * @param pipe_profile
326 * ID of port-level pre-configured pipe profile
328 * 0 upon success, error code otherwise
331 rte_sched_pipe_config(struct rte_sched_port *port,
334 int32_t pipe_profile);
337 * Hierarchical scheduler memory footprint size per port
340 * Port scheduler configuration parameter structure
342 * Memory footprint size in bytes upon success, 0 otherwise
345 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params);
353 * Hierarchical scheduler subport statistics read
356 * Handle to port scheduler instance
360 * Pointer to pre-allocated subport statistics structure where the statistics
361 * counters should be stored
363 * Pointer to pre-allocated RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE-entry array
364 * where the oversubscription status for each of the subport traffic classes
367 * 0 upon success, error code otherwise
370 rte_sched_subport_read_stats(struct rte_sched_port *port,
372 struct rte_sched_subport_stats *stats,
376 * Hierarchical scheduler queue statistics read
379 * Handle to port scheduler instance
381 * Queue ID within port scheduler
383 * Pointer to pre-allocated subport statistics structure where the statistics
384 * counters should be stored
386 * Pointer to pre-allocated variable where the current queue length
389 * 0 upon success, error code otherwise
392 rte_sched_queue_read_stats(struct rte_sched_port *port,
394 struct rte_sched_queue_stats *stats,
398 * Scheduler hierarchy path write to packet descriptor. Typically
399 * called by the packet classification stage.
402 * Handle to port scheduler instance
404 * Packet descriptor handle
408 * Pipe ID within subport
409 * @param traffic_class
410 * Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
412 * Queue ID within pipe traffic class, 0 for high priority TCs, and
413 * 0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
418 rte_sched_port_pkt_write(struct rte_sched_port *port,
419 struct rte_mbuf *pkt,
420 uint32_t subport, uint32_t pipe, uint32_t traffic_class,
421 uint32_t queue, enum rte_color color);
424 * Scheduler hierarchy path read from packet descriptor (struct
425 * rte_mbuf). Typically called as part of the hierarchical scheduler
426 * enqueue operation. The subport, pipe, traffic class and queue
427 * parameters need to be pre-allocated by the caller.
430 * Handle to port scheduler instance
432 * Packet descriptor handle
436 * Pipe ID within subport
437 * @param traffic_class
438 * Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
440 * Queue ID within pipe traffic class, 0 for high priority TCs, and
441 * 0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
444 rte_sched_port_pkt_read_tree_path(struct rte_sched_port *port,
445 const struct rte_mbuf *pkt,
446 uint32_t *subport, uint32_t *pipe,
447 uint32_t *traffic_class, uint32_t *queue);
450 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
453 * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
454 * scheduler and returns the number of packets actually written. For
455 * each packet, the port scheduler queue to write the packet to is
456 * identified by reading the hierarchy path from the packet
457 * descriptor; if the queue is full or congested and the packet is not
458 * written to the queue, then the packet is automatically dropped
459 * without any action required from the caller.
462 * Handle to port scheduler instance
464 * Array storing the packet descriptor handles
466 * Number of packets to enqueue from the pkts array into the port scheduler
468 * Number of packets successfully enqueued
471 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
474 * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
475 * port scheduler and stores them in the pkts array and returns the
476 * number of packets actually read. The pkts array needs to be
477 * pre-allocated by the caller with at least n_pkts entries.
480 * Handle to port scheduler instance
482 * Pre-allocated packet descriptor array where the packets dequeued
484 * scheduler should be stored
486 * Number of packets to dequeue from the port scheduler
488 * Number of packets successfully dequeued and placed in the pkts array
491 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
497 #endif /* __INCLUDE_RTE_SCHED_H__ */