doc/guides/nics/tap.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2016 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
  31 Tun/Tap Poll Mode Driver
  32 ========================
  33
  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.
  37
  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
  43 device.
  44
  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 give will create an interface named dtap0, dtap1,
  50 and so on.
  51
  52 The interface name can be changed by adding the ``iface=foo0``, for example::
  53
  54    --vdev=net_tap0,iface=foo0 --vdev=net_tap1,iface=foo1, ...
  55
  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::
  58
  59    --vdev=net_tap0,iface=foo0,speed=25000
  60
  61 After the DPDK application is started you can send and receive packets on the
  62 interface using the standard rx_burst/tx_burst APIs in DPDK. From the host
  63 point of view you can use any host tool like tcpdump, Wireshark, ping, Pktgen
  64 and others to communicate with the DPDK application. The DPDK application may
  65 not understand network protocols like IPv4/6, UDP or TCP unless the
  66 application has been written to understand these protocols.
  67
  68 If you need the interface as a real network interface meaning running and has
  69 a valid IP address then you can do this with the following commands::
  70
  71    sudo ip link set dtap0 up; sudo ip addr add 192.168.0.250/24 dev dtap0
  72    sudo ip link set dtap1 up; sudo ip addr add 192.168.1.250/24 dev dtap1
  73
  74 Please change the IP addresses as you see fit.
  75
  76 If routing is enabled on the host you can also communicate with the DPDK App
  77 over the internet via a standard socket layer application as long as you
  78 account for the protocol handing in the application.
  79
  80 If you have a Network Stack in your DPDK application or something like it you
  81 can utilize that stack to handle the network protocols. Plus you would be able
  82 to address the interface using an IP address assigned to the internal
  83 interface.
  84
  85 Flow API support
  86 ----------------
  87
  88 The tap PMD supports major flow API pattern items and actions, when running on
  89 linux kernels above 4.2 ("Flower" classifier required). Supported items:
  90
  91 - eth: src and dst (with variable masks), and eth_type (0xffff mask).
  92 - vlan: vid, pcp, tpid, but not eid. (requires kernel 4.9)
  93 - ipv4/6: src and dst (with variable masks), and ip_proto (0xffff mask).
  94 - udp/tcp: src and dst port (0xffff) mask.
  95
  96 Supported actions:
  97
  98 - DROP
  99 - QUEUE
 100 - PASSTHRU
 101
 102 It is generally not possible to provide a "last" item. However, if the "last"
 103 item, once masked, is identical to the masked spec, then it is supported.
 104
 105 Only IPv4/6 and MAC addresses can use a variable mask. All other items need a
 106 full mask (exact match).
 107
 108 As rules are translated to TC, it is possible to show them with something like::
 109
 110    tc -s filter show dev tap1 parent 1:
 111
 112 Examples of testpmd flow rules
 113 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 114
 115 Drop packets for destination IP 192.168.0.1::
 116
 117    testpmd> flow create 0 priority 1 ingress pattern eth / ipv4 dst is 1.1.1.1 \
 118             / end actions drop / end
 119
 120 Ensure packets from a given MAC address are received on a queue 2::
 121
 122    testpmd> flow create 0 priority 2 ingress pattern eth src is 06:05:04:03:02:01 \
 123             / end actions queue index 2 / end
 124
 125 Drop UDP packets in vlan 3::
 126
 127    testpmd> flow create 0 priority 3 ingress pattern eth / vlan vid is 3 / \
 128             ipv4 proto is 17 / end actions drop / end
 129
 130 Example
 131 -------
 132
 133 The following is a simple example of using the TUN/TAP PMD with the Pktgen
 134 packet generator. It requires that the ``socat`` utility is installed on the
 135 test system.
 136
 137 Build DPDK, then pull down Pktgen and build pktgen using the DPDK SDK/Target
 138 used to build the dpdk you pulled down.
 139
 140 Run pktgen from the pktgen directory in a terminal with a commandline like the
 141 following::
 142
 143     sudo ./app/app/x86_64-native-linuxapp-gcc/app/pktgen -l 1-5 -n 4        \
 144      --proc-type auto --log-level 8 --socket-mem 512,512 --file-prefix pg   \
 145      --vdev=net_tap0 --vdev=net_tap1 -b 05:00.0 -b 05:00.1                  \
 146      -b 04:00.0 -b 04:00.1 -b 04:00.2 -b 04:00.3                            \
 147      -b 81:00.0 -b 81:00.1 -b 81:00.2 -b 81:00.3                            \
 148      -b 82:00.0 -b 83:00.0 -- -T -P -m [2:3].0 -m [4:5].1                   \
 149      -f themes/black-yellow.theme
 150
 151 .. Note:
 152
 153    Change the ``-b`` options to blacklist all of your physical ports. The
 154    following command line is all one line.
 155
 156    Also, ``-f themes/black-yellow.theme`` is optional if the default colors
 157    work on your system configuration. See the Pktgen docs for more
 158    information.
 159
 160 Verify with ``ifconfig -a`` command in a different xterm window, should have a
 161 ``dtap0`` and ``dtap1`` interfaces created.
 162
 163 Next set the links for the two interfaces to up via the commands below::
 164
 165     sudo ip link set dtap0 up; sudo ip addr add 192.168.0.250/24 dev dtap0
 166     sudo ip link set dtap1 up; sudo ip addr add 192.168.1.250/24 dev dtap1
 167
 168 Then use socat to create a loopback for the two interfaces::
 169
 170     sudo socat interface:dtap0 interface:dtap1
 171
 172 Then on the Pktgen command line interface you can start sending packets using
 173 the commands ``start 0`` and ``start 1`` or you can start both at the same
 174 time with ``start all``. The command ``str`` is an alias for ``start all`` and
 175 ``stp`` is an alias for ``stop all``.
 176
 177 While running you should see the 64 byte counters increasing to verify the
 178 traffic is being looped back. You can use ``set all size XXX`` to change the
 179 size of the packets after you stop the traffic. Use pktgen ``help``
 180 command to see a list of all commands. You can also use the ``-f`` option to
 181 load commands at startup in command line or Lua script in pktgen.