6beb6f6b1faa50d9db1ef234135f81cfd49a1c6b
[dpdk.git] / doc / guides / sample_app_ug / tep_termination.rst
1
2 ..  BSD LICENSE
3     Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
4     All rights reserved.
5
6     Redistribution and use in source and binary forms, with or without
7     modification, are permitted provided that the following conditions
8     are met:
9
10     * Redistributions of source code must retain the above copyright
11     notice, this list of conditions and the following disclaimer.
12     * Redistributions in binary form must reproduce the above copyright
13     notice, this list of conditions and the following disclaimer in
14     the documentation and/or other materials provided with the
15     distribution.
16     * Neither the name of Intel Corporation nor the names of its
17     contributors may be used to endorse or promote products derived
18     from this software without specific prior written permission.
19
20     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31
32
33 TEP termination Sample Application
34 ==================================
35
36 The TEP (Tunnel End point) termination sample application simulates a VXLAN
37 Tunnel Endpoint (VTEP) termination in DPDK, which is used to demonstrate
38 the offload and filtering capabilities of Intel® XL710 10/40 Gigabit Ethernet
39 Controller for VXLAN packet.
40 This sample uses the basic virtio devices management mechanism from vhost example,
41 and also uses the us-vHost interface and tunnel filtering mechanism to direct
42 a specified traffic to a specific VM.
43 In addition, this sample is also designed to show how tunneling protocols can be handled.
44
45 Background
46 ----------
47
48 With virtualization, overlay networks allow a network structure to be built
49 or imposed across physical nodes which is abstracted away from the actual
50 underlining physical network connections.
51 This allows network isolation, QOS, etc to be provided on a per client basis.
52
53 .. _figure_overlay_networking:
54
55 .. figure:: img/overlay_networking.*
56
57    Overlay Networking.
58
59 In a typical setup, the network overlay tunnel is terminated at the Virtual/Tunnel End Point (VEP/TEP).
60 The TEP is normally located at the physical host level ideally in the software switch.
61 Due to processing constraints and the inevitable bottleneck that the switch
62 becomes the ability to offload overlay support features becomes an important requirement.
63 Intel® XL710 10/40 G Ethernet network card provides hardware filtering
64 and offload capabilities to support overlay networks implementations such as MAC in UDP and MAC in GRE.
65
66 Sample Code Overview
67 --------------------
68
69 The DPDK TEP termination sample code demonstrates the offload and filtering
70 capabilities of Intel® XL710 10/40 Gigabit Ethernet Controller for VXLAN packet.
71
72 The sample code is based on vhost library.
73 The vhost library is developed for user space Ethernet switch to easily integrate with vhost functionality.
74
75 The sample will support the followings:
76
77 *   Tunneling packet recognition.
78
79 *   The port of UDP tunneling is configurable
80
81 *   Directing incoming traffic to the correct queue based on the tunnel filter type.
82     The supported filter type are listed below.
83
84     * Inner MAC and VLAN and tenant ID
85
86     * Inner MAC and tenant ID, and Outer MAC
87
88     * Inner MAC and tenant ID
89
90     The tenant ID will be assigned from a static internal table based on the us-vhost device ID.
91     Each device will receive a unique device ID.
92     The inner MAC will be learned by the first packet transmitted from a device.
93
94 *   Decapsulation of RX VXLAN traffic. This is a software only operation.
95
96 *   Encapsulation of TX VXLAN traffic. This is a software only operation.
97
98 *   Inner IP and inner L4 checksum offload.
99
100 *   TSO offload support for tunneling packet.
101
102 The following figure shows the framework of the TEP termination sample application based on vhost-cuse.
103
104 .. _figure_tep_termination_arch:
105
106 .. figure:: img/tep_termination_arch.*
107
108    TEP termination Framework Overview
109
110 Supported Distributions
111 -----------------------
112
113 The example in this section have been validated with the following distributions:
114
115 *   Fedora* 18
116
117 *   Fedora* 19
118
119 *   Fedora* 20
120
121 Prerequisites
122 -------------
123
124 Refer to the guide in section 27.4 in the vhost sample.
125
126 Compiling the Sample Code
127 -------------------------
128 #.  Compile vhost lib:
129
130     To enable vhost, turn on vhost library in the configure file config/common_linuxapp.
131
132     .. code-block:: console
133
134         CONFIG_RTE_LIBRTE_VHOST=n
135
136     vhost user is turned on by default in the configure file config/common_linuxapp.
137     To enable vhost cuse, disable vhost user.
138
139     .. code-block:: console
140
141         CONFIG_RTE_LIBRTE_VHOST_USER=y
142
143      After vhost is enabled and the implementation is selected, build the vhost library.
144
145 #.  Go to the examples directory:
146
147     .. code-block:: console
148
149         export RTE_SDK=/path/to/rte_sdk
150         cd ${RTE_SDK}/examples/tep_termination
151
152 #.  Set the target (a default target is used if not specified). For example:
153
154     .. code-block:: console
155
156         export RTE_TARGET=x86_64-native-linuxapp-gcc
157
158     See the DPDK Getting Started Guide for possible RTE_TARGET values.
159
160 #.  Build the application:
161
162     .. code-block:: console
163
164         cd ${RTE_SDK}
165         make config ${RTE_TARGET}
166         make install ${RTE_TARGET}
167         cd ${RTE_SDK}/examples/tep_termination
168         make
169
170 #.  Go to the eventfd_link directory(vhost cuse required):
171
172     .. code-block:: console
173
174         cd ${RTE_SDK}/lib/librte_vhost/eventfd_link
175
176 #.  Build the eventfd_link kernel module(vhost cuse required):
177
178     .. code-block:: console
179
180         make
181
182 Running the Sample Code
183 -----------------------
184
185 #.  Install the cuse kernel module(vhost cuse required):
186
187     .. code-block:: console
188
189         modprobe cuse
190
191 #.  Go to the eventfd_link directory(vhost cuse required):
192
193     .. code-block:: console
194
195         export RTE_SDK=/path/to/rte_sdk
196         cd ${RTE_SDK}/lib/librte_vhost/eventfd_link
197
198 #.  Install the eventfd_link module(vhost cuse required):
199
200     .. code-block:: console
201
202         insmod ./eventfd_link.ko
203
204 #.  Go to the examples directory:
205
206     .. code-block:: console
207
208         export RTE_SDK=/path/to/rte_sdk
209         cd ${RTE_SDK}/examples/tep_termination
210
211 #.  Run the tep_termination sample code:
212
213     .. code-block:: console
214
215         user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
216                         -p 0x1 --dev-basename tep-termination --nb-devices 4
217                         --udp-port 4789 --filter-type 1
218
219 .. note::
220
221     Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs.
222
223 Parameters
224 ~~~~~~~~~~
225
226 **The same parameters with the vhost sample.**
227
228 Refer to the guide in section 27.6.1 in the vhost sample for the meanings of 'Basename',
229 'Stats', 'RX Retry', 'RX Retry Number' and 'RX Retry Delay Time'.
230
231 **Number of Devices.**
232
233 The nb-devices option specifies the number of virtIO device.
234 The default value is 2.
235
236 .. code-block:: console
237
238     user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
239                     --nb-devices 2
240
241 **Tunneling UDP port.**
242
243 The udp-port option is used to specify the destination UDP number for UDP tunneling packet.
244 The default value is 4789.
245
246 .. code-block:: console
247
248     user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
249                     --nb-devices 2 --udp-port 4789
250
251 **Filter Type.**
252
253 The filter-type option is used to specify which filter type is used to
254 filter UDP tunneling packet to a specified queue.
255 The default value is 1, which means the filter type of inner MAC and tenant ID is used.
256
257 .. code-block:: console
258
259     user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
260                 --nb-devices 2 --udp-port 4789 --filter-type 1
261
262 **TX Checksum.**
263
264 The tx-checksum option is used to enable or disable the inner header checksum offload.
265 The default value is 0, which means the checksum offload is disabled.
266
267 .. code-block:: console
268
269     user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
270                 --nb-devices 2 --tx-checksum
271
272 **TCP segment sise.**
273
274 The tso-segsz option specifies the TCP segment size for TSO offload for tunneling packet.
275 The default value is 0, which means TSO offload is disabled.
276
277 .. code-block:: console
278
279     user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
280                 --tx-checksum --tso-segsz 800
281
282 **Decapsulation option.**
283
284 The decap option is used to enable or disable decapsulation operation for received VXLAN packet.
285 The default value is 1.
286
287 .. code-block:: console
288
289     user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
290                 --nb-devices 4 --udp-port 4789 --decap 1
291
292 **Encapsulation option.**
293
294 The encap option is used to enable or disable encapsulation operation for transmitted packet.
295 The default value is 1.
296
297 .. code-block:: console
298
299     user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge --
300                 --nb-devices 4 --udp-port 4789 --encap 1
301
302
303 Running the Virtual Machine (QEMU)
304 ----------------------------------
305
306 Refer to the guide in section 27.7 in the vhost sample.
307
308 Running DPDK in the Virtual Machine
309 -----------------------------------
310
311 Refer to the guide in section 27.8 in the vHost sample.
312
313 Passing Traffic to the Virtual Machine Device
314 ---------------------------------------------
315
316 For a virtio-net device to receive traffic, the traffic's Layer 2 header must include
317 both the virtio-net device's MAC address.
318 The DPDK sample code behaves in a similar manner to a learning switch in that
319 it learns the MAC address of the virtio-net devices from the first transmitted packet.
320 On learning the MAC address,
321 the DPDK vhost sample code prints a message with the MAC address and tenant ID virtio-net device.
322 For example:
323
324 .. code-block:: console
325
326     DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VNI 1000 registered
327
328 The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VNI 1000.
329 Any packets received on the NIC with these values are placed on the devices receive queue.