1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2016 Intel Corporation. 3 4TAP Poll Mode Driver 5==================== 6 7The TAP Poll Mode Driver (PMD) is a virtual device for injecting packets 8to be processed by the Linux kernel. 9This PMD is useful when writing DPDK application 10for offloading network functionality (such as tunneling) from the kernel. 11 12From the kernel point of view, the TAP device looks like a regular network interface. 13The network device can be managed by standard tools such as ``ip`` and ``ethtool`` commands. 14It is also possible to use existing packet tools such as ``wireshark`` or ``tcpdump``. 15 16From the DPDK application, the TAP device looks like a DPDK ethdev. 17Packets are sent and received in L2 (Ethernet) format. 18The standard DPDK API's to query for information, statistics and send/receive packets 19work as expected. 20 21 22Requirements 23------------ 24 25The TAP PMD requires kernel support for multiple queues in TAP device 26as well as the multi-queue ``multiq`` and incoming ``ingress`` queue disciplines. 27These are standard kernel features in most Linux distributions. 28 29 30Arguments 31--------- 32 33TAP devices are created with the command line ``--vdev=net_tap0`` option. 34This option may be specified more than once by repeating with a different ``net_tapX`` device. 35 36By default, the Linux interfaces are named ``dtap0``, ``dtap1``, etc. 37The interface name can be specified by adding the ``iface=foo0``, for example:: 38 39 --vdev=net_tap0,iface=foo0 --vdev=net_tap1,iface=foo1, ... 40 41Normally the PMD will generate a random MAC address. 42If a static address is desired instead, the ``mac=fixed`` can be used:: 43 44 --vdev=net_tap0,mac=fixed 45 46With the fixed option, the MAC address will have the first octets: 47as 02:'d':'t':'a':'p':[00-FF] and the last octets are the interface number. 48 49To specify a specific MAC address use the conventional representation. 50The string is byte converted to hex, the result is MAC address: ``02:64:74:61:70:11``. 51 52It is possible to specify a remote netdevice to capture packets from by adding 53``remote=foo1``, for example:: 54 55 --vdev=net_tap,iface=tap0,remote=foo1 56 57If a ``remote`` is set, the tap MAC address will be set to match the remote one 58just after netdevice creation. Using TC rules, traffic from the remote netdevice 59will be redirected to the tap. If the tap is in promiscuous mode, then all 60packets will be redirected. In allmulti mode, all multicast packets will be 61redirected. 62 63Using the remote feature is especially useful for capturing traffic from a 64netdevice that has no support in the DPDK. It is possible to add explicit 65rte_flow rules on the tap PMD to capture specific traffic (see next section for 66examples). 67 68Normally, when the DPDK application exits, 69the TAP device is marked down and is removed. 70But this behavior can be overridden by the use of the persist flag, example:: 71 72 --vdev=net_tap0,iface=tap0,persist ... 73 74 75TUN devices 76----------- 77 78The TAP device can be used as an L3 tunnel only device (TUN). 79This type of device does not include the Ethernet (L2) header; 80all packets are sent and received as IP packets. 81 82TUN devices are created with the command line arguments ``--vdev=net_tunX``, 83where X stands for unique id, example:: 84 85 --vdev=net_tun0 --vdev=net_tun1,iface=foo1, ... 86 87Unlike TAP PMD, TUN PMD does not support user arguments as ``MAC`` or ``remote`` user 88options. Default interface name is ``dtunX``, where X stands for unique id. 89 90 91Flow API support 92---------------- 93 94The TAP PMD supports major flow API pattern items and actions. 95 96Requirements 97~~~~~~~~~~~~ 98 99Flow support in TAP driver requires the Linux kernel support of 100flow based traffic control filter ``flower``. 101This was added in Linux 4.3 kernel. 102 103The implementation of RSS action uses an eBPF module 104that requires additional libraries and tools. 105Building the RSS support requires the ``clang`` compiler 106to compile the C code to BPF target; 107``bpftool`` to convert the compiled BPF object to a header file; 108and ``libbpf`` to load the eBPF action into the kernel. 109 110Supported match items: 111 112 - eth: src and dst (with variable masks), and eth_type (0xffff mask). 113 - vlan: vid, pcp, but not eid. (requires kernel 4.9) 114 - ipv4/6: src and dst (with variable masks), and ip_proto (0xffff mask). 115 - udp/tcp: src and dst port (0xffff) mask. 116 117Supported actions: 118 119- DROP 120- QUEUE 121- PASSTHRU 122- RSS 123 124It is generally not possible to provide a "last" item. However, if the "last" 125item, once masked, is identical to the masked spec, then it is supported. 126 127Only IPv4/6 and MAC addresses can use a variable mask. All other items need a 128full mask (exact match). 129 130As rules are translated to TC, it is possible to show them with something like:: 131 132 tc -s filter show dev dtap1 parent 1: 133 134Examples of testpmd flow rules 135~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 136 137Drop packets for destination IP 192.0.2.1:: 138 139 testpmd> flow create 0 priority 1 ingress pattern eth / ipv4 dst is 192.0.2.1 \ 140 / end actions drop / end 141 142Ensure packets from a given MAC address are received on a queue 2:: 143 144 testpmd> flow create 0 priority 2 ingress pattern eth src is 06:05:04:03:02:01 \ 145 / end actions queue index 2 / end 146 147Drop UDP packets in vlan 3:: 148 149 testpmd> flow create 0 priority 3 ingress pattern eth / vlan vid is 3 / \ 150 ipv4 proto is 17 / end actions drop / end 151 152Distribute IPv4 TCP packets using RSS to a given MAC address over queues 0-3:: 153 154 testpmd> flow create 0 priority 4 ingress pattern eth dst is 0a:0b:0c:0d:0e:0f \ 155 / ipv4 / tcp / end actions rss queues 0 1 2 3 end / end 156 157 158Multi-process sharing 159--------------------- 160 161It is possible to attach an existing TAP device in a secondary process, 162by declaring it as a vdev with the same name as in the primary process, 163and without any parameter. 164 165The port attached in a secondary process will give access to the 166statistics and the queues. 167Therefore it can be used for monitoring or Rx/Tx processing. 168 169The IPC synchronization of Rx/Tx queues is currently limited: 170 171 - Maximum 8 queues shared 172 - Synchronized on probing, but not on later port update 173 174 175RSS specifics 176------------- 177 178The default packet distribution in TAP without flow rules 179is done by the kernel which has a default flow based distribution. 180When flow rules are used to distribute packets across a set of queues, 181an eBPF program is used to calculate the RSS based on Toeplitz algorithm 182with the given key. 183 184The hash is calculated for IPv4 and IPv6, 185over src/dst addresses (8 or 32 bytes for IPv4 or IPv6 respectively) 186and optionally the src/dst TCP/UDP ports (4 bytes). 187 188 189Limitations 190----------- 191 192- Since TAP device uses a file descriptor to talk to the kernel, 193 the same number of queues must be specified for receive and transmit. 194 195- The RSS algorithm only support L3 or L4 functions. 196 It does not support finer grain selections 197 (for example: only IPV6 packets with extension headers). 198