doc/guides/nics/enic.rst

   1 ..  BSD LICENSE
   2     Copyright (c) 2017, Cisco Systems, Inc.
   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     1. Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11
  12     2. Redistributions in binary form must reproduce the above copyright
  13     notice, this list of conditions and the following disclaimer in
  14     the documentation and/or other materials provided with the
  15     distribution.
  16
  17     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  20     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  21     COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  23     BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  24     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  25     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26     LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  27     ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28     POSSIBILITY OF SUCH DAMAGE.
  29
  30 ENIC Poll Mode Driver
  31 =====================
  32
  33 ENIC PMD is the DPDK poll-mode driver for the Cisco System Inc. VIC Ethernet
  34 NICs. These adapters are also referred to as vNICs below. If you are running
  35 or would like to run DPDK software applications on Cisco UCS servers using
  36 Cisco VIC adapters the following documentation is relevant.
  37
  38 How to obtain ENIC PMD integrated DPDK
  39 --------------------------------------
  40
  41 ENIC PMD support is integrated into the DPDK suite. dpdk-<version>.tar.gz
  42 should be downloaded from http://dpdk.org
  43
  44
  45 Configuration information
  46 -------------------------
  47
  48 - **DPDK Configuration Parameters**
  49
  50   The following configuration options are available for the ENIC PMD:
  51
  52   - **CONFIG_RTE_LIBRTE_ENIC_PMD** (default y): Enables or disables inclusion
  53     of the ENIC PMD driver in the DPDK compilation.
  54
  55   - **CONFIG_RTE_LIBRTE_ENIC_DEBUG** (default n): Enables or disables debug
  56     logging within the ENIC PMD driver.
  57
  58   - **CONFIG_RTE_LIBRTE_ENIC_DEBUG_FLOW** (default n): Enables or disables flow
  59     API related debug logging within the ENIC PMD driver.
  60
  61 - **vNIC Configuration Parameters**
  62
  63   - **Number of Queues**
  64
  65     The maximum number of receive queues (RQs), work queues (WQs) and
  66     completion queues (CQs) are configurable on a per vNIC basis
  67     through the Cisco UCS Manager (CIMC or UCSM).
  68
  69     These values should be configured as follows:
  70
  71     - The number of WQs should be greater or equal to the value of the
  72       expected nb_tx_q parameter in the call to
  73       rte_eth_dev_configure()
  74
  75     - The number of RQs configured in the vNIC should be greater or
  76       equal to *twice* the value of the expected nb_rx_q parameter in
  77       the call to rte_eth_dev_configure().  With the addition of Rx
  78       scatter, a pair of RQs on the vnic is needed for each receive
  79       queue used by DPDK, even if Rx scatter is not being used.
  80       Having a vNIC with only 1 RQ is not a valid configuration, and
  81       will fail with an error message.
  82
  83     - The number of CQs should set so that there is one CQ for each
  84       WQ, and one CQ for each pair of RQs.
  85
  86     For example: If the application requires 3 Rx queues, and 3 Tx
  87     queues, the vNIC should be configured to have at least 3 WQs, 6
  88     RQs (3 pairs), and 6 CQs (3 for use by WQs + 3 for use by the 3
  89     pairs of RQs).
  90
  91   - **Size of Queues**
  92
  93     Likewise, the number of receive and transmit descriptors are configurable on
  94     a per-vNIC basis via the UCS Manager and should be greater than or equal to
  95     the nb_rx_desc and   nb_tx_desc parameters expected to be used in the calls
  96     to rte_eth_rx_queue_setup() and rte_eth_tx_queue_setup() respectively.
  97     An application requesting more than the set size will be limited to that
  98     size.
  99
 100     Unless there is a lack of resources due to creating many vNICs, it
 101     is recommended that the WQ and RQ sizes be set to the maximum.  This
 102     gives the application the greatest amount of flexibility in its
 103     queue configuration.
 104
 105     - *Note*: Since the introduction of Rx scatter, for performance
 106       reasons, this PMD uses two RQs on the vNIC per receive queue in
 107       DPDK.  One RQ holds descriptors for the start of a packet, and the
 108       second RQ holds the descriptors for the rest of the fragments of
 109       a packet.  This means that the nb_rx_desc parameter to
 110       rte_eth_rx_queue_setup() can be a greater than 4096.  The exact
 111       amount will depend on the size of the mbufs being used for
 112       receives, and the MTU size.
 113
 114       For example: If the mbuf size is 2048, and the MTU is 9000, then
 115       receiving a full size packet will take 5 descriptors, 1 from the
 116       start-of-packet queue, and 4 from the second queue.  Assuming
 117       that the RQ size was set to the maximum of 4096, then the
 118       application can specify up to 1024 + 4096 as the nb_rx_desc
 119       parameter to rte_eth_rx_queue_setup().
 120
 121   - **Interrupts**
 122
 123     Only one interrupt per vNIC interface should be configured in the UCS
 124     manager regardless of the number receive/transmit queues. The ENIC PMD
 125     uses this interrupt to get information about link status and errors
 126     in the fast path.
 127
 128 .. _enic-flow-director:
 129
 130 Flow director support
 131 ---------------------
 132
 133 Advanced filtering support was added to 1300 series VIC firmware starting
 134 with version 2.0.13 for C-series UCS servers and version 3.1.2 for UCSM
 135 managed blade servers. In order to enable advanced filtering the 'Advanced
 136 filter' radio button should be enabled via CIMC or UCSM followed by a reboot
 137 of the server.
 138
 139 With advanced filters, perfect matching of all fields of IPv4, IPv6 headers
 140 as well as TCP, UDP and SCTP L4 headers is available through flow director.
 141 Masking of these fields for partial match is also supported.
 142
 143 Without advanced filter support, the flow director is limited to IPv4
 144 perfect filtering of the 5-tuple with no masking of fields supported.
 145
 146 SR-IOV mode utilization
 147 -----------------------
 148
 149 UCS blade servers configured with dynamic vNIC connection policies in UCS
 150 manager are capable of supporting assigned devices on virtual machines (VMs)
 151 through a KVM hypervisor. Assigned devices, also known as 'passthrough'
 152 devices, are SR-IOV virtual functions (VFs) on the host which are exposed
 153 to VM instances.
 154
 155 The Cisco Virtual Machine Fabric Extender (VM-FEX) gives the VM a dedicated
 156 interface on the Fabric Interconnect (FI). Layer 2 switching is done at
 157 the FI. This may eliminate the requirement for software switching on the
 158 host to route intra-host VM traffic.
 159
 160 Please refer to `Creating a Dynamic vNIC Connection Policy
 161 <http://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/sw/vm_fex/vmware/gui/config_guide/b_GUI_VMware_VM-FEX_UCSM_Configuration_Guide/b_GUI_VMware_VM-FEX_UCSM_Configuration_Guide_chapter_010.html#task_433E01651F69464783A68E66DA8A47A5>`_
 162 for information on configuring SR-IOV adapter policies using UCS manager.
 163
 164 Once the policies are in place and the host OS is rebooted, VFs should be
 165 visible on the host, E.g.:
 166
 167 .. code-block:: console
 168
 169      # lspci | grep Cisco | grep Ethernet
 170      0d:00.0 Ethernet controller: Cisco Systems Inc VIC Ethernet NIC (rev a2)
 171      0d:00.1 Ethernet controller: Cisco Systems Inc VIC SR-IOV VF (rev a2)
 172      0d:00.2 Ethernet controller: Cisco Systems Inc VIC SR-IOV VF (rev a2)
 173      0d:00.3 Ethernet controller: Cisco Systems Inc VIC SR-IOV VF (rev a2)
 174      0d:00.4 Ethernet controller: Cisco Systems Inc VIC SR-IOV VF (rev a2)
 175      0d:00.5 Ethernet controller: Cisco Systems Inc VIC SR-IOV VF (rev a2)
 176      0d:00.6 Ethernet controller: Cisco Systems Inc VIC SR-IOV VF (rev a2)
 177      0d:00.7 Ethernet controller: Cisco Systems Inc VIC SR-IOV VF (rev a2)
 178
 179 Enable Intel IOMMU on the host and install KVM and libvirt. A VM instance should
 180 be created with an assigned device. When using libvirt, this configuration can
 181 be done within the domain (i.e. VM) config file. For example this entry maps
 182 host VF 0d:00:01 into the VM.
 183
 184 .. code-block:: console
 185
 186     <interface type='hostdev' managed='yes'>
 187       <mac address='52:54:00:ac:ff:b6'/>
 188       <source>
 189         <address type='pci' domain='0x0000' bus='0x0d' slot='0x00' function='0x1'/>
 190       </source>
 191
 192 Alternatively, the configuration can be done in a separate file using the
 193 ``network`` keyword. These methods are described in the libvirt documentation for
 194 `Network XML format <https://libvirt.org/formatnetwork.html>`_.
 195
 196 When the VM instance is started, the ENIC KVM driver will bind the host VF to
 197 vfio, complete provisioning on the FI and bring up the link.
 198
 199 .. note::
 200
 201     It is not possible to use a VF directly from the host because it is not
 202     fully provisioned until the hypervisor brings up the VM that it is assigned
 203     to.
 204
 205 In the VM instance, the VF will now be visible. E.g., here the VF 00:04.0 is
 206 seen on the VM instance and should be available for binding to a DPDK.
 207
 208 .. code-block:: console
 209
 210      # lspci | grep Ether
 211      00:04.0 Ethernet controller: Cisco Systems Inc VIC SR-IOV VF (rev a2)
 212
 213 Follow the normal DPDK install procedure, binding the VF to either ``igb_uio``
 214 or ``vfio`` in non-IOMMU mode.
 215
 216 Please see :ref:`Limitations <enic_limitations>` for limitations in
 217 the use of SR-IOV.
 218
 219 .. _enic-genic-flow-api:
 220
 221 Generic Flow API support
 222 ------------------------
 223
 224 Generic Flow API is supported. The baseline support is:
 225
 226 - **1200 series VICs**
 227
 228   5-tuple exact flow support for 1200 series adapters. This allows:
 229
 230   - Attributes: ingress
 231   - Items: ipv4, ipv6, udp, tcp (must exactly match src/dst IP
 232     addresses and ports and all must be specified)
 233   - Actions: queue and void
 234   - Selectors: 'is'
 235
 236 - **1300 series VICS with advanced filters disabled**
 237
 238   With advanced filters disabled, an IPv4 or IPv6 item must be specified
 239   in the pattern.
 240
 241   - Attributes: ingress
 242   - Items: eth, ipv4, ipv6, udp, tcp, vxlan, inner eth, ipv4, ipv6, udp, tcp
 243   - Actions: queue and void
 244   - Selectors: 'is', 'spec' and 'mask'. 'last' is not supported
 245   - In total, up to 64 bytes of mask is allowed across all headers
 246
 247 - **1300 series VICS with advanced filters enabled**
 248
 249   - Attributes: ingress
 250   - Items: eth, ipv4, ipv6, udp, tcp, vxlan, inner eth, ipv4, ipv6, udp, tcp
 251   - Actions: queue, mark, flag and void
 252   - Selectors: 'is', 'spec' and 'mask'. 'last' is not supported
 253   - In total, up to 64 bytes of mask is allowed across all headers
 254
 255 More features may be added in future firmware and new versions of the VIC.
 256 Please refer to the release notes.
 257
 258 .. _enic_limitations:
 259
 260 Limitations
 261 -----------
 262
 263 - **VLAN 0 Priority Tagging**
 264
 265   If a vNIC is configured in TRUNK mode by the UCS manager, the adapter will
 266   priority tag egress packets according to 802.1Q if they were not already
 267   VLAN tagged by software. If the adapter is connected to a properly configured
 268   switch, there will be no unexpected behavior.
 269
 270   In test setups where an Ethernet port of a Cisco adapter in TRUNK mode is
 271   connected point-to-point to another adapter port or connected though a router
 272   instead of a switch, all ingress packets will be VLAN tagged. Programs such
 273   as l3fwd which do not account for VLAN tags in packets will misbehave. The
 274   solution is to enable VLAN stripping on ingress. The following code fragment is
 275   an example of how to accomplish this:
 276
 277 .. code-block:: console
 278
 279      vlan_offload = rte_eth_dev_get_vlan_offload(port);
 280      vlan_offload |= ETH_VLAN_STRIP_OFFLOAD;
 281      rte_eth_dev_set_vlan_offload(port, vlan_offload);
 282
 283 - Limited flow director support on 1200 series and 1300 series Cisco VIC
 284   adapters with old firmware. Please see :ref:`enic-flow-director`.
 285
 286 - Flow director features are not supported on generation 1 Cisco VIC adapters
 287   (M81KR and P81E)
 288
 289 - **SR-IOV**
 290
 291   - KVM hypervisor support only. VMware has not been tested.
 292   - Requires VM-FEX, and so is only available on UCS managed servers connected
 293     to Fabric Interconnects. It is not on standalone C-Series servers.
 294   - VF devices are not usable directly from the host. They can  only be used
 295     as assigned devices on VM instances.
 296   - Currently, unbind of the ENIC kernel mode driver 'enic.ko' on the VM
 297     instance may hang. As a workaround, enic.ko should be blacklisted or removed
 298     from the boot process.
 299   - pci_generic cannot be used as the uio module in the VM. igb_uio or
 300     vfio in non-IOMMU mode can be used.
 301   - The number of RQs in UCSM dynamic vNIC configurations must be at least 2.
 302   - The number of SR-IOV devices is limited to 256. Components on target system
 303     might limit this number to fewer than 256.
 304
 305 - **Flow API**
 306
 307   - The number of filters that can be specified with the Generic Flow API is
 308     dependent on how many header fields are being masked. Use 'flow create' in
 309     a loop to determine how many filters your VIC will support (not more than
 310     1000 for 1300 series VICs). Filters are checked for matching in the order they
 311     were added. Since there currently is no grouping or priority support,
 312     'catch-all' filters should be added last.
 313
 314 How to build the suite
 315 ----------------------
 316
 317 The build instructions for the DPDK suite should be followed. By default
 318 the ENIC PMD library will be built into the DPDK library.
 319
 320 Refer to the document :ref:`compiling and testing a PMD for a NIC
 321 <pmd_build_and_test>` for details.
 322
 323 For configuring and using UIO and VFIO frameworks, please refer to the
 324 documentation that comes with DPDK suite.
 325
 326 Supported Cisco VIC adapters
 327 ----------------------------
 328
 329 ENIC PMD supports all recent generations of Cisco VIC adapters including:
 330
 331 - VIC 1280
 332 - VIC 1240
 333 - VIC 1225
 334 - VIC 1285
 335 - VIC 1225T
 336 - VIC 1227
 337 - VIC 1227T
 338 - VIC 1380
 339 - VIC 1340
 340 - VIC 1385
 341 - VIC 1387
 342
 343 Supported Operating Systems
 344 ---------------------------
 345
 346 Any Linux distribution fulfilling the conditions described in Dependencies
 347 section of DPDK documentation.
 348
 349 Supported features
 350 ------------------
 351
 352 - Unicast, multicast and broadcast transmission and reception
 353 - Receive queue polling
 354 - Port Hardware Statistics
 355 - Hardware VLAN acceleration
 356 - IP checksum offload
 357 - Receive side VLAN stripping
 358 - Multiple receive and transmit queues
 359 - Flow Director ADD, UPDATE, DELETE, STATS operation support IPv4 and IPv6
 360 - Promiscuous mode
 361 - Setting RX VLAN (supported via UCSM/CIMC only)
 362 - VLAN filtering (supported via UCSM/CIMC only)
 363 - Execution of application by unprivileged system users
 364 - IPV4, IPV6 and TCP RSS hashing
 365 - Scattered Rx
 366 - MTU update
 367 - SR-IOV on UCS managed servers connected to Fabric Interconnects
 368 - Flow API
 369
 370 Known bugs and unsupported features in this release
 371 ---------------------------------------------------
 372
 373 - Signature or flex byte based flow direction
 374 - Drop feature of flow direction
 375 - VLAN based flow direction
 376 - Non-IPV4 flow direction
 377 - Setting of extended VLAN
 378 - UDP RSS hashing
 379 - MTU update only works if Scattered Rx mode is disabled
 380
 381 Prerequisites
 382 -------------
 383
 384 - Prepare the system as recommended by DPDK suite.  This includes environment
 385   variables, hugepages configuration, tool-chains and configuration.
 386 - Insert vfio-pci kernel module using the command 'modprobe vfio-pci' if the
 387   user wants to use VFIO framework.
 388 - Insert uio kernel module using the command 'modprobe uio' if the user wants
 389   to use UIO framework.
 390 - DPDK suite should be configured based on the user's decision to use VFIO or
 391   UIO framework.
 392 - If the vNIC device(s) to be used is bound to the kernel mode Ethernet driver
 393   use 'ip' to bring the interface down. The dpdk-devbind.py tool can
 394   then be used to unbind the device's bus id from the ENIC kernel mode driver.
 395 - Bind the intended vNIC to vfio-pci in case the user wants ENIC PMD to use
 396   VFIO framework using dpdk-devbind.py.
 397 - Bind the intended vNIC to igb_uio in case the user wants ENIC PMD to use
 398   UIO framework using dpdk-devbind.py.
 399
 400 At this point the system should be ready to run DPDK applications. Once the
 401 application runs to completion, the vNIC can be detached from vfio-pci or
 402 igb_uio if necessary.
 403
 404 Root privilege is required to bind and unbind vNICs to/from VFIO/UIO.
 405 VFIO framework helps an unprivileged user to run the applications.
 406 For an unprivileged user to run the applications on DPDK and ENIC PMD,
 407 it may be necessary to increase the maximum locked memory of the user.
 408 The following command could be used to do this.
 409
 410 .. code-block:: console
 411
 412     sudo sh -c "ulimit -l <value in Kilo Bytes>"
 413
 414 The value depends on the memory configuration of the application, DPDK and
 415 PMD.  Typically, the limit has to be raised to higher than 2GB.
 416 e.g., 2621440
 417
 418 The compilation of any unused drivers can be disabled using the
 419 configuration file in config/ directory (e.g., config/common_linuxapp).
 420 This would help in bringing down the time taken for building the
 421 libraries and the initialization time of the application.
 422
 423 Additional Reference
 424 --------------------
 425
 426 - https://www.cisco.com/c/en/us/products/servers-unified-computing/index.html
 427 - https://www.cisco.com/c/en/us/products/interfaces-modules/unified-computing-system-adapters/index.html
 428
 429 Contact Information
 430 -------------------
 431
 432 Any questions or bugs should be reported to DPDK community and to the ENIC PMD
 433 maintainers:
 434
 435 - John Daley <johndale@cisco.com>
 436 - Nelson Escobar <neescoba@cisco.com>