X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fnics%2Ftap.rst;h=4b6d77d377038f2e844cd14168ba3ab676fce4fb;hb=dc9ceff73c99;hp=528746ae6f31f5bcf6bcef5194bb5e28648ea689;hpb=22e8c9f341adc255d73efba6bea0b9fed5351220;p=dpdk.git diff --git a/doc/guides/nics/tap.rst b/doc/guides/nics/tap.rst index 528746ae6f..4b6d77d377 100644 --- a/doc/guides/nics/tap.rst +++ b/doc/guides/nics/tap.rst @@ -1,37 +1,10 @@ -.. BSD LICENSE - Copyright(c) 2016 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Tun/Tap Poll Mode Driver +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016 Intel Corporation. + +Tun|Tap Poll Mode Driver ======================== -The ``rte_eth_tap.c`` PMD creates a device using TUN/TAP interfaces on the +The ``rte_eth_tap.c`` PMD creates a device using TAP interfaces on the local host. The PMD allows for DPDK and the host to communicate using a raw device interface on the host and in the DPDK application. @@ -64,6 +37,12 @@ for each interface string containing ``mac=fixed``. The MAC address is formatted as 00:'d':'t':'a':'p':[00-FF]. Convert the characters to hex and you get the actual MAC address: ``00:64:74:61:70:[00-FF]``. + --vdev=net_tap0,mac="00:64:74:61:70:11" + +The MAC address will have a user value passed as string. The MAC address is in +format with delimiter ``:``. The string is byte converted to hex and you get +the actual MAC address: ``00:64:74:61:70:11``. + It is possible to specify a remote netdevice to capture packets from by adding ``remote=foo1``, for example:: @@ -104,6 +83,17 @@ can utilize that stack to handle the network protocols. Plus you would be able to address the interface using an IP address assigned to the internal interface. +The TUN PMD allows user to create a TUN device on host. The PMD allows user +to transmit and receive packets via DPDK API calls with L3 header and payload. +The devices in host can be accessed via ``ifconfig`` or ``ip`` command. TUN +interfaces are passed to DPDK ``rte_eal_init`` arguments as ``--vdev=net_tunX``, +where X stands for unique id, example:: + + --vdev=net_tun0 --vdev=net_tun1,iface=foo1, ... + +Unlike TAP PMD, TUN PMD does not support user arguments as ``MAC`` or ``remote`` user +options. Default interface name is ``dtunX``, where X stands for unique id. + Flow API support ---------------- @@ -118,7 +108,7 @@ The kernel support can be checked with this command:: Supported items: - eth: src and dst (with variable masks), and eth_type (0xffff mask). -- vlan: vid, pcp, tpid, but not eid. (requires kernel 4.9) +- vlan: vid, pcp, but not eid. (requires kernel 4.9) - ipv4/6: src and dst (with variable masks), and ip_proto (0xffff mask). - udp/tcp: src and dst port (0xffff) mask. @@ -127,7 +117,7 @@ Supported actions: - DROP - QUEUE - PASSTHRU -- RSS +- RSS (requires kernel 4.9) It is generally not possible to provide a "last" item. However, if the "last" item, once masked, is identical to the masked spec, then it is supported. @@ -162,10 +152,26 @@ Distribute IPv4 TCP packets using RSS to a given MAC address over queues 0-3:: testpmd> flow create 0 priority 4 ingress pattern eth dst is 0a:0b:0c:0d:0e:0f \ / ipv4 / tcp / end actions rss queues 0 1 2 3 end / end +Multi-process sharing +--------------------- + +It is possible to attach an existing TAP device in a secondary process, +by declaring it as a vdev with the same name as in the primary process, +and without any parameter. + +The port attached in a secondary process will give access to the +statistics and the queues. +Therefore it can be used for monitoring or Rx/Tx processing. + +The IPC synchronization of Rx/Tx queues is currently limited: + + - Maximum 8 queues shared + - Synchronized on probing, but not on later port update + Example ------- -The following is a simple example of using the TUN/TAP PMD with the Pktgen +The following is a simple example of using the TAP PMD with the Pktgen packet generator. It requires that the ``socat`` utility is installed on the test system. @@ -175,8 +181,8 @@ used to build the dpdk you pulled down. Run pktgen from the pktgen directory in a terminal with a commandline like the following:: - sudo ./app/app/x86_64-native-linuxapp-gcc/app/pktgen -l 1-5 -n 4 \ - --proc-type auto --log-level 8 --socket-mem 512,512 --file-prefix pg \ + sudo ./app/app/x86_64-native-linux-gcc/app/pktgen -l 1-5 -n 4 \ + --proc-type auto --log-level debug --socket-mem 512,512 --file-prefix pg \ --vdev=net_tap0 --vdev=net_tap1 -b 05:00.0 -b 05:00.1 \ -b 04:00.0 -b 04:00.1 -b 04:00.2 -b 04:00.3 \ -b 81:00.0 -b 81:00.1 -b 81:00.2 -b 81:00.3 \ @@ -268,3 +274,28 @@ Please refer to ``iproute2`` package file ``lib/bpf.c`` function An example utility for eBPF instruction generation in the format of C arrays will be added in next releases +TAP reports on supported RSS functions as part of dev_infos_get callback: +``ETH_RSS_IP``, ``ETH_RSS_UDP`` and ``ETH_RSS_TCP``. +**Known limitation:** TAP supports all of the above hash functions together +and not in partial combinations. + +Systems supporting flow API +--------------------------- + +- "tc flower" classifier requires linux kernel above 4.2 +- eBPF/RSS requires linux kernel above 4.9 + ++--------------------+-----------------------+ +| RH7.3 | No flow rule support | ++--------------------+-----------------------+ +| RH7.4 | No RSS action support | ++--------------------+-----------------------+ +| RH7.5 | No RSS action support | ++--------------------+-----------------------+ +| SLES 15, | No limitation | +| kernel 4.12 | | ++--------------------+-----------------------+ +| Azure Ubuntu 16.04,| No limitation | +| kernel 4.13 | | ++--------------------+-----------------------+ +