vnet/vnet/devices/dpdk/qos_doc.md

   1 # Quality-of-Service (QoS)- Hierarchcal Scheduler\r
   2 \r
   3 The Quality-of-Service (QoS) scheduler performs egress-traffic management by prioritizing the transmission of the packets of different type services and subcribers based on the Service Level Agreements (SLAs). The QoS scheduler can be enabled on one or more NIC output interfaces depending upon the requirement.\r
   4 \r
   5 ## Overview\r
   6 \r
   7 The QoS schdeuler supports a number of scheduling and shaping levels which construct hierarchical-tree. The first level in the hierarchy is port (i.e. the physical interface) that constitutes the root node of the tree. The subsequent level is subport which represents the group of the users/subscribers. The individual user/subscriber is represented by the pipe at the next level. Each user can have different traffic type based on the criteria of specific loss rate, jitter, and latency. These traffic types are represented at the traffic-class level in the form of different traffic-classes. The last level contains number of queues which are grouped together to host the packets of the specific class type traffic.\r
   8 \r
   9 The QoS scheduler implementation requires flow classification, enqueue  and dequeue operations. The flow classification is mandatory stage for HQoS where incoming packets are classified by mapping the packet fields information to 5-tuple (HQoS subport, pipe, traffic class, queue within traffic class, and color) and storing that information in mbuf sched field. The enqueue operation uses this information to determine the queue for storing the packet, and at this stage, if the specific queue is full, QoS drops the packet. The dequeue operation consists of scheduling the packet based on its length and available credits, and handing over the scheduled packet to the output interface.\r
  10 \r
  11 for more information on QoS Scheduler, please refer DPDK Programmer's Guide- http://dpdk.org/doc/guides/prog_guide/qos_framework.html\r
  12 \r
  13 ### QoS Schdeuler Parameters\r
  14 \r
  15 Following illustrates the default HQoS configuration for each 10GbE output port:\r
  16 \r
  17 Single subport (subport 0):\r
  18         - Subport rate set to 100% of port rate\r
  19         - Each of the 4 traffic classes has rate set to 100% of port rate\r
  20 4K pipes per subport 0 (pipes 0 .. 4095) with identical configuration:\r
  21         - Pipe rate set to 1/4K of port rate\r
  22         - Each of the 4 traffic classes has rate set to 100% of pipe rate\r
  23         - Within each traffic class, the byte-level WRR weights for the 4 queues are set to 1:1:1:1\r
  24 \r
  25 #### Port configuration\r
  26 port {\r
  27         rate 1250000000                                 /* Assuming 10GbE port */\r
  28         frame_overhead 24                               /* Overhead fields per Ethernet frame */ \r
  29                                                                         /* 7B (Preamble) + 1B (Start of Frame Delimiter (SFD)) + 4B (Frame Check Sequence (FCS)) + 12B (Inter Frame Gap (IFG)) */\r
  30         mtu 1522                                                /* Assuming Ethernet/IPv4 pkt (Ethernet FCS not included) */\r
  31         n_subports_per_port 1                   /* Number of subports per output interface */\r
  32         n_pipes_per_subport 4096        /* Number of pipes (users/subscribers) */\r
  33         queue_sizes 64 64 64 64                 /* Packet queue size for each traffic class. All queues within the same pipe traffic class have the same size.\r
  34                                                                                 Queues from different pipes serving the same traffic class have the same size.*/\r
  35 }\r
  36 \r
  37 #### Subport configuration\r
  38 subport 0 {\r
  39         tb_rate 1250000000                              /* Subport level token bucket rate (bytes per second) */\r
  40         tb_size 1000000                                 /* Subport level token bucket size (bytes) */\r
  41         tc0_rate 1250000000                             /* Subport level token bucket rate for traffic class 0 (bytes per second) */\r
  42         tc1_rate 1250000000                             /* Subport level token bucket rate for traffic class 1 (bytes per second) */\r
  43         tc2_rate 1250000000                             /* Subport level token bucket rate for traffic class 2 (bytes per second) */\r
  44         tc3_rate 1250000000                             /* Subport level token bucket rate for traffic class 3 (bytes per second) */\r
  45         tc_period 10                                    /* Time interval for refilling the token bucket associated with traffic class (Milliseconds) */\r
  46         pipe 0 4095 profile 0                   /* pipes (users/subscribers) configured with pipe profile 0 */\r
  47 }\r
  48 \r
  49 #### Pipe configuration\r
  50 pipe_profile 0 {\r
  51         tb_rate 305175                                  /* Pipe level token bucket rate (bytes per second) */\r
  52         tb_size 1000000                                 /* Pipe level token bucket size (bytes) */\r
  53         tc0_rate 305175                                 /* Pipe level token bucket rate for traffic class 0 (bytes per second) */\r
  54         tc1_rate 305175                                 /* Pipe level token bucket rate for traffic class 1 (bytes per second) */\r
  55         tc2_rate 305175                                 /* Pipe level token bucket rate for traffic class 2 (bytes per second) */\r
  56         tc3_rate 305175                                 /* Pipe level token bucket rate for traffic class 3 (bytes per second) */\r
  57         tc_period 40                                    /* Time interval for refilling the token bucket associated with traffic class at pipe level (Milliseconds) */\r
  58         tc3_oversubscription_weight 1   /* Weight traffic class 3 oversubscription */\r
  59         tc0_wrr_weights 1 1 1 1                 /* Pipe queues WRR weights for traffic class 0 */\r
  60         tc1_wrr_weights 1 1 1 1                 /* Pipe queues WRR weights for traffic class 1 */\r
  61         tc2_wrr_weights 1 1 1 1                 /* Pipe queues WRR weights for traffic class 2 */\r
  62         tc3_wrr_weights 1 1 1 1                 /* Pipe queues WRR weights for traffic class 3 */\r
  63 }\r
  64 \r
  65 #### Random Early Detection (RED) parameters per traffic class and color (Green / Yellow / Red)\r
  66 red {\r
  67         tc0_wred_min 48 40 32                   /* Minimum threshold for traffic class 0 queue (min_th) in number of packets */\r
  68         tc0_wred_max 64 64 64                   /* Maximum threshold for traffic class 0 queue (max_th) in number of packets */\r
  69         tc0_wred_inv_prob 10 10 10              /* Inverse of packet marking probability for traffic class 0 queue (maxp = 1 / maxp_inv) */\r
  70         tc0_wred_weight 9 9 9                   /* Traffic Class 0 queue weight */\r
  71         tc1_wred_min 48 40 32                   /* Minimum threshold for traffic class 1 queue (min_th) in number of packets */\r
  72         tc1_wred_max 64 64 64                   /* Maximum threshold for traffic class 1 queue (max_th) in number of packets */\r
  73         tc1_wred_inv_prob 10 10 10              /* Inverse of packet marking probability for traffic class 1 queue (maxp = 1 / maxp_inv) */\r
  74         tc1_wred_weight 9 9 9                   /* Traffic Class 1 queue weight */\r
  75         tc2_wred_min 48 40 32                   /* Minimum threshold for traffic class 2 queue (min_th) in number of packets */\r
  76         tc2_wred_max 64 64 64                   /* Maximum threshold for traffic class 2 queue (max_th) in number of packets */\r
  77         tc2_wred_inv_prob 10 10 10              /* Inverse of packet marking probability for traffic class 2 queue (maxp = 1 / maxp_inv) */\r
  78         tc2_wred_weight 9 9 9                   /* Traffic Class 2 queue weight */\r
  79         tc3_wred_min 48 40 32                   /* Minimum threshold for traffic class 3 queue (min_th) in number of packets */\r
  80         tc3_wred_max 64 64 64                   /* Maximum threshold for traffic class 3 queue (max_th) in number of packets */\r
  81         tc3_wred_inv_prob 10 10 10              /* Inverse of packet marking probability for traffic class 3 queue (maxp = 1 / maxp_inv) */\r
  82         tc3_wred_weight 9 9 9                   /* Traffic Class 3 queue weight */\r
  83 }\r
  84 \r
  85 ### DPDK QoS Scheduler Integration in VPP\r
  86 \r
  87 The Hierarchical Quaity-of-Service (HQoS) scheduler object could be seen as part of the logical NIC output interface. To enable HQoS on specific output interface, vpp startup.conf file has to be configured accordingly. The output interface that requires HQoS, should have "hqos" parameter specified in dpdk section. Another optional parameter "hqos-thread"  has been defined which can be used to associate the output interface with specific hqos thread. In cpu section of the config file, "corelist-hqos-threads" is introduced to assign logical cpu cores to run the HQoS threads. A HQoS thread can run multiple HQoS objects each associated with different output interfaces. All worker threads instead of writing packets to NIC TX queue directly, write the packets to a software queues. The hqos_threads read the software queues, and enqueue the packets to HQoS objects, as well as dequeue packets from HQOS objects and write them to NIC output interfaces. The worker threads need to be able to send the packets to any output interface, therefore, each HQoS object associated with NIC output interface should have software queues equal to worker threads count.\r
  88 \r
  89 Following illustrates the sample startup configuration file with 4x worker threads feeding 2x hqos threads that handle each QoS scheduler for 1x output interface.\r
  90 \r
  91 dpdk {\r
  92         socket-mem 16384,16384\r
  93 \r
  94         dev 0000:02:00.0 {\r
  95                 num-rx-queues 2\r
  96                 hqos\r
  97         }\r
  98         dev 0000:06:00.0 {\r
  99                 num-rx-queues 2\r
 100                 hqos\r
 101         }\r
 102 \r
 103         num-mbufs 1000000\r
 104 }\r
 105 \r
 106 cpu {\r
 107   main-core 0\r
 108   corelist-workers  1, 2, 3, 4\r
 109   corelist-hqos-threads  5, 6\r
 110 }\r
 111 \r
 112 ### QoS scheduler CLI Commands\r
 113         Each QoS scheduler instance is initialised with default parameters required to configure hqos port, subport, pipe and queues. Some of the parameters can be re-configured in run-time through CLI commands.\r
 114 \r
 115 #### Configuration\r
 116         Following commands can be used to configure QoS scheduler parameters-\r
 117 \r
 118         * The command below can be used to set the subport level parameters such as token bucket rate (bytes per seconds), token bucket size (bytes),\r
 119           traffic class rates (bytes per seconds) and  token update period (Milliseconds).\r
 120                 set dpdk interface hqos subport <if-name> subport <n> [rate <n>] [bktsize <n>] [tc0 <n>] [tc1 <n>] [tc2 <n>] [tc3 <n>] [period <n>]\r
 121 \r
 122         * For setting the pipe profile, following command can be used.          \r
 123                 set dpdk interface hqos pipe <if-name> subport <n> pipe <n> profile <n>\r
 124 \r
 125         * To assign QoS scheduler instance to the specific thread, following command can be used.\r
 126                 set dpdk interface hqos placement <if-name> thread <n>\r
 127 \r
 128         * The command below is used to set the packet fields required for classifiying the incoming packet. As a result of classification process,\r
 129           packet field information will be mapped to 5 tuples (subport, pipe, traffic class, pipe, color) and stored in packet mbuf.\r
 130                 set dpdk interface hqos pktfield <if-name> id <n> offset <n> mask <n>\r
 131 \r
 132         * The DSCP table entries used for idenfiying the traffic class and queue can be set using the command below;   \r
 133                 set dpdk interface hqos tctbl <if-name> entry <n> tc <n> queue <n>\r
 134 \r
 135 #### Show Command\r
 136 \r
 137         * The QoS Scheduler configuration can displayed using the command below.\r
 138 \r
 139          vpp# show dpdk interface hqos TenGigabitEthernet2/0/0\r
 140          Thread:\r
 141            Input SWQ size = 4096 packets\r
 142            Enqueue burst size = 256 packets\r
 143            Dequeue burst size = 220 packets\r
 144            Packet field 0: slab position =    0, slab bitmask = 0x0000000000000000\r
 145            Packet field 1: slab position =   40, slab bitmask = 0x0000000fff000000\r
 146            Packet field 2: slab position =    8, slab bitmask = 0x00000000000000fc\r
 147            Packet field 2 translation table:\r
 148                  [ 0 .. 15]:  0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15\r
 149                  [16 .. 31]:  0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15\r
 150                  [32 .. 47]:  0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15\r
 151                  [48 .. 63]:  0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15\r
 152          Port:\r
 153            Rate = 1250000000 bytes/second\r
 154            MTU = 1514 bytes\r
 155            Frame overhead = 24 bytes\r
 156            Number of subports = 1\r
 157            Number of pipes per subport = 4096\r
 158            Packet queue size: TC0 = 64, TC1 = 64, TC2 = 64, TC3 = 64 packets\r
 159            Number of pipe profiles = 1\r
 160            Pipe profile 0:\r
 161            Rate = 305175 bytes/second\r
 162            Token bucket size = 1000000 bytes\r
 163            Traffic class rate: TC0 = 305175, TC1 = 305175, TC2 = 305175, TC3 = 305175 bytes/second\r
 164            TC period = 40 milliseconds\r
 165            TC0 WRR weights: Q0 = 1, Q1 = 1, Q2 = 1, Q3 = 1\r
 166            TC1 WRR weights: Q0 = 1, Q1 = 1, Q2 = 1, Q3 = 1\r
 167            TC2 WRR weights: Q0 = 1, Q1 = 1, Q2 = 1, Q3 = 1\r
 168            TC3 WRR weights: Q0 = 1, Q1 = 1, Q2 = 1, Q3 = 1\r
 169 \r
 170 \r
 171         * The QoS Scheduler placement over the logical cpu cores can be displayed using below command.\r
 172 \r
 173           vpp# show dpdk interface hqos placement\r
 174             Thread 5 (vpp_hqos-threads_0 at lcore 5):\r
 175             TenGigabitEthernet2/0/0 queue 0\r
 176             Thread 6 (vpp_hqos-threads_1 at lcore 6):\r
 177             TenGigabitEthernet4/0/1 queue 0\r
 178 \r
 179 \r
 180 ### QoS Scheduler Binary APIs\r
 181 \r
 182         This section explans the available binary APIs for configuring QoS scheduler parameters in run-time.\r
 183 \r
 184 **      The following API can be used to set the pipe profile of pipe that belongs to subport id-\r
 185 \r
 186         sw_interface_set_dpdk_hqos_pipe rx <intfc> | sw_if_index <id> subport <subport-id> pipe <pipe-id>\r
 187         profile <profile-id>\r
 188 \r
 189         The data structures used for set the pipe profile parameter are as follows;\r
 190 \r
 191         /** \brief DPDK interface HQoS pipe profile set request\r
 192                 @param client_index - opaque cookie to identify the sender\r
 193                 @param context - sender context, to match reply w/ request\r
 194                 @param sw_if_index - the interface\r
 195                 @param subport - subport ID\r
 196                 @param pipe - pipe ID within its subport\r
 197                 @param profile - pipe profile ID\r
 198         */\r
 199         define sw_interface_set_dpdk_hqos_pipe {\r
 200                 u32 client_index;\r
 201                 u32 context;\r
 202                 u32 sw_if_index;\r
 203                 u32 subport;\r
 204                 u32 pipe;\r
 205                 u32 profile;\r
 206         };\r
 207 \r
 208         /** \brief DPDK interface HQoS pipe profile set reply\r
 209                 @param context - sender context, to match reply w/ request\r
 210                 @param retval - request return code\r
 211         */\r
 212         define sw_interface_set_dpdk_hqos_pipe_reply {\r
 213                 u32 context;\r
 214                 i32 retval;\r
 215         };\r
 216 \r
 217 \r
 218 **  The following API can be used to set the subport level parameters, for example- token bucket rate (bytes per seconds), tocken bucket size (bytes),\r
 219          traffic class rate (bytes per seconds) and tokens update period.\r
 220 \r
 221         sw_interface_set_dpdk_hqos_subport rx <intfc> | sw_if_index <id> subport <subport-id> [rate <n>]\r
 222         [bktsize <n>] [tc0 <n>] [tc1 <n>] [tc2 <n>] [tc3 <n>] [period <n>]\r
 223 \r
 224         The data structures used for set the subport level parameter are as follows;\r
 225 \r
 226         /** \brief DPDK interface HQoS subport parameters set request\r
 227                 @param client_index - opaque cookie to identify the sender\r
 228                 @param context - sender context, to match reply w/ request\r
 229                 @param sw_if_index - the interface\r
 230                 @param subport - subport ID\r
 231                 @param tb_rate - subport token bucket rate (measured in bytes/second)\r
 232                 @param tb_size - subport token bucket size (measured in credits)\r
 233                 @param tc_rate - subport traffic class 0 .. 3 rates (measured in bytes/second)\r
 234                 @param tc_period - enforcement period for rates (measured in milliseconds)\r
 235         */\r
 236         define sw_interface_set_dpdk_hqos_subport {\r
 237                 u32 client_index;\r
 238                 u32 context;\r
 239                 u32 sw_if_index;\r
 240                 u32 subport;\r
 241                 u32 tb_rate;\r
 242                 u32 tb_size;\r
 243                 u32 tc_rate[4];\r
 244                 u32 tc_period;\r
 245         };\r
 246 \r
 247         /** \brief DPDK interface HQoS subport parameters set reply\r
 248                 @param context - sender context, to match reply w/ request\r
 249                 @param retval - request return code\r
 250         */\r
 251         define sw_interface_set_dpdk_hqos_subport_reply {\r
 252                 u32 context;\r
 253                 i32 retval;\r
 254         };\r
 255 \r
 256 \r
 257 ** The following API can be used set the DSCP table entry. The DSCP table have 64 entries to map the packet DSCP field onto traffic class and hqos input queue.\r
 258 \r
 259         sw_interface_set_dpdk_hqos_tctbl rx <intfc> | sw_if_index <id> entry <n> tc <n> queue <n>\r
 260 \r
 261         The data structures used for setting DSCP table entries are given below.\r
 262 \r
 263         /** \brief DPDK interface HQoS tctbl entry set request\r
 264                 @param client_index - opaque cookie to identify the sender\r
 265                 @param context - sender context, to match reply w/ request\r
 266                 @param sw_if_index - the interface\r
 267                 @param entry - entry index ID\r
 268                 @param tc - traffic class (0 .. 3)\r
 269                 @param queue - traffic class queue (0 .. 3)\r
 270         */\r
 271         define sw_interface_set_dpdk_hqos_tctbl {\r
 272                 u32 client_index;\r
 273                 u32 context;\r
 274                 u32 sw_if_index;\r
 275                 u32 entry;\r
 276                 u32 tc;\r
 277                 u32 queue;\r
 278         };\r
 279 \r
 280         /** \brief DPDK interface HQoS tctbl entry set reply\r
 281                 @param context - sender context, to match reply w/ request\r
 282                 @param retval - request return code\r
 283         */\r
 284         define sw_interface_set_dpdk_hqos_tctbl_reply {\r
 285                 u32 context;\r
 286                 i32 retval;\r
 287         };\r