xref: /dpdk/doc/guides/sample_app_ug/qos_metering.rst (revision fc1f2750a3ec6da919e3c86e59d56f34ec97154b) 
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 Intel® 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
67#.  Go to the example directory:
68
69    .. code-block:: console
70
71        export RTE_SDK=/path/to/rte_sdk
72        cd ${RTE_SDK}/examples/qos_meter
73
74#.  Set the target
75    (a default target is used if not specified):
76
77    .. note::
78
79        This application is intended as a linuxapp only.
80
81    .. code-block:: console
82
83        export RTE_TARGET=x86_64-native-linuxapp-gcc
84
85#.  Build the application:
86
87    .. code-block:: console
88
89        make
90
91Running the Application
92-----------------------
93
94The application execution command line is as below:
95
96.. code-block:: console
97
98    ./qos_meter [EAL options] -- -p PORTMASK
99
100The application is constrained to use a single core in the EAL core mask and 2 ports only in the application port mask
101(first port from the port mask is used for RX and the other port in the core mask is used for TX).
102
103Refer to *Intel® DPDK Getting Started Guide* for general information on running applications and
104the Environment Abstraction Layer (EAL) options.
105
106Explanation
107-----------
108
109Selecting one of the metering modes is done with these defines:
110
111.. code-block:: c
112
113    #define APP_MODE_FWD   0
114    #define APP_MODE_SRTCM_COLOR_BLIND  1
115    #define APP_MODE_SRTCM_COLOR_AWARE  2
116    #define APP_MODE_TRTCM_COLOR_BLIND  3
117    #define APP_MODE_TRTCM_COLOR_AWARE  4
118
119    #define APP_MODE  APP_MODE_SRTCM_COLOR_BLIND
120
121To simplify debugging (for example, by using the traffic generator RX side MAC address based packet filtering feature),
122the color is defined as the LSB byte of the destination MAC address.
123
124The traffic meter parameters are configured in the application source code with following default values:
125
126.. code-block:: c
127
128    struct rte_meter_srtcm_params app_srtcm_params[] = {
129
130        {.cir = 1000000 * 46, .cbs = 2048, .ebs = 2048},
131
132    };
133
134    struct rte_meter_trtcm_params app_trtcm_params[] = {
135
136        {.cir = 1000000 * 46, .pir = 1500000 * 46, .cbs = 2048, .pbs = 2048},
137
138    };
139
140Assuming the input traffic is generated at line rate and all packets are 64 bytes Ethernet frames (IPv4 packet size of 46 bytes)
141and green, the expected output traffic should be marked as shown in the following table:
142
143.. _table_1:
144
145**Table 1. Output Traffic Marking**
146
147+-------------+------------------+-------------------+----------------+
148| **Mode**    | **Green (Mpps)** | **Yellow (Mpps)** | **Red (Mpps)** |
149|             |                  |                   |                |
150+=============+==================+===================+================+
151| srTCM blind | 1                | 1                 | 12.88          |
152|             |                  |                   |                |
153+-------------+------------------+-------------------+----------------+
154| srTCM color | 1                | 1                 | 12.88          |
155|             |                  |                   |                |
156+-------------+------------------+-------------------+----------------+
157| trTCM blind | 1                | 0.5               | 13.38          |
158|             |                  |                   |                |
159+-------------+------------------+-------------------+----------------+
160| trTCM color | 1                | 0.5               | 13.38          |
161|             |                  |                   |                |
162+-------------+------------------+-------------------+----------------+
163| FWD         | 14.88            | 0                 | 0              |
164|             |                  |                   |                |
165+-------------+------------------+-------------------+----------------+
166
167To set up the policing scheme as desired, it is necessary to modify the main.h source file,
168where this policy is implemented as a static structure, as follows:
169
170.. code-block:: c
171
172    int policer_table[e_RTE_METER_COLORS][e_RTE_METER_COLORS] =
173    {
174       { GREEN, RED, RED},
175       { DROP, YELLOW, RED},
176       { DROP, DROP, RED}
177    };
178
179Where rows indicate the input color, columns indicate the output color,
180and the value that is stored in the table indicates the action to be taken for that particular case.
181
182There are four different actions:
183
184*   GREEN: The packet's color is changed to green.
185
186*   YELLOW: The packet's color is changed to yellow.
187
188*   RED: The packet's color is changed to red.
189
190*   DROP: The packet is dropped.
191
192In this particular case:
193
194*   Every packet which input and output color are the same, keeps the same color.
195
196*   Every packet which color has improved is dropped (this particular case can't happen, so these values will not be used).
197
198*   For the rest of the cases, the color is changed to red.
199