.. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2018 Intel Corporation. ICE Poll Mode Driver ====================== The ice PMD (librte_pmd_ice) provides poll mode driver support for 10/25 Gbps Intel® Ethernet 810 Series Network Adapters based on the Intel Ethernet Controller E810. Prerequisites ------------- - Identifying your adapter using `Intel Support `_ and get the latest NVM/FW images. - Follow the DPDK :ref:`Getting Started Guide for Linux ` to setup the basic DPDK environment. - To get better performance on Intel platforms, please follow the "How to get best performance with NICs on Intel platforms" section of the :ref:`Getting Started Guide for Linux `. Pre-Installation Configuration ------------------------------ Config File Options ~~~~~~~~~~~~~~~~~~~ The following options can be modified in the ``config`` file. Please note that enabling debugging options may affect system performance. - ``CONFIG_RTE_LIBRTE_ICE_PMD`` (default ``y``) Toggle compilation of the ``librte_pmd_ice`` driver. - ``CONFIG_RTE_LIBRTE_ICE_DEBUG_*`` (default ``n``) Toggle display of generic debugging messages. - ``CONFIG_RTE_LIBRTE_ICE_RX_ALLOW_BULK_ALLOC`` (default ``y``) Toggle bulk allocation for RX. - ``CONFIG_RTE_LIBRTE_ICE_16BYTE_RX_DESC`` (default ``n``) Toggle to use a 16-byte RX descriptor, by default the RX descriptor is 32 byte. Runtime Config Options ~~~~~~~~~~~~~~~~~~~~~~ - ``Safe Mode Support`` (default ``0``) If driver failed to load OS package, by default driver's initialization failed. But if user intend to use the device without OS package, user can take ``devargs`` parameter ``safe-mode-support``, for example:: -w 80:00.0,safe-mode-support=1 Then the driver will be initialized successfully and the device will enter Safe Mode. NOTE: In Safe mode, only very limited features are available, features like RSS, checksum, fdir, tunneling ... are all disabled. - ``Protocol extraction for per queue`` Configure the RX queues to do protocol extraction into ``rte_mbuf::udata64`` for protocol handling acceleration, like checking the TCP SYN packets quickly. The argument format is:: -w 18:00.0,proto_xtr=[...] -w 18:00.0,proto_xtr= Queues are grouped by ``(`` and ``)`` within the group. The ``-`` character is used as a range separator and ``,`` is used as a single number separator. The grouping ``()`` can be omitted for single element group. If no queues are specified, PMD will use this protocol extraction type for all queues. Protocol is : ``vlan, ipv4, ipv6, ipv6_flow, tcp``. .. code-block:: console testpmd -w 18:00.0,proto_xtr='[(1,2-3,8-9):tcp,10-13:vlan]' This setting means queues 1, 2-3, 8-9 are TCP extraction, queues 10-13 are VLAN extraction, other queues run with no protocol extraction. .. code-block:: console testpmd -w 18:00.0,proto_xtr=vlan,proto_xtr='[(1,2-3,8-9):tcp,10-23:ipv6]' This setting means queues 1, 2-3, 8-9 are TCP extraction, queues 10-23 are IPv6 extraction, other queues use the default VLAN extraction. The extraction will be copied into the lower 32 bit of ``rte_mbuf::udata64``. .. table:: Protocol extraction : ``vlan`` +----------------------------+----------------------------+ | VLAN2 | VLAN1 | +======+===+=================+======+===+=================+ | PCP | D | VID | PCP | D | VID | +------+---+-----------------+------+---+-----------------+ VLAN1 - single or EVLAN (first for QinQ). VLAN2 - C-VLAN (second for QinQ). .. table:: Protocol extraction : ``ipv4`` +----------------------------+----------------------------+ | IPHDR2 | IPHDR1 | +======+=======+=============+==============+=============+ | Ver |Hdr Len| ToS | TTL | Protocol | +------+-------+-------------+--------------+-------------+ IPHDR1 - IPv4 header word 4, "TTL" and "Protocol" fields. IPHDR2 - IPv4 header word 0, "Ver", "Hdr Len" and "Type of Service" fields. .. table:: Protocol extraction : ``ipv6`` +----------------------------+----------------------------+ | IPHDR2 | IPHDR1 | +=====+=============+========+=============+==============+ | Ver |Traffic class| Flow | Next Header | Hop Limit | +-----+-------------+--------+-------------+--------------+ IPHDR1 - IPv6 header word 3, "Next Header" and "Hop Limit" fields. IPHDR2 - IPv6 header word 0, "Ver", "Traffic class" and high 4 bits of "Flow Label" fields. .. table:: Protocol extraction : ``ipv6_flow`` +----------------------------+----------------------------+ | IPHDR2 | IPHDR1 | +=====+=============+========+============================+ | Ver |Traffic class| Flow Label | +-----+-------------+-------------------------------------+ IPHDR1 - IPv6 header word 1, 16 low bits of the "Flow Label" field. IPHDR2 - IPv6 header word 0, "Ver", "Traffic class" and high 4 bits of "Flow Label" fields. .. table:: Protocol extraction : ``tcp`` +----------------------------+----------------------------+ | TCPHDR2 | TCPHDR1 | +============================+======+======+==============+ | Reserved |Offset| RSV | Flags | +----------------------------+------+------+--------------+ TCPHDR1 - TCP header word 6, "Data Offset" and "Flags" fields. TCPHDR2 - Reserved Use ``get_proto_xtr_flds(struct rte_mbuf *mb)`` to access the protocol extraction, do not use ``rte_mbuf::udata64`` directly. The ``dump_proto_xtr_flds(struct rte_mbuf *mb)`` routine shows how to access the protocol extraction result in ``struct rte_mbuf``. Driver compilation and testing ------------------------------ Refer to the document :ref:`compiling and testing a PMD for a NIC ` for details. Features -------- Vector PMD ~~~~~~~~~~ Vector PMD for RX and TX path are selected automatically. The paths are chosen based on 2 conditions. - ``CPU`` On the X86 platform, the driver checks if the CPU supports AVX2. If it's supported, AVX2 paths will be chosen. If not, SSE is chosen. - ``Offload features`` The supported HW offload features are described in the document ice_vec.ini. If any not supported features are used, ICE vector PMD is disabled and the normal paths are chosen. Malicious driver detection (MDD) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It's not appropriate to send a packet, if this packet's destination MAC address is just this port's MAC address. If SW tries to send such packets, HW will report a MDD event and drop the packets. The APPs based on DPDK should avoid providing such packets. Sample Application Notes ------------------------ Vlan filter ~~~~~~~~~~~ Vlan filter only works when Promiscuous mode is off. To start ``testpmd``, and add vlan 10 to port 0: .. code-block:: console ./app/testpmd -l 0-15 -n 4 -- -i ... testpmd> rx_vlan add 10 0 Limitations or Known issues --------------------------- The Intel E810 requires a programmable pipeline package be downloaded by the driver to support normal operations. The E810 has a limited functionality built in to allow PXE boot and other use cases, but the driver must download a package file during the driver initialization stage. The default DDP package file name is ice.pkg. For a specific NIC, the DDP package supposed to be loaded can have a filename: ice-xxxxxx.pkg, where 'xxxxxx' is the 64-bit PCIe Device Serial Number of the NIC. For example, if the NIC's device serial number is 00-CC-BB-FF-FF-AA-05-68, the device-specific DDP package filename is ice-00ccbbffffaa0568.pkg (in hex and all low case). During initialization, the driver searches in the following paths in order: /lib/firmware/updates/intel/ice/ddp and /lib/firmware/intel/ice/ddp. The corresponding device-specific DDP package will be downloaded first if the file exists. If not, then the driver tries to load the default package. The type of loaded package is stored in ``ice_adapter->active_pkg_type``. A symbolic link to the DDP package file is also ok. The same package file is used by both the kernel driver and the DPDK PMD. 19.02 limitation ~~~~~~~~~~~~~~~~ Ice code released in 19.02 is for evaluation only.