]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. BSD LICENSE |
2 | Copyright (c) 2016 Solarflare Communications Inc. | |
3 | All rights reserved. | |
4 | ||
5 | This software was jointly developed between OKTET Labs (under contract | |
6 | for Solarflare) and Solarflare Communications, Inc. | |
7 | ||
8 | Redistribution and use in source and binary forms, with or without | |
9 | modification, are permitted provided that the following conditions are met: | |
10 | ||
11 | 1. Redistributions of source code must retain the above copyright notice, | |
12 | this list of conditions and the following disclaimer. | |
13 | 2. Redistributions in binary form must reproduce the above copyright notice, | |
14 | this list of conditions and the following disclaimer in the documentation | |
15 | and/or other materials provided with the distribution. | |
16 | ||
17 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | |
18 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, | |
19 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | |
20 | PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR | |
21 | CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | |
22 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, | |
23 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; | |
24 | OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, | |
25 | WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR | |
26 | OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, | |
27 | EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
28 | ||
29 | Solarflare libefx-based Poll Mode Driver | |
30 | ======================================== | |
31 | ||
32 | The SFC EFX PMD (**librte_pmd_sfc_efx**) provides poll mode driver support | |
33 | for **Solarflare SFN7xxx and SFN8xxx** family of 10/40 Gbps adapters and | |
34 | **Solarflare XtremeScale X2xxx** family of 10/25/40/50/100 Gbps adapters. | |
35 | SFC EFX PMD has support for the latest Linux and FreeBSD operating systems. | |
36 | ||
37 | More information can be found at `Solarflare Communications website | |
38 | <http://solarflare.com>`_. | |
39 | ||
40 | ||
41 | Features | |
42 | -------- | |
43 | ||
44 | SFC EFX PMD has support for: | |
45 | ||
46 | - Multiple transmit and receive queues | |
47 | ||
48 | - Link state information including link status change interrupt | |
49 | ||
50 | - IPv4/IPv6 TCP/UDP transmit checksum offload | |
51 | ||
52 | - Inner IPv4/IPv6 TCP/UDP transmit checksum offload | |
53 | ||
54 | - Port hardware statistics | |
55 | ||
56 | - Extended statistics (see Solarflare Server Adapter User's Guide for | |
57 | the statistics description) | |
58 | ||
59 | - Basic flow control | |
60 | ||
61 | - MTU update | |
62 | ||
63 | - Jumbo frames up to 9K | |
64 | ||
65 | - Promiscuous mode | |
66 | ||
67 | - Allmulticast mode | |
68 | ||
9f95a23c | 69 | - TCP segmentation offload (TSO) including VXLAN and GENEVE encapsulated |
11fdf7f2 TL |
70 | |
71 | - Multicast MAC filter | |
72 | ||
73 | - IPv4/IPv6 TCP/UDP receive checksum offload | |
74 | ||
75 | - Inner IPv4/IPv6 TCP/UDP receive checksum offload | |
76 | ||
77 | - Received packet type information | |
78 | ||
79 | - Receive side scaling (RSS) | |
80 | ||
81 | - RSS hash | |
82 | ||
83 | - Scattered Rx DMA for packet that are larger that a single Rx descriptor | |
84 | ||
85 | - Deferred receive and transmit queue start | |
86 | ||
87 | - Transmit VLAN insertion (if running firmware variant supports it) | |
88 | ||
89 | - Flow API | |
90 | ||
91 | - Loopback | |
92 | ||
93 | ||
94 | Non-supported Features | |
95 | ---------------------- | |
96 | ||
97 | The features not yet supported include: | |
98 | ||
9f95a23c | 99 | - Receive queue interrupts |
11fdf7f2 TL |
100 | |
101 | - Priority-based flow control | |
102 | ||
103 | - Configurable RX CRC stripping (always stripped) | |
104 | ||
105 | - Header split on receive | |
106 | ||
107 | - VLAN filtering | |
108 | ||
109 | - VLAN stripping | |
110 | ||
111 | - LRO | |
112 | ||
113 | ||
114 | Limitations | |
115 | ----------- | |
116 | ||
117 | Due to requirements on receive buffer alignment and usage of the receive | |
118 | buffer for the auxiliary packet information provided by the NIC up to | |
119 | extra 269 (14 bytes prefix plus up to 255 bytes for end padding) bytes may be | |
120 | required in the receive buffer. | |
121 | It should be taken into account when mbuf pool for receive is created. | |
122 | ||
123 | ||
124 | Equal stride super-buffer mode | |
125 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
126 | ||
127 | When the receive queue uses equal stride super-buffer DMA mode, one HW Rx | |
128 | descriptor carries many Rx buffers which contiguously follow each other | |
129 | with some stride (equal to total size of rte_mbuf as mempool object). | |
130 | Each Rx buffer is an independent rte_mbuf. | |
131 | However dedicated mempool manager must be used when mempool for the Rx | |
132 | queue is created. The manager must support dequeue of the contiguous | |
133 | block of objects and provide mempool info API to get the block size. | |
134 | ||
135 | Another limitation of a equal stride super-buffer mode, imposed by the | |
136 | firmware, is that it allows for a single RSS context. | |
137 | ||
138 | ||
139 | Tunnels support | |
140 | --------------- | |
141 | ||
142 | NVGRE, VXLAN and GENEVE tunnels are supported on SFN8xxx and X2xxx family | |
143 | adapters with full-feature firmware variant running. | |
144 | **sfboot** should be used to configure NIC to run full-feature firmware variant. | |
145 | See Solarflare Server Adapter User's Guide for details. | |
146 | ||
147 | SFN8xxx and X2xxx family adapters provide either inner or outer packet classes. | |
148 | If adapter firmware advertises support for tunnels then the PMD | |
149 | configures the hardware to report inner classes, and outer classes are | |
150 | not reported in received packets. | |
151 | However, for VXLAN and GENEVE tunnels the PMD does report UDP as the | |
152 | outer layer 4 packet type. | |
153 | ||
154 | SFN8xxx and X2xxx family adapters report GENEVE packets as VXLAN. | |
155 | If UDP ports are configured for only one tunnel type then it is safe to | |
156 | treat VXLAN packet type indication as the corresponding UDP tunnel type. | |
157 | ||
158 | ||
159 | Flow API support | |
160 | ---------------- | |
161 | ||
162 | Supported attributes: | |
163 | ||
164 | - Ingress | |
165 | ||
166 | Supported pattern items: | |
167 | ||
168 | - VOID | |
169 | ||
170 | - ETH (exact match of source/destination addresses, individual/group match | |
171 | of destination address, EtherType in the outer frame and exact match of | |
172 | destination addresses, individual/group match of destination address in | |
173 | the inner frame) | |
174 | ||
175 | - VLAN (exact match of VID, double-tagging is supported) | |
176 | ||
177 | - IPV4 (exact match of source/destination addresses, | |
178 | IP transport protocol) | |
179 | ||
180 | - IPV6 (exact match of source/destination addresses, | |
181 | IP transport protocol) | |
182 | ||
183 | - TCP (exact match of source/destination ports) | |
184 | ||
185 | - UDP (exact match of source/destination ports) | |
186 | ||
187 | - VXLAN (exact match of VXLAN network identifier) | |
188 | ||
189 | - GENEVE (exact match of virtual network identifier, only Ethernet (0x6558) | |
190 | protocol type is supported) | |
191 | ||
192 | - NVGRE (exact match of virtual subnet ID) | |
193 | ||
194 | Supported actions: | |
195 | ||
196 | - VOID | |
197 | ||
198 | - QUEUE | |
199 | ||
200 | - RSS | |
201 | ||
202 | - DROP | |
203 | ||
204 | - FLAG (supported only with ef10_essb Rx datapath) | |
205 | ||
206 | - MARK (supported only with ef10_essb Rx datapath) | |
207 | ||
208 | Validating flow rules depends on the firmware variant. | |
209 | ||
9f95a23c TL |
210 | The :ref:`flow_isolated_mode` is supported. |
211 | ||
212 | Ethernet destination individual/group match | |
213 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11fdf7f2 TL |
214 | |
215 | Ethernet item supports I/G matching, if only the corresponding bit is set | |
9f95a23c TL |
216 | in the mask of destination address. If destination address in the spec is |
217 | multicast, it matches all multicast (and broadcast) packets, otherwise it | |
11fdf7f2 TL |
218 | matches unicast packets that are not filtered by other flow rules. |
219 | ||
220 | Exceptions to flow rules | |
221 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
222 | ||
223 | There is a list of exceptional flow rule patterns which will not be | |
224 | accepted by the PMD. A pattern will be rejected if at least one of the | |
225 | conditions is met: | |
226 | ||
227 | - Filtering by IPv4 or IPv6 EtherType without pattern items of internet | |
228 | layer and above. | |
229 | ||
230 | - The last item is IPV4 or IPV6, and it's empty. | |
231 | ||
232 | - Filtering by TCP or UDP IP transport protocol without pattern items of | |
233 | transport layer and above. | |
234 | ||
235 | - The last item is TCP or UDP, and it's empty. | |
236 | ||
237 | ||
238 | Supported NICs | |
239 | -------------- | |
240 | ||
241 | - Solarflare XtremeScale Adapters: | |
242 | ||
243 | - Solarflare X2522 Dual Port SFP28 10/25GbE Adapter | |
244 | ||
9f95a23c TL |
245 | - Solarflare X2541 Single Port QSFP28 10/25G/100G Adapter |
246 | ||
247 | - Solarflare X2542 Dual Port QSFP28 10/25G/100G Adapter | |
248 | ||
11fdf7f2 TL |
249 | - Solarflare Flareon [Ultra] Server Adapters: |
250 | ||
251 | - Solarflare SFN8522 Dual Port SFP+ Server Adapter | |
252 | ||
253 | - Solarflare SFN8522M Dual Port SFP+ Server Adapter | |
254 | ||
255 | - Solarflare SFN8042 Dual Port QSFP+ Server Adapter | |
256 | ||
257 | - Solarflare SFN8542 Dual Port QSFP+ Server Adapter | |
258 | ||
259 | - Solarflare SFN8722 Dual Port SFP+ OCP Server Adapter | |
260 | ||
261 | - Solarflare SFN7002F Dual Port SFP+ Server Adapter | |
262 | ||
263 | - Solarflare SFN7004F Quad Port SFP+ Server Adapter | |
264 | ||
265 | - Solarflare SFN7042Q Dual Port QSFP+ Server Adapter | |
266 | ||
267 | - Solarflare SFN7122F Dual Port SFP+ Server Adapter | |
268 | ||
269 | - Solarflare SFN7124F Quad Port SFP+ Server Adapter | |
270 | ||
271 | - Solarflare SFN7142Q Dual Port QSFP+ Server Adapter | |
272 | ||
273 | - Solarflare SFN7322F Precision Time Synchronization Server Adapter | |
274 | ||
275 | ||
276 | Prerequisites | |
277 | ------------- | |
278 | ||
279 | - Requires firmware version: | |
280 | ||
281 | - SFN7xxx: **4.7.1.1001** or higher | |
282 | ||
283 | - SFN8xxx: **6.0.2.1004** or higher | |
284 | ||
285 | Visit `Solarflare Support Downloads <https://support.solarflare.com>`_ to get | |
286 | Solarflare Utilities (either Linux or FreeBSD) with the latest firmware. | |
287 | Follow instructions from Solarflare Server Adapter User's Guide to | |
288 | update firmware and configure the adapter. | |
289 | ||
290 | ||
291 | Pre-Installation Configuration | |
292 | ------------------------------ | |
293 | ||
294 | ||
295 | Config File Options | |
296 | ~~~~~~~~~~~~~~~~~~~ | |
297 | ||
298 | The following options can be modified in the ``.config`` file. | |
299 | Please note that enabling debugging options may affect system performance. | |
300 | ||
301 | - ``CONFIG_RTE_LIBRTE_SFC_EFX_PMD`` (default **y**) | |
302 | ||
303 | Enable compilation of Solarflare libefx-based poll-mode driver. | |
304 | ||
305 | - ``CONFIG_RTE_LIBRTE_SFC_EFX_DEBUG`` (default **n**) | |
306 | ||
307 | Enable compilation of the extra run-time consistency checks. | |
308 | ||
309 | ||
310 | Per-Device Parameters | |
311 | ~~~~~~~~~~~~~~~~~~~~~ | |
312 | ||
313 | The following per-device parameters can be passed via EAL PCI device | |
314 | whitelist option like "-w 02:00.0,arg1=value1,...". | |
315 | ||
316 | Case-insensitive 1/y/yes/on or 0/n/no/off may be used to specify | |
317 | boolean parameters value. | |
318 | ||
319 | - ``rx_datapath`` [auto|efx|ef10|ef10_esps] (default **auto**) | |
320 | ||
321 | Choose receive datapath implementation. | |
322 | **auto** allows the driver itself to make a choice based on firmware | |
323 | features available and required by the datapath implementation. | |
324 | **efx** chooses libefx-based datapath which supports Rx scatter. | |
325 | **ef10** chooses EF10 (SFN7xxx, SFN8xxx, X2xxx) native datapath which is | |
326 | more efficient than libefx-based and provides richer packet type | |
9f95a23c | 327 | classification. |
11fdf7f2 TL |
328 | **ef10_esps** chooses SFNX2xxx equal stride packed stream datapath |
329 | which may be used on DPDK firmware variant only | |
330 | (see notes about its limitations above). | |
331 | ||
332 | - ``tx_datapath`` [auto|efx|ef10|ef10_simple] (default **auto**) | |
333 | ||
334 | Choose transmit datapath implementation. | |
335 | **auto** allows the driver itself to make a choice based on firmware | |
336 | features available and required by the datapath implementation. | |
337 | **efx** chooses libefx-based datapath which supports VLAN insertion | |
338 | (full-feature firmware variant only), TSO and multi-segment mbufs. | |
339 | Mbuf segments may come from different mempools, and mbuf reference | |
340 | counters are treated responsibly. | |
341 | **ef10** chooses EF10 (SFN7xxx, SFN8xxx, X2xxx) native datapath which is | |
9f95a23c | 342 | more efficient than libefx-based but has no VLAN insertion support yet. |
11fdf7f2 TL |
343 | Mbuf segments may come from different mempools, and mbuf reference |
344 | counters are treated responsibly. | |
345 | **ef10_simple** chooses EF10 (SFN7xxx, SFN8xxx, X2xxx) native datapath which | |
346 | is even more faster then **ef10** but does not support multi-segment | |
347 | mbufs, disallows multiple mempools and neglects mbuf reference counters. | |
348 | ||
349 | - ``perf_profile`` [auto|throughput|low-latency] (default **throughput**) | |
350 | ||
9f95a23c | 351 | Choose hardware tuning to be optimized for either throughput or |
11fdf7f2 TL |
352 | low-latency. |
353 | **auto** allows NIC firmware to make a choice based on | |
9f95a23c | 354 | installed licenses and firmware variant configured using **sfboot**. |
11fdf7f2 TL |
355 | |
356 | - ``stats_update_period_ms`` [long] (default **1000**) | |
357 | ||
358 | Adjust period in milliseconds to update port hardware statistics. | |
359 | The accepted range is 0 to 65535. The value of **0** may be used | |
360 | to disable periodic statistics update. One should note that it's | |
361 | only possible to set an arbitrary value on SFN8xxx and X2xxx provided that | |
362 | firmware version is 6.2.1.1033 or higher, otherwise any positive | |
363 | value will select a fixed update period of **1000** milliseconds | |
364 | ||
365 | - ``fw_variant`` [dont-care|full-feature|ultra-low-latency| | |
366 | capture-packed-stream|dpdk] (default **dont-care**) | |
367 | ||
368 | Choose the preferred firmware variant to use. In order for the selected | |
369 | option to have an effect, the **sfboot** utility must be configured with the | |
370 | **auto** firmware-variant option. The preferred firmware variant applies to | |
371 | all ports on the NIC. | |
372 | **dont-care** ensures that the driver can attach to an unprivileged function. | |
373 | The datapath firmware type to use is controlled by the **sfboot** | |
374 | utility. | |
375 | **full-feature** chooses full featured firmware. | |
376 | **ultra-low-latency** chooses firmware with fewer features but lower latency. | |
377 | **capture-packed-stream** chooses firmware for SolarCapture packed stream | |
378 | mode. | |
379 | **dpdk** chooses DPDK firmware with equal stride super-buffer Rx mode | |
380 | for higher Rx packet rate and packet marks support and firmware subvariant | |
381 | without checksumming on transmit for higher Tx packet rate if | |
382 | checksumming is not required. | |
383 | ||
384 | - ``rxd_wait_timeout_ns`` [long] (default **200 us**) | |
385 | ||
386 | Adjust timeout in nanoseconds to head-of-line block to wait for | |
387 | Rx descriptors. | |
388 | The accepted range is 0 to 400 ms. | |
389 | Flow control should be enabled to make it work. | |
390 | The value of **0** disables it and packets are dropped immediately. | |
391 | When a packet is dropped because of no Rx descriptors, | |
392 | ``rx_nodesc_drop_cnt`` counter grows. | |
393 | The feature is supported only by the DPDK firmware variant when equal | |
394 | stride super-buffer Rx mode is used. | |
395 | ||
396 | ||
397 | Dynamic Logging Parameters | |
398 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
399 | ||
400 | One may leverage EAL option "--log-level" to change default levels | |
401 | for the log types supported by the driver. The option is used with | |
402 | an argument typically consisting of two parts separated by a colon. | |
403 | ||
404 | Level value is the last part which takes a symbolic name (or integer). | |
405 | Log type is the former part which may shell match syntax. | |
406 | Depending on the choice of the expression, the given log level may | |
407 | be used either for some specific log type or for a subset of types. | |
408 | ||
409 | SFC EFX PMD provides the following log types available for control: | |
410 | ||
411 | - ``pmd.net.sfc.driver`` (default level is **notice**) | |
412 | ||
413 | Affects driver-wide messages unrelated to any particular devices. | |
414 | ||
415 | - ``pmd.net.sfc.main`` (default level is **notice**) | |
416 | ||
417 | Matches a subset of per-port log types registered during runtime. | |
418 | A full name for a particular type may be obtained by appending a | |
419 | dot and a PCI device identifier (``XXXX:XX:XX.X``) to the prefix. | |
420 | ||
421 | - ``pmd.net.sfc.mcdi`` (default level is **notice**) | |
422 | ||
423 | Extra logging of the communication with the NIC's management CPU. | |
424 | The format of the log is consumed by the Solarflare netlogdecode | |
425 | cross-platform tool. May be managed per-port, as explained above. |