doc/guides/nics/ice.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 ICE Poll Mode Driver
   5 ======================
   6
   7 The ice PMD (librte_pmd_ice) provides poll mode driver support for
   8 10/25 Gbps Intel® Ethernet 810 Series Network Adapters based on
   9 the Intel Ethernet Controller E810.
  10
  11
  12 Prerequisites
  13 -------------
  14
  15 - Identifying your adapter using `Intel Support
  16   <http://www.intel.com/support>`_ and get the latest NVM/FW images.
  17
  18 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
  19
  20 - To get better performance on Intel platforms, please follow the "How to get best performance with NICs on Intel platforms"
  21   section of the :ref:`Getting Started Guide for Linux <linux_gsg>`.
  22
  23
  24 Pre-Installation Configuration
  25 ------------------------------
  26
  27 Config File Options
  28 ~~~~~~~~~~~~~~~~~~~
  29
  30 The following options can be modified in the ``config`` file.
  31 Please note that enabling debugging options may affect system performance.
  32
  33 - ``CONFIG_RTE_LIBRTE_ICE_PMD`` (default ``y``)
  34
  35   Toggle compilation of the ``librte_pmd_ice`` driver.
  36
  37 - ``CONFIG_RTE_LIBRTE_ICE_DEBUG_*`` (default ``n``)
  38
  39   Toggle display of generic debugging messages.
  40
  41 - ``CONFIG_RTE_LIBRTE_ICE_RX_ALLOW_BULK_ALLOC`` (default ``y``)
  42
  43   Toggle bulk allocation for RX.
  44
  45 - ``CONFIG_RTE_LIBRTE_ICE_16BYTE_RX_DESC`` (default ``n``)
  46
  47   Toggle to use a 16-byte RX descriptor, by default the RX descriptor is 32 byte.
  48
  49 Runtime Config Options
  50 ~~~~~~~~~~~~~~~~~~~~~~
  51
  52 - ``Safe Mode Support`` (default ``0``)
  53
  54   If driver failed to load OS package, by default driver's initialization failed.
  55   But if user intend to use the device without OS package, user can take ``devargs``
  56   parameter ``safe-mode-support``, for example::
  57
  58     -w 80:00.0,safe-mode-support=1
  59
  60   Then the driver will be initialized successfully and the device will enter Safe Mode.
  61   NOTE: In Safe mode, only very limited features are available, features like RSS,
  62   checksum, fdir, tunneling ... are all disabled.
  63
  64 Driver compilation and testing
  65 ------------------------------
  66
  67 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
  68 for details.
  69
  70 Features
  71 --------
  72
  73 Vector PMD
  74 ~~~~~~~~~~
  75
  76 Vector PMD for RX and TX path are selected automatically. The paths
  77 are chosen based on 2 conditions.
  78
  79 - ``CPU``
  80   On the X86 platform, the driver checks if the CPU supports AVX2.
  81   If it's supported, AVX2 paths will be chosen. If not, SSE is chosen.
  82
  83 - ``Offload features``
  84   The supported HW offload features are described in the document ice_vec.ini.
  85   If any not supported features are used, ICE vector PMD is disabled and the
  86   normal paths are chosen.
  87
  88 Malicious driver detection (MDD)
  89 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  90
  91 It's not appropriate to send a packet, if this packet's destination MAC address
  92 is just this port's MAC address. If SW tries to send such packets, HW will
  93 report a MDD event and drop the packets.
  94
  95 The APPs based on DPDK should avoid providing such packets.
  96
  97 Sample Application Notes
  98 ------------------------
  99
 100 Vlan filter
 101 ~~~~~~~~~~~
 102
 103 Vlan filter only works when Promiscuous mode is off.
 104
 105 To start ``testpmd``, and add vlan 10 to port 0:
 106
 107 .. code-block:: console
 108
 109     ./app/testpmd -l 0-15 -n 4 -- -i
 110     ...
 111
 112     testpmd> rx_vlan add 10 0
 113
 114 Limitations or Known issues
 115 ---------------------------
 116
 117 The Intel E810 requires a programmable pipeline package be downloaded
 118 by the driver to support normal operations. The E810 has a limited
 119 functionality built in to allow PXE boot and other use cases, but the
 120 driver must download a package file during the driver initialization
 121 stage. The file must be in the /lib/firmware/intel/ice/ddp directory
 122 and it must be named ice.pkg. A symbolic link to this file is also ok.
 123 The same package file is used by both the kernel driver and the DPDK PMD.
 124
 125
 126 19.02 limitation
 127 ~~~~~~~~~~~~~~~~
 128
 129 Ice code released in 19.02 is for evaluation only.