doc/guides/howto/flow_bifurcation.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2016 Intel Corporation.
   3
   4 Flow Bifurcation How-to Guide
   5 =============================
   6
   7 Flow Bifurcation is a mechanism which uses hardware capable Ethernet devices
   8 to split traffic between Linux user space and kernel space. Since it is a
   9 hardware assisted feature this approach can provide line rate processing
  10 capability. Other than :ref:`KNI <kni>`, the software is just required to
  11 enable device configuration, there is no need to take care of the packet
  12 movement during the traffic split. This can yield better performance with
  13 less CPU overhead.
  14
  15 The Flow Bifurcation splits the incoming data traffic to user space
  16 applications (such as DPDK applications) and/or kernel space programs (such as
  17 the Linux kernel stack). It can direct some traffic, for example data plane
  18 traffic, to DPDK, while directing some other traffic, for example control
  19 plane traffic, to the traditional Linux networking stack.
  20
  21 There are a number of technical options to achieve this. A typical example is
  22 to combine the technology of SR-IOV and packet classification filtering.
  23
  24 SR-IOV is a PCI standard that allows the same physical adapter to be split as
  25 multiple virtual functions. Each virtual function (VF) has separated queues
  26 with physical functions (PF). The network adapter will direct traffic to a
  27 virtual function with a matching destination MAC address. In a sense, SR-IOV
  28 has the capability for queue division.
  29
  30 Packet classification filtering is a hardware capability available on most
  31 network adapters. Filters can be configured to direct specific flows to a
  32 given receive queue by hardware. Different NICs may have different filter
  33 types to direct flows to a Virtual Function or a queue that belong to it.
  34
  35 In this way the Linux networking stack can receive specific traffic through
  36 the kernel driver while a DPDK application can receive specific traffic
  37 bypassing the Linux kernel by using drivers like VFIO or the DPDK ``igb_uio``
  38 module.
  39
  40 .. _figure_flow_bifurcation_overview:
  41
  42 .. figure:: img/flow_bifurcation_overview.*
  43
  44    Flow Bifurcation Overview
  45
  46
  47 Using Flow Bifurcation on IXGBE in Linux
  48 ----------------------------------------
  49
  50 On Intel 82599 10 Gigabit Ethernet Controller series NICs Flow Bifurcation can
  51 be achieved by SR-IOV and Intel Flow Director technologies. Traffic can be
  52 directed to queues by the Flow Director capability, typically by matching
  53 5-tuple of UDP/TCP packets.
  54
  55 The typical procedure to achieve this is as follows:
  56
  57 #. Boot the system without iommu, or with ``iommu=pt``.
  58
  59 #. Create Virtual Functions:
  60
  61    .. code-block:: console
  62
  63        echo 2 > /sys/bus/pci/devices/0000:01:00.0/sriov_numvfs
  64
  65 #. Enable and set flow filters:
  66
  67    .. code-block:: console
  68
  69        ethtool -K eth1 ntuple on
  70        ethtool -N eth1 flow-type udp4 src-ip 192.0.2.2 dst-ip 198.51.100.2 \
  71                action $queue_index_in_VF0
  72        ethtool -N eth1 flow-type udp4 src-ip 198.51.100.2 dst-ip 192.0.2.2 \
  73                action $queue_index_in_VF1
  74
  75    Where:
  76
  77    * ``$queue_index_in_VFn``: Bits 39:32 of the variable defines VF id + 1; the lower 32 bits indicates the queue index of the VF. Thus:
  78
  79      * ``$queue_index_in_VF0`` = ``(0x1 & 0xFF) << 32 + [queue index]``.
  80
  81      * ``$queue_index_in_VF1`` = ``(0x2 & 0xFF) << 32 + [queue index]``.
  82
  83    .. _figure_ixgbe_bifu_queue_idx:
  84
  85    .. figure:: img/ixgbe_bifu_queue_idx.*
  86
  87 #. Compile the DPDK application and insert ``igb_uio`` or probe the ``vfio-pci`` kernel modules as normal.
  88
  89 #. Bind the virtual functions:
  90
  91    .. code-block:: console
  92
  93        modprobe vfio-pci
  94        dpdk-devbind.py -b vfio-pci 01:10.0
  95        dpdk-devbind.py -b vfio-pci 01:10.1
  96
  97 #. Run a DPDK application on the VFs:
  98
  99    .. code-block:: console
 100
 101        testpmd -l 0-7 -n 4 -- -i -w 01:10.0 -w 01:10.1 --forward-mode=mac
 102
 103 In this example, traffic matching the rules will go through the VF by matching
 104 the filter rule. All other traffic, not matching the rules, will go through
 105 the default queue or scaling on queues in the PF. That is to say UDP packets
 106 with the specified IP source and destination addresses will go through the
 107 DPDK application. All other traffic, with different hosts or different
 108 protocols, will go through the Linux networking stack.
 109
 110 .. note::
 111
 112     * The above steps work on the Linux kernel v4.2.
 113
 114     * The Flow Bifurcation is implemented in Linux kernel and ixgbe kernel driver using the following patches:
 115
 116         * `ethtool: Add helper routines to pass vf to rx_flow_spec <https://patchwork.ozlabs.org/patch/476511/>`_
 117
 118         * `ixgbe: Allow flow director to use entire queue space <https://patchwork.ozlabs.org/patch/476516/>`_
 119
 120     * The Ethtool version used in this example is 3.18.
 121
 122
 123 Using Flow Bifurcation on I40E in Linux
 124 ---------------------------------------
 125
 126 On Intel X710/XL710 series Ethernet Controllers Flow Bifurcation can be
 127 achieved by SR-IOV, Cloud Filter and L3 VEB switch. The traffic can be
 128 directed to queues by the Cloud Filter and L3 VEB switch's matching rule.
 129
 130 * L3 VEB filters work for non-tunneled packets. It can direct a packet just by
 131   the Destination IP address to a queue in a VF.
 132
 133 * Cloud filters work for the following types of tunneled packets.
 134
 135     * Inner mac.
 136
 137     * Inner mac + VNI.
 138
 139     * Outer mac + Inner mac + VNI.
 140
 141     * Inner mac + Inner vlan + VNI.
 142
 143     * Inner mac + Inner vlan.
 144
 145 The typical procedure to achieve this is as follows:
 146
 147 #. Boot the system without iommu, or with ``iommu=pt``.
 148
 149 #. Build and insert the ``i40e.ko`` module.
 150
 151 #. Create Virtual Functions:
 152
 153    .. code-block:: console
 154
 155        echo 2 > /sys/bus/pci/devices/0000:01:00.0/sriov_numvfs
 156
 157 #. Add udp port offload to the NIC if using cloud filter:
 158
 159    .. code-block:: console
 160
 161        ip li add vxlan0 type vxlan id 42 group 239.1.1.1 local 10.16.43.214 dev <name>
 162        ifconfig vxlan0 up
 163        ip -d li show vxlan0
 164
 165    .. note::
 166
 167        Output such as ``add vxlan port 8472, index 0 success`` should be
 168        found in the system log.
 169
 170 #. Examples of enabling and setting flow filters:
 171
 172    * L3 VEB filter, for a route whose destination IP is 192.168.50.108 to VF
 173      0's queue 2.
 174
 175      .. code-block:: console
 176
 177        ethtool -N <dev_name> flow-type ip4 dst-ip 192.168.50.108 \
 178                user-def 0xffffffff00000000 action 2 loc 8
 179
 180    * Inner mac, for a route whose inner destination mac is 0:0:0:0:9:0 to
 181      PF's queue 6.
 182
 183      .. code-block:: console
 184
 185        ethtool -N <dev_name> flow-type ether dst 00:00:00:00:00:00 \
 186                m ff:ff:ff:ff:ff:ff src 00:00:00:00:09:00 m 00:00:00:00:00:00 \
 187                user-def 0xffffffff00000003 action 6 loc 1
 188
 189    * Inner mac + VNI, for a route whose inner destination mac is 0:0:0:0:9:0
 190      and VNI is 8 to PF's queue 4.
 191
 192      .. code-block:: console
 193
 194        ethtool -N <dev_name> flow-type ether dst 00:00:00:00:00:00 \
 195                m ff:ff:ff:ff:ff:ff src 00:00:00:00:09:00 m 00:00:00:00:00:00 \
 196                user-def 0x800000003 action 4 loc 4
 197
 198    * Outer mac + Inner mac + VNI, for a route whose outer mac is
 199      68:05:ca:24:03:8b, inner destination mac is c2:1a:e1:53:bc:57, and VNI
 200      is 8 to PF's queue 2.
 201
 202      .. code-block:: console
 203
 204        ethtool -N <dev_name> flow-type ether dst 68:05:ca:24:03:8b \
 205                m 00:00:00:00:00:00 src c2:1a:e1:53:bc:57 m 00:00:00:00:00:00 \
 206                user-def 0x800000003 action 2 loc 2
 207
 208    * Inner mac + Inner vlan + VNI, for a route whose inner destination mac is
 209      00:00:00:00:20:00, inner vlan is 10, and VNI is 8 to VF 0's queue 1.
 210
 211      .. code-block:: console
 212
 213        ethtool -N <dev_name> flow-type ether dst 00:00:00:00:01:00 \
 214                m ff:ff:ff:ff:ff:ff src 00:00:00:00:20:00 m 00:00:00:00:00:00 \
 215                vlan 10 user-def 0x800000000 action 1 loc 5
 216
 217    * Inner mac + Inner vlan, for a route whose inner destination mac is
 218      00:00:00:00:20:00, and inner vlan is 10 to VF 0's queue 1.
 219
 220      .. code-block:: console
 221
 222        ethtool -N <dev_name> flow-type ether dst 00:00:00:00:01:00 \
 223                m ff:ff:ff:ff:ff:ff src 00:00:00:00:20:00 m 00:00:00:00:00:00 \
 224                vlan 10 user-def 0xffffffff00000000 action 1 loc 5
 225
 226    .. note::
 227
 228        * If the upper 32 bits of 'user-def' are ``0xffffffff``, then the
 229          filter can be used for programming an L3 VEB filter, otherwise the
 230          upper 32 bits of 'user-def' can carry the tenant ID/VNI if
 231          specified/required.
 232
 233        * Cloud filters can be defined with inner mac, outer mac, inner ip,
 234          inner vlan and VNI as part of the cloud tuple. It is always the
 235          destination (not source) mac/ip that these filters use. For all
 236          these examples dst and src mac address fields are overloaded dst ==
 237          outer, src == inner.
 238
 239        * The filter will direct a packet matching the rule to a vf id
 240          specified in the lower 32 bit of user-def to the queue specified by
 241          'action'.
 242
 243        * If the vf id specified by the lower 32 bit of user-def is greater
 244          than or equal to ``max_vfs``, then the filter is for the PF queues.
 245
 246 #. Compile the DPDK application and insert ``igb_uio`` or probe the ``vfio-pci``
 247    kernel modules as normal.
 248
 249 #. Bind the virtual function:
 250
 251    .. code-block:: console
 252
 253        modprobe vfio-pci
 254        dpdk-devbind.py -b vfio-pci 01:10.0
 255        dpdk-devbind.py -b vfio-pci 01:10.1
 256
 257 #. run DPDK application on VFs:
 258
 259    .. code-block:: console
 260
 261        testpmd -l 0-7 -n 4 -- -i -w 01:10.0 -w 01:10.1 --forward-mode=mac
 262
 263 .. note::
 264
 265    * The above steps work on the i40e Linux kernel driver v1.5.16.
 266
 267    * The Ethtool version used in this example is 3.18. The mask ``ff`` means
 268      'not involved', while ``00`` or no mask means 'involved'.
 269
 270    * For more details of the configuration, refer to the
 271      `cloud filter test plan <http://dpdk.org/browse/tools/dts/tree/test_plans/cloud_filter_test_plan.rst>`_