lib/librte_sched/rte_sched.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef __INCLUDE_RTE_SCHED_H__
  35 #define __INCLUDE_RTE_SCHED_H__
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /**
  42  * @file
  43  * RTE Hierarchical Scheduler
  44  *
  45  * The hierarchical scheduler prioritizes the transmission of packets
  46  * from different users and traffic classes according to the Service
  47  * Level Agreements (SLAs) defined for the current network node.
  48  *
  49  * The scheduler supports thousands of packet queues grouped under a
  50  * 5-level hierarchy:
  51  *     1. Port:
  52  *           - Typical usage: output Ethernet port;
  53  *           - Multiple ports are scheduled in round robin order with
  54  *          equal priority;
  55  *     2. Subport:
  56  *           - Typical usage: group of users;
  57  *           - Traffic shaping using the token bucket algorithm
  58  *          (one bucket per subport);
  59  *           - Upper limit enforced per traffic class at subport level;
  60  *           - Lower priority traffic classes able to reuse subport
  61  *          bandwidth currently unused by higher priority traffic
  62  *          classes of the same subport;
  63  *           - When any subport traffic class is oversubscribed
  64  *          (configuration time event), the usage of subport member
  65  *          pipes with high demand for thattraffic class pipes is
  66  *          truncated to a dynamically adjusted value with no
  67  *             impact to low demand pipes;
  68  *     3. Pipe:
  69  *           - Typical usage: individual user/subscriber;
  70  *           - Traffic shaping using the token bucket algorithm
  71  *          (one bucket per pipe);
  72  *     4. Traffic class:
  73  *           - Traffic classes of the same pipe handled in strict
  74  *          priority order;
  75  *           - Upper limit enforced per traffic class at the pipe level;
  76  *           - Lower priority traffic classes able to reuse pipe
  77  *          bandwidth currently unused by higher priority traffic
  78  *          classes of the same pipe;
  79  *     5. Queue:
  80  *           - Typical usage: queue hosting packets from one or
  81  *          multiple connections of same traffic class belonging to
  82  *          the same user;
  83  *           - Weighted Round Robin (WRR) is used to service the
  84  *          queues within same pipe traffic class.
  85  *
  86  */
  87
  88 #include <sys/types.h>
  89 #include <rte_mbuf.h>
  90 #include <rte_meter.h>
  91
  92 /** Random Early Detection (RED) */
  93 #ifdef RTE_SCHED_RED
  94 #include "rte_red.h"
  95 #endif
  96
  97 /** Number of traffic classes per pipe (as well as subport).
  98  * Cannot be changed.
  99  */
 100 #define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE    4
 101
 102 /** Number of queues per pipe traffic class. Cannot be changed. */
 103 #define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS    4
 104
 105 /** Number of queues per pipe. */
 106 #define RTE_SCHED_QUEUES_PER_PIPE             \
 107         (RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE *     \
 108         RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS)
 109
 110 /** Maximum number of pipe profiles that can be defined per port.
 111  * Compile-time configurable.
 112  */
 113 #ifndef RTE_SCHED_PIPE_PROFILES_PER_PORT
 114 #define RTE_SCHED_PIPE_PROFILES_PER_PORT      256
 115 #endif
 116
 117 /*
 118  * Ethernet framing overhead. Overhead fields per Ethernet frame:
 119  * 1. Preamble:                             7 bytes;
 120  * 2. Start of Frame Delimiter (SFD):       1 byte;
 121  * 3. Frame Check Sequence (FCS):           4 bytes;
 122  * 4. Inter Frame Gap (IFG):               12 bytes.
 123  *
 124  * The FCS is considered overhead only if not included in the packet
 125  * length (field pkt_len of struct rte_mbuf).
 126  */
 127 #ifndef RTE_SCHED_FRAME_OVERHEAD_DEFAULT
 128 #define RTE_SCHED_FRAME_OVERHEAD_DEFAULT      24
 129 #endif
 130
 131 /*
 132  * Subport configuration parameters. The period and credits_per_period
 133  * parameters are measured in bytes, with one byte meaning the time
 134  * duration associated with the transmission of one byte on the
 135  * physical medium of the output port, with pipe or pipe traffic class
 136  * rate (measured as percentage of output port rate) determined as
 137  * credits_per_period divided by period. One credit represents one
 138  * byte.
 139  */
 140 struct rte_sched_subport_params {
 141         /* Subport token bucket */
 142         uint32_t tb_rate;                /**< Rate (measured in bytes per second) */
 143         uint32_t tb_size;                /**< Size (measured in credits) */
 144
 145         /* Subport traffic classes */
 146         uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 147         /**< Traffic class rates (measured in bytes per second) */
 148         uint32_t tc_period;
 149         /**< Enforcement period for rates (measured in milliseconds) */
 150 };
 151
 152 /** Subport statistics */
 153 struct rte_sched_subport_stats {
 154         /* Packets */
 155         uint32_t n_pkts_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 156         /**< Number of packets successfully written */
 157         uint32_t n_pkts_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 158         /**< Number of packets dropped */
 159
 160         /* Bytes */
 161         uint32_t n_bytes_tc[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 162         /**< Number of bytes successfully written for each traffic class */
 163         uint32_t n_bytes_tc_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 164         /**< Number of bytes dropped for each traffic class */
 165
 166 #ifdef RTE_SCHED_RED
 167         uint32_t n_pkts_red_dropped[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 168         /**< Number of packets dropped by red */
 169 #endif
 170 };
 171
 172 /*
 173  * Pipe configuration parameters. The period and credits_per_period
 174  * parameters are measured in bytes, with one byte meaning the time
 175  * duration associated with the transmission of one byte on the
 176  * physical medium of the output port, with pipe or pipe traffic class
 177  * rate (measured as percentage of output port rate) determined as
 178  * credits_per_period divided by period. One credit represents one
 179  * byte.
 180  */
 181 struct rte_sched_pipe_params {
 182         /* Pipe token bucket */
 183         uint32_t tb_rate;                /**< Rate (measured in bytes per second) */
 184         uint32_t tb_size;                /**< Size (measured in credits) */
 185
 186         /* Pipe traffic classes */
 187         uint32_t tc_rate[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 188         /**< Traffic class rates (measured in bytes per second) */
 189         uint32_t tc_period;
 190         /**< Enforcement period (measured in milliseconds) */
 191 #ifdef RTE_SCHED_SUBPORT_TC_OV
 192         uint8_t tc_ov_weight;            /**< Weight Traffic class 3 oversubscription */
 193 #endif
 194
 195         /* Pipe queues */
 196         uint8_t  wrr_weights[RTE_SCHED_QUEUES_PER_PIPE]; /**< WRR weights */
 197 };
 198
 199 /** Queue statistics */
 200 struct rte_sched_queue_stats {
 201         /* Packets */
 202         uint32_t n_pkts;                 /**< Packets successfully written */
 203         uint32_t n_pkts_dropped;         /**< Packets dropped */
 204 #ifdef RTE_SCHED_RED
 205         uint32_t n_pkts_red_dropped;     /**< Packets dropped by RED */
 206 #endif
 207
 208         /* Bytes */
 209         uint32_t n_bytes;                /**< Bytes successfully written */
 210         uint32_t n_bytes_dropped;        /**< Bytes dropped */
 211 };
 212
 213 /** Port configuration parameters. */
 214 struct rte_sched_port_params {
 215         const char *name;                /**< String to be associated */
 216         int socket;                      /**< CPU socket ID */
 217         uint32_t rate;                   /**< Output port rate
 218                                           * (measured in bytes per second) */
 219         uint32_t mtu;                    /**< Maximum Ethernet frame size
 220                                           * (measured in bytes).
 221                                           * Should not include the framing overhead. */
 222         uint32_t frame_overhead;         /**< Framing overhead per packet
 223                                           * (measured in bytes) */
 224         uint32_t n_subports_per_port;    /**< Number of subports */
 225         uint32_t n_pipes_per_subport;    /**< Number of pipes per subport */
 226         uint16_t qsize[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE];
 227         /**< Packet queue size for each traffic class.
 228          * All queues within the same pipe traffic class have the same
 229          * size. Queues from different pipes serving the same traffic
 230          * class have the same size. */
 231         struct rte_sched_pipe_params *pipe_profiles;
 232         /**< Pipe profile table.
 233          * Every pipe is configured using one of the profiles from this table. */
 234         uint32_t n_pipe_profiles;        /**< Profiles in the pipe profile table */
 235 #ifdef RTE_SCHED_RED
 236         struct rte_red_params red_params[RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE][e_RTE_METER_COLORS]; /**< RED parameters */
 237 #endif
 238 };
 239
 240 /*
 241  * Configuration
 242  *
 243  ***/
 244
 245 /**
 246  * Hierarchical scheduler port configuration
 247  *
 248  * @param params
 249  *   Port scheduler configuration parameter structure
 250  * @return
 251  *   Handle to port scheduler instance upon success or NULL otherwise.
 252  */
 253 struct rte_sched_port *
 254 rte_sched_port_config(struct rte_sched_port_params *params);
 255
 256 /**
 257  * Hierarchical scheduler port free
 258  *
 259  * @param port
 260  *   Handle to port scheduler instance
 261  */
 262 void
 263 rte_sched_port_free(struct rte_sched_port *port);
 264
 265 /**
 266  * Hierarchical scheduler subport configuration
 267  *
 268  * @param port
 269  *   Handle to port scheduler instance
 270  * @param subport_id
 271  *   Subport ID
 272  * @param params
 273  *   Subport configuration parameters
 274  * @return
 275  *   0 upon success, error code otherwise
 276  */
 277 int
 278 rte_sched_subport_config(struct rte_sched_port *port,
 279         uint32_t subport_id,
 280         struct rte_sched_subport_params *params);
 281
 282 /**
 283  * Hierarchical scheduler pipe configuration
 284  *
 285  * @param port
 286  *   Handle to port scheduler instance
 287  * @param subport_id
 288  *   Subport ID
 289  * @param pipe_id
 290  *   Pipe ID within subport
 291  * @param pipe_profile
 292  *   ID of port-level pre-configured pipe profile
 293  * @return
 294  *   0 upon success, error code otherwise
 295  */
 296 int
 297 rte_sched_pipe_config(struct rte_sched_port *port,
 298         uint32_t subport_id,
 299         uint32_t pipe_id,
 300         int32_t pipe_profile);
 301
 302 /**
 303  * Hierarchical scheduler memory footprint size per port
 304  *
 305  * @param params
 306  *   Port scheduler configuration parameter structure
 307  * @return
 308  *   Memory footprint size in bytes upon success, 0 otherwise
 309  */
 310 uint32_t
 311 rte_sched_port_get_memory_footprint(struct rte_sched_port_params *params);
 312
 313 /*
 314  * Statistics
 315  *
 316  ***/
 317
 318 /**
 319  * Hierarchical scheduler subport statistics read
 320  *
 321  * @param port
 322  *   Handle to port scheduler instance
 323  * @param subport_id
 324  *   Subport ID
 325  * @param stats
 326  *   Pointer to pre-allocated subport statistics structure where the statistics
 327  *   counters should be stored
 328  * @param tc_ov
 329  *   Pointer to pre-allocated 4-entry array where the oversubscription status for
 330  *   each of the 4 subport traffic classes should be stored.
 331  * @return
 332  *   0 upon success, error code otherwise
 333  */
 334 int
 335 rte_sched_subport_read_stats(struct rte_sched_port *port,
 336         uint32_t subport_id,
 337         struct rte_sched_subport_stats *stats,
 338         uint32_t *tc_ov);
 339
 340 /**
 341  * Hierarchical scheduler queue statistics read
 342  *
 343  * @param port
 344  *   Handle to port scheduler instance
 345  * @param queue_id
 346  *   Queue ID within port scheduler
 347  * @param stats
 348  *   Pointer to pre-allocated subport statistics structure where the statistics
 349  *   counters should be stored
 350  * @param qlen
 351  *   Pointer to pre-allocated variable where the current queue length
 352  *   should be stored.
 353  * @return
 354  *   0 upon success, error code otherwise
 355  */
 356 int
 357 rte_sched_queue_read_stats(struct rte_sched_port *port,
 358         uint32_t queue_id,
 359         struct rte_sched_queue_stats *stats,
 360         uint16_t *qlen);
 361
 362 /**
 363  * Scheduler hierarchy path write to packet descriptor. Typically
 364  * called by the packet classification stage.
 365  *
 366  * @param pkt
 367  *   Packet descriptor handle
 368  * @param subport
 369  *   Subport ID
 370  * @param pipe
 371  *   Pipe ID within subport
 372  * @param traffic_class
 373  *   Traffic class ID within pipe (0 .. 3)
 374  * @param queue
 375  *   Queue ID within pipe traffic class (0 .. 3)
 376  * @param color
 377  *   Packet color set
 378  */
 379 void
 380 rte_sched_port_pkt_write(struct rte_mbuf *pkt,
 381                          uint32_t subport, uint32_t pipe, uint32_t traffic_class,
 382                          uint32_t queue, enum rte_meter_color color);
 383
 384 /**
 385  * Scheduler hierarchy path read from packet descriptor (struct
 386  * rte_mbuf). Typically called as part of the hierarchical scheduler
 387  * enqueue operation. The subport, pipe, traffic class and queue
 388  * parameters need to be pre-allocated by the caller.
 389  *
 390  * @param pkt
 391  *   Packet descriptor handle
 392  * @param subport
 393  *   Subport ID
 394  * @param pipe
 395  *   Pipe ID within subport
 396  * @param traffic_class
 397  *   Traffic class ID within pipe (0 .. 3)
 398  * @param queue
 399  *   Queue ID within pipe traffic class (0 .. 3)
 400  *
 401  */
 402 void
 403 rte_sched_port_pkt_read_tree_path(const struct rte_mbuf *pkt,
 404                                   uint32_t *subport, uint32_t *pipe,
 405                                   uint32_t *traffic_class, uint32_t *queue);
 406
 407 enum rte_meter_color
 408 rte_sched_port_pkt_read_color(const struct rte_mbuf *pkt);
 409
 410 /**
 411  * Hierarchical scheduler port enqueue. Writes up to n_pkts to port
 412  * scheduler and returns the number of packets actually written. For
 413  * each packet, the port scheduler queue to write the packet to is
 414  * identified by reading the hierarchy path from the packet
 415  * descriptor; if the queue is full or congested and the packet is not
 416  * written to the queue, then the packet is automatically dropped
 417  * without any action required from the caller.
 418  *
 419  * @param port
 420  *   Handle to port scheduler instance
 421  * @param pkts
 422  *   Array storing the packet descriptor handles
 423  * @param n_pkts
 424  *   Number of packets to enqueue from the pkts array into the port scheduler
 425  * @return
 426  *   Number of packets successfully enqueued
 427  */
 428 int
 429 rte_sched_port_enqueue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
 430
 431 /**
 432  * Hierarchical scheduler port dequeue. Reads up to n_pkts from the
 433  * port scheduler and stores them in the pkts array and returns the
 434  * number of packets actually read.  The pkts array needs to be
 435  * pre-allocated by the caller with at least n_pkts entries.
 436  *
 437  * @param port
 438  *   Handle to port scheduler instance
 439  * @param pkts
 440  *   Pre-allocated packet descriptor array where the packets dequeued
 441  *   from the port
 442  *   scheduler should be stored
 443  * @param n_pkts
 444  *   Number of packets to dequeue from the port scheduler
 445  * @return
 446  *   Number of packets successfully dequeued and placed in the pkts array
 447  */
 448 int
 449 rte_sched_port_dequeue(struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts);
 450
 451 #ifdef __cplusplus
 452 }
 453 #endif
 454
 455 #endif /* __INCLUDE_RTE_SCHED_H__ */