]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 Gigabit 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 | |
103 | application based on DPDK vhost lib. | |
104 | ||
105 | .. _figure_tep_termination_arch: | |
106 | ||
107 | .. figure:: img/tep_termination_arch.* | |
108 | ||
109 | TEP termination Framework Overview | |
110 | ||
111 | Supported Distributions | |
112 | ----------------------- | |
113 | ||
114 | The example in this section have been validated with the following distributions: | |
115 | ||
116 | * Fedora* 18 | |
117 | ||
118 | * Fedora* 19 | |
119 | ||
120 | * Fedora* 20 | |
121 | ||
122 | Compiling the Sample Code | |
123 | ------------------------- | |
124 | #. Compile vhost lib: | |
125 | ||
126 | To enable vhost, turn on vhost library in the configure file config/common_linuxapp. | |
127 | ||
128 | .. code-block:: console | |
129 | ||
130 | CONFIG_RTE_LIBRTE_VHOST=y | |
131 | ||
132 | ||
133 | #. Go to the examples directory: | |
134 | ||
135 | .. code-block:: console | |
136 | ||
137 | export RTE_SDK=/path/to/rte_sdk | |
138 | cd ${RTE_SDK}/examples/tep_termination | |
139 | ||
140 | #. Set the target (a default target is used if not specified). For example: | |
141 | ||
142 | .. code-block:: console | |
143 | ||
144 | export RTE_TARGET=x86_64-native-linuxapp-gcc | |
145 | ||
146 | See the DPDK Getting Started Guide for possible RTE_TARGET values. | |
147 | ||
148 | #. Build the application: | |
149 | ||
150 | .. code-block:: console | |
151 | ||
152 | cd ${RTE_SDK} | |
153 | make config ${RTE_TARGET} | |
154 | make install ${RTE_TARGET} | |
155 | cd ${RTE_SDK}/examples/tep_termination | |
156 | make | |
157 | ||
158 | Running the Sample Code | |
159 | ----------------------- | |
160 | ||
161 | #. Go to the examples directory: | |
162 | ||
163 | .. code-block:: console | |
164 | ||
165 | export RTE_SDK=/path/to/rte_sdk | |
166 | cd ${RTE_SDK}/examples/tep_termination | |
167 | ||
168 | #. Run the tep_termination sample code: | |
169 | ||
170 | .. code-block:: console | |
171 | ||
172 | user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge -- | |
173 | -p 0x1 --dev-basename tep-termination --nb-devices 4 | |
174 | --udp-port 4789 --filter-type 1 | |
175 | ||
176 | .. note:: | |
177 | ||
178 | Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs. | |
179 | ||
180 | Parameters | |
181 | ~~~~~~~~~~ | |
182 | ||
183 | **The same parameters with the vhost sample.** | |
184 | ||
185 | Refer to :ref:`vhost_app_parameters` for detailed explanation. | |
186 | ||
187 | **Number of Devices.** | |
188 | ||
189 | The nb-devices option specifies the number of virtIO device. | |
190 | The default value is 2. | |
191 | ||
192 | .. code-block:: console | |
193 | ||
194 | user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge -- | |
195 | --nb-devices 2 | |
196 | ||
197 | **Tunneling UDP port.** | |
198 | ||
199 | The udp-port option is used to specify the destination UDP number for UDP tunneling packet. | |
200 | The default value is 4789. | |
201 | ||
202 | .. code-block:: console | |
203 | ||
204 | user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge -- | |
205 | --nb-devices 2 --udp-port 4789 | |
206 | ||
207 | **Filter Type.** | |
208 | ||
209 | The filter-type option is used to specify which filter type is used to | |
210 | filter UDP tunneling packet to a specified queue. | |
211 | The default value is 1, which means the filter type of inner MAC and tenant ID is used. | |
212 | ||
213 | .. code-block:: console | |
214 | ||
215 | user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge -- | |
216 | --nb-devices 2 --udp-port 4789 --filter-type 1 | |
217 | ||
218 | **TX Checksum.** | |
219 | ||
220 | The tx-checksum option is used to enable or disable the inner header checksum offload. | |
221 | The default value is 0, which means the checksum offload is disabled. | |
222 | ||
223 | .. code-block:: console | |
224 | ||
225 | user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge -- | |
226 | --nb-devices 2 --tx-checksum | |
227 | ||
228 | **TCP segment size.** | |
229 | ||
230 | The tso-segsz option specifies the TCP segment size for TSO offload for tunneling packet. | |
231 | The default value is 0, which means TSO offload is disabled. | |
232 | ||
233 | .. code-block:: console | |
234 | ||
235 | user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge -- | |
236 | --tx-checksum --tso-segsz 800 | |
237 | ||
238 | **Decapsulation option.** | |
239 | ||
240 | The decap option is used to enable or disable decapsulation operation for received VXLAN packet. | |
241 | The default value is 1. | |
242 | ||
243 | .. code-block:: console | |
244 | ||
245 | user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge -- | |
246 | --nb-devices 4 --udp-port 4789 --decap 1 | |
247 | ||
248 | **Encapsulation option.** | |
249 | ||
250 | The encap option is used to enable or disable encapsulation operation for transmitted packet. | |
251 | The default value is 1. | |
252 | ||
253 | .. code-block:: console | |
254 | ||
255 | user@target:~$ ./build/app/tep_termination -c f -n 4 --huge-dir /mnt/huge -- | |
256 | --nb-devices 4 --udp-port 4789 --encap 1 | |
257 | ||
258 | ||
259 | Running the Virtual Machine (QEMU) | |
260 | ---------------------------------- | |
261 | ||
262 | Refer to :ref:`vhost_app_run_vm`. | |
263 | ||
264 | Running DPDK in the Virtual Machine | |
265 | ----------------------------------- | |
266 | ||
267 | Refer to :ref:`vhost_app_run_dpdk_inside_guest`. | |
268 | ||
269 | Passing Traffic to the Virtual Machine Device | |
270 | --------------------------------------------- | |
271 | ||
272 | For a virtio-net device to receive traffic, the traffic's Layer 2 header must include | |
273 | both the virtio-net device's MAC address. | |
274 | The DPDK sample code behaves in a similar manner to a learning switch in that | |
275 | it learns the MAC address of the virtio-net devices from the first transmitted packet. | |
276 | On learning the MAC address, | |
277 | the DPDK vhost sample code prints a message with the MAC address and tenant ID virtio-net device. | |
278 | For example: | |
279 | ||
280 | .. code-block:: console | |
281 | ||
282 | DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VNI 1000 registered | |
283 | ||
284 | The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VNI 1000. | |
285 | Any packets received on the NIC with these values are placed on the devices receive queue. |