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 /*
  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.
 103  *
 104  * The FCS is considered overhead only if not included in the packet
 105  * length (field pkt_len of struct rte_mbuf).
 106  *
 107  * @see struct rte_sched_port_params
 108  */
 109 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
 110 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT      24
 111 #endif
 112
 113 /*
 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
 120  * byte.
 121  */
 122 struct rte_sched_pipe_params {
 123         /** Token bucket rate (measured in bytes per second) */
 124         uint64_t tb_rate;
 125
 126         /** Token bucket size (measured in credits) */
 127         uint64_t tb_size;
 128
 129         /** Traffic class rates (measured in bytes per second) */
 130         uint64_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 131
 132         /** Enforcement period (measured in milliseconds) */
 133         uint64_t tc_period;
 134
 135         /** Best-effort traffic class oversubscription weight */
 136         uint8_t tc_ov_weight;
 137
 138         /** WRR weights of best-effort traffic class queues */
 139         uint8_t wrr_weights[RTE_SCHED_BE_QUEUES_PER_PIPE];
 140 };
 141
 142 /*
 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
 149  * byte.
 150  */
 151 struct rte_sched_subport_params {
 152         /** Token bucket rate (measured in bytes per second) */
 153         uint64_t tb_rate;
 154
 155         /** Token bucket size (measured in credits) */
 156         uint64_t tb_size;
 157
 158         /** Traffic class rates (measured in bytes per second) */
 159         uint64_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 160
 161         /** Enforcement period for rates (measured in milliseconds) */
 162         uint64_t tc_period;
 163
 164         /** Number of subport pipes.
 165          * The subport can enable/allocate fewer pipes than the maximum
 166          * number set through struct port_params::n_max_pipes_per_subport,
 167          * as needed, to avoid memory allocation for the queues of the
 168          * pipes that are not really needed.
 169          */
 170         uint32_t n_pipes_per_subport_enabled;
 171
 172         /** Packet queue size for each traffic class.
 173          * All the pipes within the same subport share the similar
 174          * configuration for the queues.
 175          */
 176         uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 177
 178         /** Pipe profile table.
 179          * Every pipe is configured using one of the profiles from this table.
 180          */
 181         struct rte_sched_pipe_params *pipe_profiles;
 182
 183         /** Profiles in the pipe profile table */
 184         uint32_t n_pipe_profiles;
 185
 186         /** Max allowed profiles in the pipe profile table */
 187         uint32_t n_max_pipe_profiles;
 188
 189 #ifdef RTE_SCHED_RED
 190         /** RED parameters */
 191         struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][RTE_COLORS];
 192 #endif
 193 };
 194
 195 struct rte_sched_subport_profile_params {
 196         /** Token bucket rate (measured in bytes per second) */
 197         uint64_t tb_rate;
 198
 199         /** Token bucket size (measured in credits) */
 200         uint64_t tb_size;
 201
 202         /** Traffic class rates (measured in bytes per second) */
 203         uint64_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 204
 205         /** Enforcement period for rates (measured in milliseconds) */
 206         uint64_t tc_period;
 207 };
 208
 209 /** Subport statistics */
 210 struct rte_sched_subport_stats {
 211         /** Number of packets successfully written */
 212         uint64_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 213
 214         /** Number of packets dropped */
 215         uint64_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 216
 217         /** Number of bytes successfully written for each traffic class */
 218         uint64_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 219
 220         /** Number of bytes dropped for each traffic class */
 221         uint64_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 222
 223 #ifdef RTE_SCHED_RED
 224         /** Number of packets dropped by red */
 225         uint64_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 226 #endif
 227 };
 228
 229 /** Queue statistics */
 230 struct rte_sched_queue_stats {
 231         /** Packets successfully written */
 232         uint64_t n_pkts;
 233
 234         /** Packets dropped */
 235         uint64_t n_pkts_dropped;
 236
 237 #ifdef RTE_SCHED_RED
 238         /** Packets dropped by RED */
 239         uint64_t n_pkts_red_dropped;
 240 #endif
 241
 242         /** Bytes successfully written */
 243         uint64_t n_bytes;
 244
 245         /** Bytes dropped */
 246         uint64_t n_bytes_dropped;
 247 };
 248
 249 /** Port configuration parameters. */
 250 struct rte_sched_port_params {
 251         /** Name of the port to be associated */
 252         const char *name;
 253
 254         /** CPU socket ID */
 255         int socket;
 256
 257         /** Output port rate (measured in bytes per second) */
 258         uint64_t rate;
 259
 260         /** Maximum Ethernet frame size (measured in bytes).
 261          * Should not include the framing overhead.
 262          */
 263         uint32_t mtu;
 264
 265         /** Framing overhead per packet (measured in bytes) */
 266         uint32_t frame_overhead;
 267
 268         /** Number of subports */
 269         uint32_t n_subports_per_port;
 270
 271         /** subport profile table.
 272          * Every pipe is configured using one of the profiles from this table.
 273          */
 274         struct rte_sched_subport_profile_params *subport_profiles;
 275
 276         /** Profiles in the pipe profile table */
 277         uint32_t n_subport_profiles;
 278
 279         /** Max allowed profiles in the pipe profile table */
 280         uint32_t n_max_subport_profiles;
 281
 282         /** Maximum number of subport pipes.
 283          * This parameter is used to reserve a fixed number of bits
 284          * in struct rte_mbuf::sched.queue_id for the pipe_id for all
 285          * the subports of the same port.
 286          */
 287         uint32_t n_pipes_per_subport;
 288 };
 289
 290 /*
 291  * Configuration
 292  *
 293  ***/
 294
 295 /**
 296  * Hierarchical scheduler port configuration
 297  *
 298  * @param params
 299  *   Port scheduler configuration parameter structure
 300  * @return
 301  *   Handle to port scheduler instance upon success or NULL otherwise.
 302  */
 303 struct rte_sched_port *
 304 rte_sched_port_config(struct rte_sched_port_params *params);
 305
 306 /**
 307  * Hierarchical scheduler port free
 308  *
 309  * @param port
 310  *   Handle to port scheduler instance
 311  */
 312 void
 313 rte_sched_port_free(struct rte_sched_port *port);
 314
 315 /**
 316  * @warning
 317  * @b EXPERIMENTAL: this API may change without prior notice.
 318  *
 319  * Hierarchical scheduler pipe profile add
 320  *
 321  * @param port
 322  *   Handle to port scheduler instance
 323  * @param subport_id
 324  *   Subport ID
 325  * @param params
 326  *   Pipe profile parameters
 327  * @param pipe_profile_id
 328  *   Set to valid profile id when profile is added successfully.
 329  * @return
 330  *   0 upon success, error code otherwise
 331  */
 332 __rte_experimental
 333 int
 334 rte_sched_subport_pipe_profile_add(struct rte_sched_port *port,
 335         uint32_t subport_id,
 336         struct rte_sched_pipe_params *params,
 337         uint32_t *pipe_profile_id);
 338
 339 /**
 340  * @warning
 341  * @b EXPERIMENTAL: this API may change without prior notice.
 342  *
 343  * Hierarchical scheduler subport bandwidth profile add
 344  * Note that this function is safe to use in runtime for adding new
 345  * subport bandwidth profile as it doesn't have any impact on hiearchical
 346  * structure of the scheduler.
 347  * @param port
 348  *   Handle to port scheduler instance
 349  * @param profile
 350  *   Subport bandwidth profile
 351  * @param subport_profile_id
 352  *   Subport profile id
 353  * @return
 354  *   0 upon success, error code otherwise
 355  */
 356 __rte_experimental
 357 int
 358 rte_sched_port_subport_profile_add(struct rte_sched_port *port,
 359         struct rte_sched_subport_profile_params *profile,
 360         uint32_t *subport_profile_id);
 361
 362 /**
 363  * Hierarchical scheduler subport configuration
 364  * Note that this function is safe to use at runtime
 365  * to configure subport bandwidth profile.
 366  * @param port
 367  *   Handle to port scheduler instance
 368  * @param subport_id
 369  *   Subport ID
 370  * @param params
 371  *   Subport configuration parameters. Must be non-NULL
 372  *   for first invocation (i.e initialization) for a given
 373  *   subport. Ignored (recommended value is NULL) for all
 374  *   subsequent invocation on the same subport.
 375  * @param subport_profile_id
 376  *   ID of subport bandwidth profile
 377  * @return
 378  *   0 upon success, error code otherwise
 379  */
 380 int
 381 rte_sched_subport_config(struct rte_sched_port *port,
 382         uint32_t subport_id,
 383         struct rte_sched_subport_params *params,
 384         uint32_t subport_profile_id);
 385
 386 /**
 387  * Hierarchical scheduler pipe configuration
 388  *
 389  * @param port
 390  *   Handle to port scheduler instance
 391  * @param subport_id
 392  *   Subport ID
 393  * @param pipe_id
 394  *   Pipe ID within subport
 395  * @param pipe_profile
 396  *   ID of subport-level pre-configured pipe profile
 397  * @return
 398  *   0 upon success, error code otherwise
 399  */
 400 int
 401 rte_sched_pipe_config(struct rte_sched_port *port,
 402         uint32_t subport_id,
 403         uint32_t pipe_id,
 404         int32_t pipe_profile);
 405
 406 /**
 407  * Hierarchical scheduler memory footprint size per port
 408  *
 409  * @param port_params
 410  *   Port scheduler configuration parameter structure
 411  * @param subport_params
 412  *   Array of subport parameter structures
 413  * @return
 414  *   Memory footprint size in bytes upon success, 0 otherwise
 415  */
 416 uint32_t
 417 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *port_params,
 418         struct rte_sched_subport_params **subport_params);
 419 /*
 420  * Statistics
 421  *
 422  ***/
 423
 424 /**
 425  * Hierarchical scheduler subport statistics read
 426  *
 427  * @param port
 428  *   Handle to port scheduler instance
 429  * @param subport_id
 430  *   Subport ID
 431  * @param stats
 432  *   Pointer to pre-allocated subport statistics structure where the statistics
 433  *   counters should be stored
 434  * @param tc_ov
 435  *   Pointer to pre-allocated RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE-entry array
 436  *   where the oversubscription status for each of the subport traffic classes
 437  *   should be stored.
 438  * @return
 439  *   0 upon success, error code otherwise
 440  */
 441 int
 442 rte_sched_subport_read_stats(struct rte_sched_port *port,
 443         uint32_t subport_id,
 444         struct rte_sched_subport_stats *stats,
 445         uint32_t *tc_ov);
 446
 447 /**
 448  * Hierarchical scheduler queue statistics read
 449  *
 450  * @param port
 451  *   Handle to port scheduler instance
 452  * @param queue_id
 453  *   Queue ID within port scheduler
 454  * @param stats
 455  *   Pointer to pre-allocated subport statistics structure where the statistics
 456  *   counters should be stored
 457  * @param qlen
 458  *   Pointer to pre-allocated variable where the current queue length
 459  *   should be stored.
 460  * @return
 461  *   0 upon success, error code otherwise
 462  */
 463 int
 464 rte_sched_queue_read_stats(struct rte_sched_port *port,
 465         uint32_t queue_id,
 466         struct rte_sched_queue_stats *stats,
 467         uint16_t *qlen);
 468
 469 /**
 470  * Scheduler hierarchy path write to packet descriptor. Typically
 471  * called by the packet classification stage.
 472  *
 473  * @param port
 474  *   Handle to port scheduler instance
 475  * @param pkt
 476  *   Packet descriptor handle
 477  * @param subport
 478  *   Subport ID
 479  * @param pipe
 480  *   Pipe ID within subport
 481  * @param traffic_class
 482  *   Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
 483  * @param queue
 484  *   Queue ID within pipe traffic class, 0 for high priority TCs, and
 485  *   0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
 486  * @param color
 487  *   Packet color set
 488  */
 489 void
 490 rte_sched_port_pkt_write(struct rte_sched_port *port,
 491                          struct rte_mbuf *pkt,
 492                          uint32_t subport, uint32_t pipe, uint32_t traffic_class,
 493                          uint32_t queue, enum rte_color color);
 494
 495 /**
 496  * Scheduler hierarchy path read from packet descriptor (struct
 497  * rte_mbuf). Typically called as part of the hierarchical scheduler
 498  * enqueue operation. The subport, pipe, traffic class and queue
 499  * parameters need to be pre-allocated by the caller.
 500  *
 501  * @param port
 502  *   Handle to port scheduler instance
 503  * @param pkt
 504  *   Packet descriptor handle
 505  * @param subport
 506  *   Subport ID
 507  * @param pipe
 508  *   Pipe ID within subport
 509  * @param traffic_class
 510  *   Traffic class ID within pipe (0 .. RTE_SCHED_TRAFFIC_CLASS_BE)
 511  * @param queue
 512  *   Queue ID within pipe traffic class, 0 for high priority TCs, and
 513  *   0 .. (RTE_SCHED_BE_QUEUES_PER_PIPE - 1) for best-effort TC
 514  */
 515 void
 516 rte_sched_port_pkt_read_tree_path(struct rte_sched_port *port,
 517                                   const struct rte_mbuf *pkt,
 518                                   uint32_t *subport, uint32_t *pipe,
 519                                   uint32_t *traffic_class, uint32_t *queue);
 520
 521 enum rte_color
 522 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
 523
 524 /**
 525  * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
 526  * scheduler and returns the number of packets actually written. For
 527  * each packet, the port scheduler queue to write the packet to is
 528  * identified by reading the hierarchy path from the packet
 529  * descriptor; if the queue is full or congested and the packet is not
 530  * written to the queue, then the packet is automatically dropped
 531  * without any action required from the caller.
 532  *
 533  * @param port
 534  *   Handle to port scheduler instance
 535  * @param pkts
 536  *   Array storing the packet descriptor handles
 537  * @param n_pkts
 538  *   Number of packets to enqueue from the pkts array into the port scheduler
 539  * @return
 540  *   Number of packets successfully enqueued
 541  */
 542 int
 543 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
 544
 545 /**
 546  * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
 547  * port scheduler and stores them in the pkts array and returns the
 548  * number of packets actually read.  The pkts array needs to be
 549  * pre-allocated by the caller with at least n_pkts entries.
 550  *
 551  * @param port
 552  *   Handle to port scheduler instance
 553  * @param pkts
 554  *   Pre-allocated packet descriptor array where the packets dequeued
 555  *   from the port
 556  *   scheduler should be stored
 557  * @param n_pkts
 558  *   Number of packets to dequeue from the port scheduler
 559  * @return
 560  *   Number of packets successfully dequeued and placed in the pkts array
 561  */
 562 int
 563 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
 564
 565 #ifdef __cplusplus
 566 }
 567 #endif
 568
 569 #endif /* __INCLUDE_RTE_SCHED_H__ */