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