lib/librte_sched/rte_sched.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2014 Intel Corporation
   3  */
   4
   5 #ifndef __INCLUDE_RTE_SCHED_H__
   6 #define __INCLUDE_RTE_SCHED_H__
   7
   8 #ifdef __cplusplus
   9 extern "C" {
  10 #endif
  11
  12 /**
  13  * @file
  14  * RTE Hierarchical Scheduler
  15  *
  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.
  19  *
  20  * The scheduler supports thousands of packet queues grouped under a
  21  * 5-level hierarchy:
  22  *     1. Port:
  23  *           - Typical usage: output Ethernet port;
  24  *           - Multiple ports are scheduled in round robin order with
  25  *          equal priority;
  26  *     2. Subport:
  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;
  39  *     3. Pipe:
  40  *           - Typical usage: individual user/subscriber;
  41  *           - Traffic shaping using the token bucket algorithm
  42  *          (one bucket per pipe);
  43  *     4. Traffic class:
  44  *           - Traffic classes of the same pipe handled in strict
  45  *          priority order;
  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;
  50  *     5. Queue:
  51  *           - Typical usage: queue hosting packets from one or
  52  *          multiple connections of same traffic class belonging to
  53  *          the same user;
  54  *           - Weighted Round Robin (WRR) is used to service the
  55  *          queues within same pipe lowest priority traffic class (best-effort).
  56  *
  57  */
  58
  59 #include <sys/types.h>
  60 #include <rte_compat.h>
  61 #include <rte_mbuf.h>
  62 #include <rte_meter.h>
  63
  64 /** Random Early Detection (RED) */
  65 #ifdef RTE_SCHED_RED
  66 #include "rte_red.h"
  67 #endif
  68
  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.
  73  * Can not change.
  74  *
  75  * @see struct rte_sched_port_params
  76  */
  77 #define RTE_SCHED_QUEUES_PER_PIPE    16
  78
  79 /** Number of WRR queues for best-effort traffic class per pipe.
  80  *
  81  * @see struct rte_sched_pipe_params
  82  */
  83 #define RTE_SCHED_BE_QUEUES_PER_PIPE    4
  84
  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
  88  */
  89 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE    \
  90 (RTE_SCHED_QUEUES_PER_PIPE - RTE_SCHED_BE_QUEUES_PER_PIPE + 1)
  91
  92 /** Best-effort traffic class ID
  93  * Can not change.
  94  */
  95 #define RTE_SCHED_TRAFFIC_CLASS_BE    (RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE - 1)
  96
  97 /** Number of queues per pipe traffic class. Cannot be changed. */
  98 #define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS    4
  99
 100
 101 /** Maximum number of pipe profiles that can be defined per port.
 102  * Compile-time configurable.
 103  */
 104 #ifndef RTE_SCHED_PIPE_PROFILES_PER_PORT
 105 #define RTE_SCHED_PIPE_PROFILES_PER_PORT      256
 106 #endif
 107
 108 /*
 109  * Ethernet framing overhead. Overhead fields per Ethernet frame:
 110  * 1. Preamble:                             7 bytes;
 111  * 2. Start of Frame Delimiter (SFD):       1 byte;
 112  * 3. Frame Check Sequence (FCS):           4 bytes;
 113  * 4. Inter Frame Gap (IFG):               12 bytes.
 114  *
 115  * The FCS is considered overhead only if not included in the packet
 116  * length (field pkt_len of struct rte_mbuf).
 117  *
 118  * @see struct rte_sched_port_params
 119  */
 120 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
 121 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT      24
 122 #endif
 123
 124 /*
 125  * Subport configuration parameters. The period and credits_per_period
 126  * parameters are measured in bytes, with one byte meaning the time
 127  * duration associated with the transmission of one byte on the
 128  * physical medium of the output port, with pipe or pipe traffic class
 129  * rate (measured as percentage of output port rate) determined as
 130  * credits_per_period divided by period. One credit represents one
 131  * byte.
 132  */
 133 struct rte_sched_subport_params {
 134         /** Token bucket rate (measured in bytes per second) */
 135         uint32_t tb_rate;
 136
 137         /** Token bucket size (measured in credits) */
 138         uint32_t tb_size;
 139
 140         /** Traffic class rates (measured in bytes per second) */
 141         uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 142
 143         /** Enforcement period for rates (measured in milliseconds) */
 144         uint32_t tc_period;
 145 };
 146
 147 /** Subport statistics */
 148 struct rte_sched_subport_stats {
 149         /** Number of packets successfully written */
 150         uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 151
 152         /** Number of packets dropped */
 153         uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 154
 155         /** Number of bytes successfully written for each traffic class */
 156         uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 157
 158         /** Number of bytes dropped for each traffic class */
 159         uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 160
 161 #ifdef RTE_SCHED_RED
 162         /** Number of packets dropped by red */
 163         uint32_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 164 #endif
 165 };
 166
 167 /*
 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
 174  * byte.
 175  */
 176 struct rte_sched_pipe_params {
 177         /** Token bucket rate (measured in bytes per second) */
 178         uint32_t tb_rate;
 179
 180         /** Token bucket size (measured in credits) */
 181         uint32_t tb_size;
 182
 183         /** Traffic class rates (measured in bytes per second) */
 184         uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 185
 186         /** Enforcement period (measured in milliseconds) */
 187         uint32_t tc_period;
 188
 189         /** Best-effort traffic class oversubscription weight */
 190         uint8_t tc_ov_weight;
 191
 192         /** WRR weights of best-effort traffic class queues */
 193         uint8_t wrr_weights[RTE_SCHED_BE_QUEUES_PER_PIPE];
 194 };
 195
 196 /** Queue statistics */
 197 struct rte_sched_queue_stats {
 198         /** Packets successfully written */
 199         uint32_t n_pkts;
 200
 201         /** Packets dropped */
 202         uint32_t n_pkts_dropped;
 203
 204 #ifdef RTE_SCHED_RED
 205         /** Packets dropped by RED */
 206         uint32_t n_pkts_red_dropped;
 207 #endif
 208
 209         /** Bytes successfully written */
 210         uint32_t n_bytes;
 211
 212         /** Bytes dropped */
 213         uint32_t n_bytes_dropped;
 214 };
 215
 216 /** Port configuration parameters. */
 217 struct rte_sched_port_params {
 218         /** Name of the port to be associated */
 219         const char *name;
 220
 221         /** CPU socket ID */
 222         int socket;
 223
 224         /** Output port rate (measured in bytes per second) */
 225         uint32_t rate;
 226
 227         /** Maximum Ethernet frame size (measured in bytes).
 228          * Should not include the framing overhead.
 229          */
 230         uint32_t mtu;
 231
 232         /** Framing overhead per packet (measured in bytes) */
 233         uint32_t frame_overhead;
 234
 235         /** Number of subports */
 236         uint32_t n_subports_per_port;
 237
 238         /** Number of subport_pipes */
 239         uint32_t n_pipes_per_subport;
 240
 241         /** Packet queue size for each traffic class.
 242          * All the pipes within the same subport share the similar
 243          * configuration for the queues.
 244          */
 245         uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 246
 247         /** Pipe profile table.
 248          * Every pipe is configured using one of the profiles from this table.
 249          */
 250         struct rte_sched_pipe_params *pipe_profiles;
 251
 252         /** Profiles in the pipe profile table */
 253         uint32_t n_pipe_profiles;
 254
 255         /** Max profiles allowed in the pipe profile table */
 256         uint32_t n_max_pipe_profiles;
 257
 258 #ifdef RTE_SCHED_RED
 259         /** RED parameters */
 260         struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][RTE_COLORS];
 261 #endif
 262 };
 263
 264 /*
 265  * Configuration
 266  *
 267  ***/
 268
 269 /**
 270  * Hierarchical scheduler port configuration
 271  *
 272  * @param params
 273  *   Port scheduler configuration parameter structure
 274  * @return
 275  *   Handle to port scheduler instance upon success or NULL otherwise.
 276  */
 277 struct rte_sched_port *
 278 rte_sched_port_config(struct rte_sched_port_params *params);
 279
 280 /**
 281  * Hierarchical scheduler port free
 282  *
 283  * @param port
 284  *   Handle to port scheduler instance
 285  */
 286 void
 287 rte_sched_port_free(struct rte_sched_port *port);
 288
 289 /**
 290  * @warning
 291  * @b EXPERIMENTAL: this API may change without prior notice.
 292  *
 293  * Hierarchical scheduler pipe profile add
 294  *
 295  * @param port
 296  *   Handle to port scheduler instance
 297  * @param params
 298  *   Pipe profile parameters
 299  * @param pipe_profile_id
 300  *   Set to valid profile id when profile is added successfully.
 301  * @return
 302  *   0 upon success, error code otherwise
 303  */
 304 __rte_experimental
 305 int
 306 rte_sched_port_pipe_profile_add(struct rte_sched_port *port,
 307         struct rte_sched_pipe_params *params,
 308         uint32_t *pipe_profile_id);
 309
 310 /**
 311  * Hierarchical scheduler subport configuration
 312  *
 313  * @param port
 314  *   Handle to port scheduler instance
 315  * @param subport_id
 316  *   Subport ID
 317  * @param params
 318  *   Subport configuration parameters
 319  * @return
 320  *   0 upon success, error code otherwise
 321  */
 322 int
 323 rte_sched_subport_config(struct rte_sched_port *port,
 324         uint32_t subport_id,
 325         struct rte_sched_subport_params *params);
 326
 327 /**
 328  * Hierarchical scheduler pipe configuration
 329  *
 330  * @param port
 331  *   Handle to port scheduler instance
 332  * @param subport_id
 333  *   Subport ID
 334  * @param pipe_id
 335  *   Pipe ID within subport
 336  * @param pipe_profile
 337  *   ID of port-level pre-configured pipe profile
 338  * @return
 339  *   0 upon success, error code otherwise
 340  */
 341 int
 342 rte_sched_pipe_config(struct rte_sched_port *port,
 343         uint32_t subport_id,
 344         uint32_t pipe_id,
 345         int32_t pipe_profile);
 346
 347 /**
 348  * Hierarchical scheduler memory footprint size per port
 349  *
 350  * @param params
 351  *   Port scheduler configuration parameter structure
 352  * @return
 353  *   Memory footprint size in bytes upon success, 0 otherwise
 354  */
 355 uint32_t
 356 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params);
 357
 358 /*
 359  * Statistics
 360  *
 361  ***/
 362
 363 /**
 364  * Hierarchical scheduler subport statistics read
 365  *
 366  * @param port
 367  *   Handle to port scheduler instance
 368  * @param subport_id
 369  *   Subport ID
 370  * @param stats
 371  *   Pointer to pre-allocated subport statistics structure where the statistics
 372  *   counters should be stored
 373  * @param tc_ov
 374  *   Pointer to pre-allocated RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE-entry array
 375  *   where the oversubscription status for each of the subport traffic classes
 376  *   should be stored.
 377  * @return
 378  *   0 upon success, error code otherwise
 379  */
 380 int
 381 rte_sched_subport_read_stats(struct rte_sched_port *port,
 382         uint32_t subport_id,
 383         struct rte_sched_subport_stats *stats,
 384         uint32_t *tc_ov);
 385
 386 /**
 387  * Hierarchical scheduler queue statistics read
 388  *
 389  * @param port
 390  *   Handle to port scheduler instance
 391  * @param queue_id
 392  *   Queue ID within port scheduler
 393  * @param stats
 394  *   Pointer to pre-allocated subport statistics structure where the statistics
 395  *   counters should be stored
 396  * @param qlen
 397  *   Pointer to pre-allocated variable where the current queue length
 398  *   should be stored.
 399  * @return
 400  *   0 upon success, error code otherwise
 401  */
 402 int
 403 rte_sched_queue_read_stats(struct rte_sched_port *port,
 404         uint32_t queue_id,
 405         struct rte_sched_queue_stats *stats,
 406         uint16_t *qlen);
 407
 408 /**
 409  * Scheduler hierarchy path write to packet descriptor. Typically
 410  * called by the packet classification stage.
 411  *
 412  * @param port
 413  *   Handle to port scheduler instance
 414  * @param pkt
 415  *   Packet descriptor handle
 416  * @param subport
 417  *   Subport ID
 418  * @param pipe
 419  *   Pipe ID within subport
 420  * @param traffic_class
 421  *   Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
 422  * @param queue
 423  *   Queue ID within pipe traffic class, 0 for high priority TCs, and
 424  *   0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
 425  * @param color
 426  *   Packet color set
 427  */
 428 void
 429 rte_sched_port_pkt_write(struct rte_sched_port *port,
 430                          struct rte_mbuf *pkt,
 431                          uint32_t subport, uint32_t pipe, uint32_t traffic_class,
 432                          uint32_t queue, enum rte_color color);
 433
 434 /**
 435  * Scheduler hierarchy path read from packet descriptor (struct
 436  * rte_mbuf). Typically called as part of the hierarchical scheduler
 437  * enqueue operation. The subport, pipe, traffic class and queue
 438  * parameters need to be pre-allocated by the caller.
 439  *
 440  * @param port
 441  *   Handle to port scheduler instance
 442  * @param pkt
 443  *   Packet descriptor handle
 444  * @param subport
 445  *   Subport ID
 446  * @param pipe
 447  *   Pipe ID within subport
 448  * @param traffic_class
 449  *   Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
 450  * @param queue
 451  *   Queue ID within pipe traffic class, 0 for high priority TCs, and
 452  *   0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
 453  */
 454 void
 455 rte_sched_port_pkt_read_tree_path(struct rte_sched_port *port,
 456                                   const struct rte_mbuf *pkt,
 457                                   uint32_t *subport, uint32_t *pipe,
 458                                   uint32_t *traffic_class, uint32_t *queue);
 459
 460 enum rte_color
 461 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
 462
 463 /**
 464  * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
 465  * scheduler and returns the number of packets actually written. For
 466  * each packet, the port scheduler queue to write the packet to is
 467  * identified by reading the hierarchy path from the packet
 468  * descriptor; if the queue is full or congested and the packet is not
 469  * written to the queue, then the packet is automatically dropped
 470  * without any action required from the caller.
 471  *
 472  * @param port
 473  *   Handle to port scheduler instance
 474  * @param pkts
 475  *   Array storing the packet descriptor handles
 476  * @param n_pkts
 477  *   Number of packets to enqueue from the pkts array into the port scheduler
 478  * @return
 479  *   Number of packets successfully enqueued
 480  */
 481 int
 482 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
 483
 484 /**
 485  * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
 486  * port scheduler and stores them in the pkts array and returns the
 487  * number of packets actually read.  The pkts array needs to be
 488  * pre-allocated by the caller with at least n_pkts entries.
 489  *
 490  * @param port
 491  *   Handle to port scheduler instance
 492  * @param pkts
 493  *   Pre-allocated packet descriptor array where the packets dequeued
 494  *   from the port
 495  *   scheduler should be stored
 496  * @param n_pkts
 497  *   Number of packets to dequeue from the port scheduler
 498  * @return
 499  *   Number of packets successfully dequeued and placed in the pkts array
 500  */
 501 int
 502 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
 503
 504 #ifdef __cplusplus
 505 }
 506 #endif
 507
 508 #endif /* __INCLUDE_RTE_SCHED_H__ */