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