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