2 Copyright(c) 2016 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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
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.
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.
31 Tun/Tap Poll Mode Driver
32 ========================
34 The ``rte_eth_tap.c`` PMD creates a device using TUN/TAP interfaces on the
35 local host. The PMD allows for DPDK and the host to communicate using a raw
36 device interface on the host and in the DPDK application.
38 The device created is a TAP device, which sends/receives packet in a raw
39 format with a L2 header. The usage for a TAP PMD is for connectivity to the
40 local host using a TAP interface. When the TAP PMD is initialized it will
41 create a number of tap devices in the host accessed via ``ifconfig -a`` or
42 ``ip`` command. The commands can be used to assign and query the virtual like
45 These TAP interfaces can be used with Wireshark or tcpdump or Pktgen-DPDK
46 along with being able to be used as a network connection to the DPDK
47 application. The method enable one or more interfaces is to use the
48 ``--vdev=net_tap0`` option on the DPDK application command line. Each
49 ``--vdev=net_tap1`` option given will create an interface named dtap0, dtap1,
52 The interface name can be changed by adding the ``iface=foo0``, for example::
54 --vdev=net_tap0,iface=foo0 --vdev=net_tap1,iface=foo1, ...
56 Also the speed of the interface can be changed from 10G to whatever number
57 needed, but the interface does not enforce that speed, for example::
59 --vdev=net_tap0,iface=foo0,speed=25000
61 Normally the PMD will generate a random MAC address, but when testing or with
62 a static configuration the developer may need a fixed MAC address style.
63 Using the option ``mac=fixed`` you can create a fixed known MAC address::
65 --vdev=net_tap0,mac=fixed
67 The MAC address will have a fixed value with the last octet incrementing by one
68 for each interface string containing ``mac=fixed``. The MAC address is formatted
69 as 00:'d':'t':'a':'p':[00-FF]. Convert the characters to hex and you get the
70 actual MAC address: ``00:64:74:61:70:[00-FF]``.
72 It is possible to specify a remote netdevice to capture packets from by adding
73 ``remote=foo1``, for example::
75 --vdev=net_tap,iface=tap0,remote=foo1
77 If a ``remote`` is set, the tap MAC address will be set to match the remote one
78 just after netdevice creation. Using TC rules, traffic from the remote netdevice
79 will be redirected to the tap. If the tap is in promiscuous mode, then all
80 packets will be redirected. In allmulti mode, all multicast packets will be
83 Using the remote feature is especially useful for capturing traffic from a
84 netdevice that has no support in the DPDK. It is possible to add explicit
85 rte_flow rules on the tap PMD to capture specific traffic (see next section for
88 After the DPDK application is started you can send and receive packets on the
89 interface using the standard rx_burst/tx_burst APIs in DPDK. From the host
90 point of view you can use any host tool like tcpdump, Wireshark, ping, Pktgen
91 and others to communicate with the DPDK application. The DPDK application may
92 not understand network protocols like IPv4/6, UDP or TCP unless the
93 application has been written to understand these protocols.
95 If you need the interface as a real network interface meaning running and has
96 a valid IP address then you can do this with the following commands::
98 sudo ip link set dtap0 up; sudo ip addr add 192.168.0.250/24 dev dtap0
99 sudo ip link set dtap1 up; sudo ip addr add 192.168.1.250/24 dev dtap1
101 Please change the IP addresses as you see fit.
103 If routing is enabled on the host you can also communicate with the DPDK App
104 over the internet via a standard socket layer application as long as you
105 account for the protocol handing in the application.
107 If you have a Network Stack in your DPDK application or something like it you
108 can utilize that stack to handle the network protocols. Plus you would be able
109 to address the interface using an IP address assigned to the internal
115 The tap PMD supports major flow API pattern items and actions, when running on
116 linux kernels above 4.2 ("Flower" classifier required).
117 The kernel support can be checked with this command::
119 zcat /proc/config.gz | ( grep 'CLS_FLOWER=' || echo 'not supported' ) |
120 tee -a /dev/stderr | grep -q '=m' &&
121 lsmod | ( grep cls_flower || echo 'try modprobe cls_flower' )
125 - eth: src and dst (with variable masks), and eth_type (0xffff mask).
126 - vlan: vid, pcp, tpid, but not eid. (requires kernel 4.9)
127 - ipv4/6: src and dst (with variable masks), and ip_proto (0xffff mask).
128 - udp/tcp: src and dst port (0xffff) mask.
136 It is generally not possible to provide a "last" item. However, if the "last"
137 item, once masked, is identical to the masked spec, then it is supported.
139 Only IPv4/6 and MAC addresses can use a variable mask. All other items need a
140 full mask (exact match).
142 As rules are translated to TC, it is possible to show them with something like::
144 tc -s filter show dev tap1 parent 1:
146 Examples of testpmd flow rules
147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
149 Drop packets for destination IP 192.168.0.1::
151 testpmd> flow create 0 priority 1 ingress pattern eth / ipv4 dst is 1.1.1.1 \
152 / end actions drop / end
154 Ensure packets from a given MAC address are received on a queue 2::
156 testpmd> flow create 0 priority 2 ingress pattern eth src is 06:05:04:03:02:01 \
157 / end actions queue index 2 / end
159 Drop UDP packets in vlan 3::
161 testpmd> flow create 0 priority 3 ingress pattern eth / vlan vid is 3 / \
162 ipv4 proto is 17 / end actions drop / end
167 The following is a simple example of using the TUN/TAP PMD with the Pktgen
168 packet generator. It requires that the ``socat`` utility is installed on the
171 Build DPDK, then pull down Pktgen and build pktgen using the DPDK SDK/Target
172 used to build the dpdk you pulled down.
174 Run pktgen from the pktgen directory in a terminal with a commandline like the
177 sudo ./app/app/x86_64-native-linuxapp-gcc/app/pktgen -l 1-5 -n 4 \
178 --proc-type auto --log-level 8 --socket-mem 512,512 --file-prefix pg \
179 --vdev=net_tap0 --vdev=net_tap1 -b 05:00.0 -b 05:00.1 \
180 -b 04:00.0 -b 04:00.1 -b 04:00.2 -b 04:00.3 \
181 -b 81:00.0 -b 81:00.1 -b 81:00.2 -b 81:00.3 \
182 -b 82:00.0 -b 83:00.0 -- -T -P -m [2:3].0 -m [4:5].1 \
183 -f themes/black-yellow.theme
187 Change the ``-b`` options to blacklist all of your physical ports. The
188 following command line is all one line.
190 Also, ``-f themes/black-yellow.theme`` is optional if the default colors
191 work on your system configuration. See the Pktgen docs for more
194 Verify with ``ifconfig -a`` command in a different xterm window, should have a
195 ``dtap0`` and ``dtap1`` interfaces created.
197 Next set the links for the two interfaces to up via the commands below::
199 sudo ip link set dtap0 up; sudo ip addr add 192.168.0.250/24 dev dtap0
200 sudo ip link set dtap1 up; sudo ip addr add 192.168.1.250/24 dev dtap1
202 Then use socat to create a loopback for the two interfaces::
204 sudo socat interface:dtap0 interface:dtap1
206 Then on the Pktgen command line interface you can start sending packets using
207 the commands ``start 0`` and ``start 1`` or you can start both at the same
208 time with ``start all``. The command ``str`` is an alias for ``start all`` and
209 ``stp`` is an alias for ``stop all``.
211 While running you should see the 64 byte counters increasing to verify the
212 traffic is being looped back. You can use ``set all size XXX`` to change the
213 size of the packets after you stop the traffic. Use pktgen ``help``
214 command to see a list of all commands. You can also use the ``-f`` option to
215 load commands at startup in command line or Lua script in pktgen.