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 Tap Poll Mode Driver
  32 ====================
  33
  34 The ``rte_eth_tap.c`` PMD creates a device using 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 given 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 Normally the PMD will generate a random MAC address, but when testing or with
  57 a static configuration the developer may need a fixed MAC address style.
  58 Using the option ``mac=fixed`` you can create a fixed known MAC address::
  59
  60    --vdev=net_tap0,mac=fixed
  61
  62 The MAC address will have a fixed value with the last octet incrementing by one
  63 for each interface string containing ``mac=fixed``. The MAC address is formatted
  64 as 00:'d':'t':'a':'p':[00-FF]. Convert the characters to hex and you get the
  65 actual MAC address: ``00:64:74:61:70:[00-FF]``.
  66
  67 It is possible to specify a remote netdevice to capture packets from by adding
  68 ``remote=foo1``, for example::
  69
  70    --vdev=net_tap,iface=tap0,remote=foo1
  71
  72 If a ``remote`` is set, the tap MAC address will be set to match the remote one
  73 just after netdevice creation. Using TC rules, traffic from the remote netdevice
  74 will be redirected to the tap. If the tap is in promiscuous mode, then all
  75 packets will be redirected. In allmulti mode, all multicast packets will be
  76 redirected.
  77
  78 Using the remote feature is especially useful for capturing traffic from a
  79 netdevice that has no support in the DPDK. It is possible to add explicit
  80 rte_flow rules on the tap PMD to capture specific traffic (see next section for
  81 examples).
  82
  83 After the DPDK application is started you can send and receive packets on the
  84 interface using the standard rx_burst/tx_burst APIs in DPDK. From the host
  85 point of view you can use any host tool like tcpdump, Wireshark, ping, Pktgen
  86 and others to communicate with the DPDK application. The DPDK application may
  87 not understand network protocols like IPv4/6, UDP or TCP unless the
  88 application has been written to understand these protocols.
  89
  90 If you need the interface as a real network interface meaning running and has
  91 a valid IP address then you can do this with the following commands::
  92
  93    sudo ip link set dtap0 up; sudo ip addr add 192.168.0.250/24 dev dtap0
  94    sudo ip link set dtap1 up; sudo ip addr add 192.168.1.250/24 dev dtap1
  95
  96 Please change the IP addresses as you see fit.
  97
  98 If routing is enabled on the host you can also communicate with the DPDK App
  99 over the internet via a standard socket layer application as long as you
 100 account for the protocol handing in the application.
 101
 102 If you have a Network Stack in your DPDK application or something like it you
 103 can utilize that stack to handle the network protocols. Plus you would be able
 104 to address the interface using an IP address assigned to the internal
 105 interface.
 106
 107 Flow API support
 108 ----------------
 109
 110 The tap PMD supports major flow API pattern items and actions, when running on
 111 linux kernels above 4.2 ("Flower" classifier required).
 112 The kernel support can be checked with this command::
 113
 114    zcat /proc/config.gz | ( grep 'CLS_FLOWER=' || echo 'not supported' ) |
 115    tee -a /dev/stderr | grep -q '=m' &&
 116    lsmod | ( grep cls_flower || echo 'try modprobe cls_flower' )
 117
 118 Supported items:
 119
 120 - eth: src and dst (with variable masks), and eth_type (0xffff mask).
 121 - vlan: vid, pcp, tpid, but not eid. (requires kernel 4.9)
 122 - ipv4/6: src and dst (with variable masks), and ip_proto (0xffff mask).
 123 - udp/tcp: src and dst port (0xffff) mask.
 124
 125 Supported actions:
 126
 127 - DROP
 128 - QUEUE
 129 - PASSTHRU
 130 - RSS
 131
 132 It is generally not possible to provide a "last" item. However, if the "last"
 133 item, once masked, is identical to the masked spec, then it is supported.
 134
 135 Only IPv4/6 and MAC addresses can use a variable mask. All other items need a
 136 full mask (exact match).
 137
 138 As rules are translated to TC, it is possible to show them with something like::
 139
 140    tc -s filter show dev tap1 parent 1:
 141
 142 Examples of testpmd flow rules
 143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145 Drop packets for destination IP 192.168.0.1::
 146
 147    testpmd> flow create 0 priority 1 ingress pattern eth / ipv4 dst is 1.1.1.1 \
 148             / end actions drop / end
 149
 150 Ensure packets from a given MAC address are received on a queue 2::
 151
 152    testpmd> flow create 0 priority 2 ingress pattern eth src is 06:05:04:03:02:01 \
 153             / end actions queue index 2 / end
 154
 155 Drop UDP packets in vlan 3::
 156
 157    testpmd> flow create 0 priority 3 ingress pattern eth / vlan vid is 3 / \
 158             ipv4 proto is 17 / end actions drop / end
 159
 160 Distribute IPv4 TCP packets using RSS to a given MAC address over queues 0-3::
 161
 162    testpmd> flow create 0 priority 4 ingress pattern eth dst is 0a:0b:0c:0d:0e:0f \
 163             / ipv4 / tcp / end actions rss queues 0 1 2 3 end / end
 164
 165 Example
 166 -------
 167
 168 The following is a simple example of using the TAP PMD with the Pktgen
 169 packet generator. It requires that the ``socat`` utility is installed on the
 170 test system.
 171
 172 Build DPDK, then pull down Pktgen and build pktgen using the DPDK SDK/Target
 173 used to build the dpdk you pulled down.
 174
 175 Run pktgen from the pktgen directory in a terminal with a commandline like the
 176 following::
 177
 178     sudo ./app/app/x86_64-native-linuxapp-gcc/app/pktgen -l 1-5 -n 4        \
 179      --proc-type auto --log-level 8 --socket-mem 512,512 --file-prefix pg   \
 180      --vdev=net_tap0 --vdev=net_tap1 -b 05:00.0 -b 05:00.1                  \
 181      -b 04:00.0 -b 04:00.1 -b 04:00.2 -b 04:00.3                            \
 182      -b 81:00.0 -b 81:00.1 -b 81:00.2 -b 81:00.3                            \
 183      -b 82:00.0 -b 83:00.0 -- -T -P -m [2:3].0 -m [4:5].1                   \
 184      -f themes/black-yellow.theme
 185
 186 .. Note:
 187
 188    Change the ``-b`` options to blacklist all of your physical ports. The
 189    following command line is all one line.
 190
 191    Also, ``-f themes/black-yellow.theme`` is optional if the default colors
 192    work on your system configuration. See the Pktgen docs for more
 193    information.
 194
 195 Verify with ``ifconfig -a`` command in a different xterm window, should have a
 196 ``dtap0`` and ``dtap1`` interfaces created.
 197
 198 Next set the links for the two interfaces to up via the commands below::
 199
 200     sudo ip link set dtap0 up; sudo ip addr add 192.168.0.250/24 dev dtap0
 201     sudo ip link set dtap1 up; sudo ip addr add 192.168.1.250/24 dev dtap1
 202
 203 Then use socat to create a loopback for the two interfaces::
 204
 205     sudo socat interface:dtap0 interface:dtap1
 206
 207 Then on the Pktgen command line interface you can start sending packets using
 208 the commands ``start 0`` and ``start 1`` or you can start both at the same
 209 time with ``start all``. The command ``str`` is an alias for ``start all`` and
 210 ``stp`` is an alias for ``stop all``.
 211
 212 While running you should see the 64 byte counters increasing to verify the
 213 traffic is being looped back. You can use ``set all size XXX`` to change the
 214 size of the packets after you stop the traffic. Use pktgen ``help``
 215 command to see a list of all commands. You can also use the ``-f`` option to
 216 load commands at startup in command line or Lua script in pktgen.
 217
 218 RSS specifics
 219 -------------
 220 Packet distribution in TAP is done by the kernel which has a default
 221 distribution. This feature is adding RSS distribution based on eBPF code.
 222 The default eBPF code calculates RSS hash based on Toeplitz algorithm for
 223 a fixed RSS key. It is calculated on fixed packet offsets. For IPv4 and IPv6 it
 224 is calculated over src/dst addresses (8 or 32 bytes for IPv4 or IPv6
 225 respectively) and src/dst TCP/UDP ports (4 bytes).
 226
 227 The RSS algorithm is written in file ``tap_bpf_program.c`` which
 228 does not take part in TAP PMD compilation. Instead this file is compiled
 229 in advance to eBPF object file. The eBPF object file is then parsed and
 230 translated into eBPF byte code in the format of C arrays of eBPF
 231 instructions. The C array of eBPF instructions is part of TAP PMD tree and
 232 is taking part in TAP PMD compilation. At run time the C arrays are uploaded to
 233 the kernel via BPF system calls and the RSS hash is calculated by the
 234 kernel.
 235
 236 It is possible to support different RSS hash algorithms by updating file
 237 ``tap_bpf_program.c``  In order to add a new RSS hash algorithm follow these
 238 steps:
 239
 240 1. Write the new RSS implementation in file ``tap_bpf_program.c``
 241
 242 BPF programs which are uploaded to the kernel correspond to
 243 C functions under different ELF sections.
 244
 245 2. Install ``LLVM`` library and ``clang`` compiler versions 3.7 and above
 246
 247 3. Compile ``tap_bpf_program.c`` via ``LLVM`` into an object file::
 248
 249     clang -O2 -emit-llvm -c tap_bpf_program.c -o - | llc -march=bpf \
 250     -filetype=obj -o <tap_bpf_program.o>
 251
 252
 253 4. Use a tool that receives two parameters: an eBPF object file and a section
 254 name, and prints out the section as a C array of eBPF instructions.
 255 Embed the C array in your TAP PMD tree.
 256
 257 The C arrays are uploaded to the kernel using BPF system calls.
 258
 259 ``tc`` (traffic control) is a well known user space utility program used to
 260 configure the Linux kernel packet scheduler. It is usually packaged as
 261 part of the ``iproute2`` package.
 262 Since commit 11c39b5e9 ("tc: add eBPF support to f_bpf") ``tc`` can be used
 263 to uploads eBPF code to the kernel and can be patched in order to print the
 264 C arrays of eBPF instructions just before calling the BPF system call.
 265 Please refer to ``iproute2`` package file ``lib/bpf.c`` function
 266 ``bpf_prog_load()``.
 267
 268 An example utility for eBPF instruction generation in the format of C arrays will
 269 be added in next releases
 270