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