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