lib/librte_sched/rte_sched.h

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