fm10k.rst revision 8b25d1ad
1..  BSD LICENSE
2    Copyright(c) 2015-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
31FM10K Poll Mode Driver
32======================
33
34The FM10K poll mode driver library provides support for the Intel FM10000
35(FM10K) family of 40GbE/100GbE adapters.
36
37FTAG Based Forwarding of FM10K
38------------------------------
39
40FTAG Based Forwarding is a unique feature of FM10K. The FM10K family of NICs
41support the addition of a Fabric Tag (FTAG) to carry special information.
42The FTAG is placed at the beginning of the frame, it contains information
43such as where the packet comes from and goes, and the vlan tag. In FTAG based
44forwarding mode, the switch logic forwards packets according to glort (global
45resource tag) information, rather than the mac and vlan table. Currently this
46feature works only on PF.
47
48To enable this feature, the user should pass a devargs parameter to the eal
49like "-w 84:00.0,enable_ftag=1", and the application should make sure an
50appropriate FTAG is inserted for every frame on TX side.
51
52Vector PMD for FM10K
53--------------------
54
55Vector PMD (vPMD) uses Intel® SIMD instructions to optimize packet I/O.
56It improves load/store bandwidth efficiency of L1 data cache by using a wider
57SSE/AVX ''register (1)''.
58The wider register gives space to hold multiple packet buffers so as to save
59on the number of instructions when bulk processing packets.
60
61There is no change to the PMD API. The RX/TX handlers are the only two entries for
62vPMD packet I/O. They are transparently registered at runtime RX/TX execution
63if all required conditions are met.
64
651.  To date, only an SSE version of FM10K vPMD is available.
66    To ensure that vPMD is in the binary code, set
67    ``CONFIG_RTE_LIBRTE_FM10K_INC_VECTOR=y`` in the configure file.
68
69Some constraints apply as pre-conditions for specific optimizations on bulk
70packet transfers. The following sections explain RX and TX constraints in the
71vPMD.
72
73
74RX Constraints
75~~~~~~~~~~~~~~
76
77
78Prerequisites and Pre-conditions
79^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
80
81For Vector RX it is assumed that the number of descriptor rings will be a power
82of 2. With this pre-condition, the ring pointer can easily scroll back to the
83head after hitting the tail without a conditional check. In addition Vector RX
84can use this assumption to do a bit mask using ``ring_size - 1``.
85
86
87Features not Supported by Vector RX PMD
88^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
89
90Some features are not supported when trying to increase the throughput in
91vPMD. They are:
92
93*   IEEE1588
94
95*   Flow director
96
97*   Header split
98
99*   RX checksum offload
100
101Other features are supported using optional MACRO configuration. They include:
102
103*   HW VLAN strip
104
105*   L3/L4 packet type
106
107To enable via ``RX_OLFLAGS`` use ``RTE_LIBRTE_FM10K_RX_OLFLAGS_ENABLE=y``.
108
109To guarantee the constraint, the following configuration flags in ``dev_conf.rxmode``
110will be checked:
111
112*   ``hw_vlan_extend``
113
114*   ``hw_ip_checksum``
115
116*   ``header_split``
117
118*   ``fdir_conf->mode``
119
120
121RX Burst Size
122^^^^^^^^^^^^^
123
124As vPMD is focused on high throughput, it processes 4 packets at a time. So it assumes
125that the RX burst should be greater than 4 packets per burst. It returns zero if using
126``nb_pkt`` < 4 in the receive handler. If ``nb_pkt`` is not a multiple of 4, a
127floor alignment will be applied.
128
129
130TX Constraint
131~~~~~~~~~~~~~
132
133Features not Supported by TX Vector PMD
134^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
135
136TX vPMD only works when ``txq_flags`` is set to ``FM10K_SIMPLE_TX_FLAG``.
137This means that it does not support TX multi-segment, VLAN offload or TX csum
138offload. The following MACROs are used for these three features:
139
140*   ``ETH_TXQ_FLAGS_NOMULTSEGS``
141
142*   ``ETH_TXQ_FLAGS_NOVLANOFFL``
143
144*   ``ETH_TXQ_FLAGS_NOXSUMSCTP``
145
146*   ``ETH_TXQ_FLAGS_NOXSUMUDP``
147
148*   ``ETH_TXQ_FLAGS_NOXSUMTCP``
149
150Limitations
151-----------
152
153
154Switch manager
155~~~~~~~~~~~~~~
156
157The Intel FM10000 family of NICs integrate a hardware switch and multiple host
158interfaces. The FM10000 PMD driver only manages host interfaces. For the
159switch component another switch driver has to be loaded prior to to the
160FM10000 PMD driver. The switch driver can be acquired from Intel support.
161Only Testpoint is validated with DPDK, the latest version that has been
162validated with DPDK is 4.1.6.
163
164CRC striping
165~~~~~~~~~~~~
166
167The FM10000 family of NICs strip the CRC for every packets coming into the
168host interface.  So, CRC will be stripped even when the
169``rxmode.hw_strip_crc`` member is set to 0 in ``struct rte_eth_conf``.
170
171
172Maximum packet length
173~~~~~~~~~~~~~~~~~~~~~
174
175The FM10000 family of NICS support a maximum of a 15K jumbo frame. The value
176is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
177member of ``struct rte_eth_conf`` is set to a value lower than 15364, frames
178up to 15364 bytes can still reach the host interface.
179
180Statistic Polling Frequency
181~~~~~~~~~~~~~~~~~~~~~~~~~~~
182
183The FM10000 NICs expose a set of statistics via the PCI BARs. These statistics
184are read from the hardware registers when ``rte_eth_stats_get()`` or
185``rte_eth_xstats_get()`` is called. The packet counting registers are 32 bits
186while the byte counting registers are 48 bits. As a result, the statistics must
187be polled regularly in order to ensure the consistency of the returned reads.
188
189Given the PCIe Gen3 x8, about 50Gbps of traffic can occur. With 64 byte packets
190this gives almost 100 million packets/second, causing 32 bit integer overflow
191after approx 40 seconds. To ensure these overflows are detected and accounted
192for in the statistics, it is necessary to read statistic regularly. It is
193suggested to read stats every 20 seconds, which will ensure the statistics
194are accurate.
195
196
197Interrupt mode
198~~~~~~~~~~~~~~
199
200The FM10000 family of NICS need one separate interrupt for mailbox. So only
201drivers which support multiple interrupt vectors e.g. vfio-pci can work
202for fm10k interrupt mode.
203