1.. BSD LICENSE 2 Copyright(c) 2010-2014 Intel Corporation. All rights reserved. 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 * Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 * Redistributions in binary form must reproduce the above copyright 12 notice, this list of conditions and the following disclaimer in 13 the documentation and/or other materials provided with the 14 distribution. 15 * Neither the name of Intel Corporation nor the names of its 16 contributors may be used to endorse or promote products derived 17 from this software without specific prior written permission. 18 19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31QoS Metering Sample Application 32=============================== 33 34The QoS meter sample application is an example that demonstrates the use of DPDK to provide QoS marking and metering, 35as defined by RFC2697 for Single Rate Three Color Marker (srTCM) and RFC 2698 for Two Rate Three Color Marker (trTCM) algorithm. 36 37Overview 38-------- 39 40The application uses a single thread for reading the packets from the RX port, 41metering, marking them with the appropriate color (green, yellow or red) and writing them to the TX port. 42 43A policing scheme can be applied before writing the packets to the TX port by dropping or 44changing the color of the packet in a static manner depending on both the input and output colors of the packets that are processed by the meter. 45 46The operation mode can be selected as compile time out of the following options: 47 48* Simple forwarding 49 50* srTCM color blind 51 52* srTCM color aware 53 54* srTCM color blind 55 56* srTCM color aware 57 58Please refer to RFC2697 and RFC2698 for details about the srTCM and trTCM configurable parameters 59(CIR, CBS and EBS for srTCM; CIR, PIR, CBS and PBS for trTCM). 60 61The color blind modes are functionally equivalent with the color-aware modes when 62all the incoming packets are colored as green. 63 64Compiling the Application 65------------------------- 66 67To compile the sample application see :doc:`compiling`. 68 69The application is located in the ``qos_meter`` sub-directory. 70 71Running the Application 72----------------------- 73 74The application execution command line is as below: 75 76.. code-block:: console 77 78 ./qos_meter [EAL options] -- -p PORTMASK 79 80The application is constrained to use a single core in the EAL core mask and 2 ports only in the application port mask 81(first port from the port mask is used for RX and the other port in the core mask is used for TX). 82 83Refer to *DPDK Getting Started Guide* for general information on running applications and 84the Environment Abstraction Layer (EAL) options. 85 86Explanation 87----------- 88 89Selecting one of the metering modes is done with these defines: 90 91.. code-block:: c 92 93 #define APP_MODE_FWD 0 94 #define APP_MODE_SRTCM_COLOR_BLIND 1 95 #define APP_MODE_SRTCM_COLOR_AWARE 2 96 #define APP_MODE_TRTCM_COLOR_BLIND 3 97 #define APP_MODE_TRTCM_COLOR_AWARE 4 98 99 #define APP_MODE APP_MODE_SRTCM_COLOR_BLIND 100 101To simplify debugging (for example, by using the traffic generator RX side MAC address based packet filtering feature), 102the color is defined as the LSB byte of the destination MAC address. 103 104The traffic meter parameters are configured in the application source code with following default values: 105 106.. code-block:: c 107 108 struct rte_meter_srtcm_params app_srtcm_params[] = { 109 110 {.cir = 1000000 * 46, .cbs = 2048, .ebs = 2048}, 111 112 }; 113 114 struct rte_meter_trtcm_params app_trtcm_params[] = { 115 116 {.cir = 1000000 * 46, .pir = 1500000 * 46, .cbs = 2048, .pbs = 2048}, 117 118 }; 119 120Assuming the input traffic is generated at line rate and all packets are 64 bytes Ethernet frames (IPv4 packet size of 46 bytes) 121and green, the expected output traffic should be marked as shown in the following table: 122 123.. _table_qos_metering_1: 124 125.. table:: Output Traffic Marking 126 127 +-------------+------------------+-------------------+----------------+ 128 | **Mode** | **Green (Mpps)** | **Yellow (Mpps)** | **Red (Mpps)** | 129 | | | | | 130 +=============+==================+===================+================+ 131 | srTCM blind | 1 | 1 | 12.88 | 132 | | | | | 133 +-------------+------------------+-------------------+----------------+ 134 | srTCM color | 1 | 1 | 12.88 | 135 | | | | | 136 +-------------+------------------+-------------------+----------------+ 137 | trTCM blind | 1 | 0.5 | 13.38 | 138 | | | | | 139 +-------------+------------------+-------------------+----------------+ 140 | trTCM color | 1 | 0.5 | 13.38 | 141 | | | | | 142 +-------------+------------------+-------------------+----------------+ 143 | FWD | 14.88 | 0 | 0 | 144 | | | | | 145 +-------------+------------------+-------------------+----------------+ 146 147To set up the policing scheme as desired, it is necessary to modify the main.h source file, 148where this policy is implemented as a static structure, as follows: 149 150.. code-block:: c 151 152 int policer_table[e_RTE_METER_COLORS][e_RTE_METER_COLORS] = 153 { 154 { GREEN, RED, RED}, 155 { DROP, YELLOW, RED}, 156 { DROP, DROP, RED} 157 }; 158 159Where rows indicate the input color, columns indicate the output color, 160and the value that is stored in the table indicates the action to be taken for that particular case. 161 162There are four different actions: 163 164* GREEN: The packet's color is changed to green. 165 166* YELLOW: The packet's color is changed to yellow. 167 168* RED: The packet's color is changed to red. 169 170* DROP: The packet is dropped. 171 172In this particular case: 173 174* Every packet which input and output color are the same, keeps the same color. 175 176* Every packet which color has improved is dropped (this particular case can't happen, so these values will not be used). 177 178* For the rest of the cases, the color is changed to red. 179