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 - ``Maximum Number of Queue Pairs``
  53
  54   The maximum number of queue pairs is decided by HW. If not configured, APP
  55   uses the number from HW. Users can check the number by calling the API
  56   ``rte_eth_dev_info_get``.
  57   If users want to limit the number of queues, they can set a smaller number
  58   using EAL parameter like ``max_queue_pair_num=n``.
  59
  60
  61 Driver compilation and testing
  62 ------------------------------
  63
  64 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
  65 for details.
  66
  67 Features
  68 --------
  69
  70 Vector PMD
  71 ~~~~~~~~~~
  72
  73 Vector PMD for RX and TX path are selected automatically. The paths
  74 are chosen based on 2 conditions.
  75
  76 - ``CPU``
  77   On the X86 platform, the driver checks if the CPU supports AVX2.
  78   If it's supported, AVX2 paths will be chosen. If not, SSE is chosen.
  79
  80 - ``Offload features``
  81   The supported HW offload features are described in the document ice_vec.ini.
  82   If any not supported features are used, ICE vector PMD is disabled and the
  83   normal paths are chosen.
  84
  85 Malicious driver detection (MDD)
  86 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  87
  88 It's not appropriate to send a packet, if this packet's destination MAC address
  89 is just this port's MAC address. If SW tries to send such packets, HW will
  90 report a MDD event and drop the packets.
  91
  92 The APPs based on DPDK should avoid providing such packets.
  93
  94 Sample Application Notes
  95 ------------------------
  96
  97 Vlan filter
  98 ~~~~~~~~~~~
  99
 100 Vlan filter only works when Promiscuous mode is off.
 101
 102 To start ``testpmd``, and add vlan 10 to port 0:
 103
 104 .. code-block:: console
 105
 106     ./app/testpmd -l 0-15 -n 4 -- -i
 107     ...
 108
 109     testpmd> rx_vlan add 10 0
 110
 111 Limitations or Known issues
 112 ---------------------------
 113
 114 The Intel E810 requires a programmable pipeline package be downloaded
 115 by the driver to support normal operations. The E810 has a limited
 116 functionality built in to allow PXE boot and other use cases, but the
 117 driver must download a package file during the driver initialization
 118 stage. The file must be in the /lib/firmware/intel/ice/ddp directory
 119 and it must be named ice.pkg. A symbolic link to this file is also ok.
 120 The same package file is used by both the kernel driver and the DPDK PMD.
 121
 122
 123 19.02 limitation
 124 ~~~~~~~~~~~~~~~~
 125
 126 Ice code released in 19.02 is for evaluation only.