doc: add packet framework update in release notes
[dpdk.git] / 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>`_