1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4QoS Metering Sample Application 5=============================== 6 7The QoS meter sample application is an example that demonstrates the use of DPDK to provide QoS marking and metering, 8as defined by RFC2697 for Single Rate Three Color Marker (srTCM) and RFC 2698 for Two Rate Three Color Marker (trTCM) algorithm. 9 10Overview 11-------- 12 13The application uses a single thread for reading the packets from the RX port, 14metering, marking them with the appropriate color (green, yellow or red) and writing them to the TX port. 15 16A policing scheme can be applied before writing the packets to the TX port by dropping or 17changing 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. 18 19The operation mode can be selected as compile time out of the following options: 20 21* Simple forwarding 22 23* srTCM color blind 24 25* srTCM color aware 26 27* srTCM color blind 28 29* srTCM color aware 30 31Please refer to RFC2697 and RFC2698 for details about the srTCM and trTCM configurable parameters 32(CIR, CBS and EBS for srTCM; CIR, PIR, CBS and PBS for trTCM). 33 34The color blind modes are functionally equivalent with the color-aware modes when 35all the incoming packets are colored as green. 36 37Compiling the Application 38------------------------- 39 40To compile the sample application see :doc:`compiling`. 41 42The application is located in the ``qos_meter`` sub-directory. 43 44Running the Application 45----------------------- 46 47The application execution command line is as below: 48 49.. code-block:: console 50 51 ./qos_meter [EAL options] -- -p PORTMASK 52 53The application is constrained to use a single core in the EAL core mask and 2 ports only in the application port mask 54(first port from the port mask is used for RX and the other port in the core mask is used for TX). 55 56Refer to *DPDK Getting Started Guide* for general information on running applications and 57the Environment Abstraction Layer (EAL) options. 58 59Explanation 60----------- 61 62Selecting one of the metering modes is done with these defines: 63 64.. code-block:: c 65 66 #define APP_MODE_FWD 0 67 #define APP_MODE_SRTCM_COLOR_BLIND 1 68 #define APP_MODE_SRTCM_COLOR_AWARE 2 69 #define APP_MODE_TRTCM_COLOR_BLIND 3 70 #define APP_MODE_TRTCM_COLOR_AWARE 4 71 72 #define APP_MODE APP_MODE_SRTCM_COLOR_BLIND 73 74To simplify debugging (for example, by using the traffic generator RX side MAC address based packet filtering feature), 75the color is defined as the LSB byte of the destination MAC address. 76 77The traffic meter parameters are configured in the application source code with following default values: 78 79.. code-block:: c 80 81 struct rte_meter_srtcm_params app_srtcm_params[] = { 82 83 {.cir = 1000000 * 46, .cbs = 2048, .ebs = 2048}, 84 85 }; 86 87 struct rte_meter_trtcm_params app_trtcm_params[] = { 88 89 {.cir = 1000000 * 46, .pir = 1500000 * 46, .cbs = 2048, .pbs = 2048}, 90 91 }; 92 93Assuming the input traffic is generated at line rate and all packets are 64 bytes Ethernet frames (IPv4 packet size of 46 bytes) 94and green, the expected output traffic should be marked as shown in the following table: 95 96.. _table_qos_metering_1: 97 98.. table:: Output Traffic Marking 99 100 +-------------+------------------+-------------------+----------------+ 101 | **Mode** | **Green (Mpps)** | **Yellow (Mpps)** | **Red (Mpps)** | 102 | | | | | 103 +=============+==================+===================+================+ 104 | srTCM blind | 1 | 1 | 12.88 | 105 | | | | | 106 +-------------+------------------+-------------------+----------------+ 107 | srTCM color | 1 | 1 | 12.88 | 108 | | | | | 109 +-------------+------------------+-------------------+----------------+ 110 | trTCM blind | 1 | 0.5 | 13.38 | 111 | | | | | 112 +-------------+------------------+-------------------+----------------+ 113 | trTCM color | 1 | 0.5 | 13.38 | 114 | | | | | 115 +-------------+------------------+-------------------+----------------+ 116 | FWD | 14.88 | 0 | 0 | 117 | | | | | 118 +-------------+------------------+-------------------+----------------+ 119 120To set up the policing scheme as desired, it is necessary to modify the main.h source file, 121where this policy is implemented as a static structure, as follows: 122 123.. code-block:: c 124 125 int policer_table[e_RTE_METER_COLORS][e_RTE_METER_COLORS] = 126 { 127 { GREEN, RED, RED}, 128 { DROP, YELLOW, RED}, 129 { DROP, DROP, RED} 130 }; 131 132Where rows indicate the input color, columns indicate the output color, 133and the value that is stored in the table indicates the action to be taken for that particular case. 134 135There are four different actions: 136 137* GREEN: The packet's color is changed to green. 138 139* YELLOW: The packet's color is changed to yellow. 140 141* RED: The packet's color is changed to red. 142 143* DROP: The packet is dropped. 144 145In this particular case: 146 147* Every packet which input and output color are the same, keeps the same color. 148 149* Every packet which color has improved is dropped (this particular case can't happen, so these values will not be used). 150 151* For the rest of the cases, the color is changed to red. 152 153.. note:: 154 * In color blind mode, first row GREEN color is only valid. 155 * To drop the packet, policer_table action has to be set to DROP. 156