doc/guides/nics/sfc_efx.rst

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