X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fnics%2Fi40e.rst;h=07841dca2424b40ae2039cef20dbf274a57486ee;hb=a6a18d06f5ae900eabba24325f49ee2ef86449c0;hp=5d8500cef63e5b4212d6a636e7961a94afb864b5;hpb=abc6234e8321c2a85680ad246ae7da826fe1418b;p=dpdk.git diff --git a/doc/guides/nics/i40e.rst b/doc/guides/nics/i40e.rst index 5d8500cef6..07841dca24 100644 --- a/doc/guides/nics/i40e.rst +++ b/doc/guides/nics/i40e.rst @@ -4,7 +4,7 @@ I40E Poll Mode Driver ====================== -The i40e PMD (librte_pmd_i40e) provides poll mode driver support for +The i40e PMD (**librte_net_i40e**) provides poll mode driver support for 10/25/40 Gbps Intel® Ethernet 700 Series Network Adapters based on the Intel Ethernet Controller X710/XL710/XXV710 and Intel Ethernet Connection X722 (only support part of features). @@ -43,9 +43,11 @@ Features of the i40e PMD are: - Dynamic Device Personalization (DDP) - Queue region configuration - Virtual Function Port Representors +- Malicious Device Drive event catch and notify +- Generic flow API -Prerequisites -------------- +Linux Prerequisites +------------------- - Identifying your adapter using `Intel Support `_ and get the latest NVM/FW images. @@ -58,6 +60,33 @@ Prerequisites - Upgrade the NVM/FW version following the `Intel® Ethernet NVM Update Tool Quick Usage Guide for Linux `_ and `Intel® Ethernet NVM Update Tool: Quick Usage Guide for EFI `_ if needed. +- For information about supported media, please refer to this document: `Intel® Ethernet Controller X710/XXV710/XL710 Feature Support Matrix + `_. + + .. Note:: + + * Some adapters based on the Intel(R) Ethernet Controller 700 Series only + support Intel Ethernet Optics modules. On these adapters, other modules are not + supported and will not function. + + * For connections based on Intel(R) Ethernet Controller 700 Series, + support is dependent on your system board. Please see your vendor for details. + + * In all cases Intel recommends using Intel Ethernet Optics; other modules + may function but are not validated by Intel. Contact Intel for supported media types. + +Windows Prerequisites +--------------------- + +- Follow the DPDK `Getting Started Guide for Windows `_ to setup the basic DPDK environment. + +- Identify the Intel® Ethernet adapter and get the latest NVM/FW version. + +- To access any Intel® Ethernet hardware, load the NetUIO driver in place of existing built-in (inbox) driver. + +- To load NetUIO driver, follow the steps mentioned in `dpdk-kmods repository + `_. + Recommended Matching List ------------------------- @@ -66,9 +95,33 @@ avoid the compatibility issues with i40e PMD. Here is the suggested matching list which has been tested and verified. The detailed information can refer to chapter Tested Platforms/Tested NICs in release notes. +For X710/XL710/XXV710, + +--------------+-----------------------+------------------+ | DPDK version | Kernel driver version | Firmware version | +==============+=======================+==================+ + | 21.02 | 2.14.13 | 8.00 | + +--------------+-----------------------+------------------+ + | 20.11 | 2.14.13 | 8.00 | + +--------------+-----------------------+------------------+ + | 20.08 | 2.12.6 | 7.30 | + +--------------+-----------------------+------------------+ + | 20.05 | 2.11.27 | 7.30 | + +--------------+-----------------------+------------------+ + | 20.02 | 2.10.19 | 7.20 | + +--------------+-----------------------+------------------+ + | 19.11 | 2.9.21 | 7.00 | + +--------------+-----------------------+------------------+ + | 19.08 | 2.8.43 | 7.00 | + +--------------+-----------------------+------------------+ + | 19.05 | 2.7.29 | 6.80 | + +--------------+-----------------------+------------------+ + | 19.02 | 2.7.26 | 6.80 | + +--------------+-----------------------+------------------+ + | 18.11 | 2.4.6 | 6.01 | + +--------------+-----------------------+------------------+ + | 18.08 | 2.4.6 | 6.01 | + +--------------+-----------------------+------------------+ | 18.05 | 2.4.6 | 6.01 | +--------------+-----------------------+------------------+ | 18.02 | 2.4.3 | 6.01 | @@ -88,54 +141,63 @@ to chapter Tested Platforms/Tested NICs in release notes. | 16.04 | 1.4.25 | 5.02 | +--------------+-----------------------+------------------+ -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_I40E_PMD`` (default ``y``) +For X722, - Toggle compilation of the ``librte_pmd_i40e`` driver. - -- ``CONFIG_RTE_LIBRTE_I40E_DEBUG_*`` (default ``n``) - - Toggle display of generic debugging messages. - -- ``CONFIG_RTE_LIBRTE_I40E_RX_ALLOW_BULK_ALLOC`` (default ``y``) - - Toggle bulk allocation for RX. + +--------------+-----------------------+------------------+ + | DPDK version | Kernel driver version | Firmware version | + +==============+=======================+==================+ + | 21.02 | 2.14.13 | 5.00 | + +--------------+-----------------------+------------------+ + | 20.11 | 2.13.10 | 5.00 | + +--------------+-----------------------+------------------+ + | 20.08 | 2.12.6 | 4.11 | + +--------------+-----------------------+------------------+ + | 20.05 | 2.11.27 | 4.11 | + +--------------+-----------------------+------------------+ + | 20.02 | 2.10.19 | 4.11 | + +--------------+-----------------------+------------------+ + | 19.11 | 2.9.21 | 4.10 | + +--------------+-----------------------+------------------+ + | 19.08 | 2.9.21 | 4.10 | + +--------------+-----------------------+------------------+ + | 19.05 | 2.7.29 | 3.33 | + +--------------+-----------------------+------------------+ + | 19.02 | 2.7.26 | 3.33 | + +--------------+-----------------------+------------------+ + | 18.11 | 2.4.6 | 3.33 | + +--------------+-----------------------+------------------+ -- ``CONFIG_RTE_LIBRTE_I40E_INC_VECTOR`` (default ``n``) - Toggle the use of Vector PMD instead of normal RX/TX path. - To enable vPMD for RX, bulk allocation for Rx must be allowed. +Pre-Installation Configuration +------------------------------ -- ``CONFIG_RTE_LIBRTE_I40E_16BYTE_RX_DESC`` (default ``n``) +Config File Options +~~~~~~~~~~~~~~~~~~~ - Toggle to use a 16-byte RX descriptor, by default the RX descriptor is 32 byte. +The following options can be modified in the ``config/rte_config.h`` file. -- ``CONFIG_RTE_LIBRTE_I40E_QUEUE_NUM_PER_PF`` (default ``64``) +- ``RTE_LIBRTE_I40E_QUEUE_NUM_PER_PF`` (default ``64``) Number of queues reserved for PF. -- ``CONFIG_RTE_LIBRTE_I40E_QUEUE_NUM_PER_VM`` (default ``4``) +- ``RTE_LIBRTE_I40E_QUEUE_NUM_PER_VM`` (default ``4``) Number of queues reserved for each VMDQ Pool. Runtime Config Options ~~~~~~~~~~~~~~~~~~~~~~ -- ``Number of Queues per VF`` (default ``4``) +- ``Reserved number of Queues per VF`` (default ``4``) + + The number of reserved queue per VF is determined by its host PF. If the + PCI address of an i40e PF is aaaa:bb.cc, the number of reserved queues per + VF can be configured with EAL parameter like -a aaaa:bb.cc,queue-num-per-vf=n. + The value n can be 1, 2, 4, 8 or 16. If no such parameter is configured, the + number of reserved queues per VF is 4 by default. If VF request more than + reserved queues per VF, PF will able to allocate max to 16 queues after a VF + reset. - The number of queue per VF is determined by its host PF. If the PCI address - of an i40e PF is aaaa:bb.cc, the number of queues per VF can be configured - with EAL parameter like -w aaaa:bb.cc,queue-num-per-vf=n. The value n can be - 1, 2, 4, 8 or 16. If no such parameter is configured, the number of queues - per VF is 4 by default. - ``Support multiple driver`` (default ``disable``) @@ -143,7 +205,7 @@ Runtime Config Options Adapter with both Linux kernel and DPDK PMD. To fix this issue, ``devargs`` parameter ``support-multi-driver`` is introduced, for example:: - -w 84:00.0,support-multi-driver=1 + -a 84:00.0,support-multi-driver=1 With the above configuration, DPDK PMD will not change global registers, and will switch PF interrupt from IntN to Int0 to avoid interrupt conflict between @@ -158,11 +220,28 @@ Runtime Config Options port representors for on initialization of the PF PMD by passing the VF IDs of the VFs which are required.:: - -w DBDF,representor=[0,1,4] + -a DBDF,representor=[0,1,4] Currently hot-plugging of representor ports is not supported so all required representors must be specified on the creation of the PF. +- ``Enable validation for VF message`` (default ``not enabled``) + + The PF counts messages from each VF. If in any period of seconds the message + statistic from a VF exceeds maximal limitation, the PF will ignore any new message + from that VF for some seconds. + Format -- "maximal-message@period-seconds:ignore-seconds" + For example:: + + -a 84:00.0,vf_msg_cfg=80@120:180 + +Vector RX Pre-conditions +~~~~~~~~~~~~~~~~~~~~~~~~ +For Vector RX it is assumed that the number of descriptor rings will be a power +of 2. With this pre-condition, the ring pointer can easily scroll back to the +head after hitting the tail without a conditional check. In addition Vector RX +can use this assumption to do a bit mask using ``ring_size - 1``. + Driver compilation and testing ------------------------------ @@ -264,7 +343,7 @@ To start ``testpmd``, and add vlan 10 to port 0: .. code-block:: console - ./app/testpmd -l 0-15 -n 4 -- -i --forward-mode=mac + .//app/dpdk-testpmd -l 0-15 -n 4 -- -i --forward-mode=mac ... testpmd> set promisc 0 off @@ -299,16 +378,17 @@ Start ``testpmd`` with ``--disable-rss`` and ``--pkt-filter-mode=perfect``: .. code-block:: console - ./app/testpmd -l 0-15 -n 4 -- -i --disable-rss --pkt-filter-mode=perfect \ - --rxq=8 --txq=8 --nb-cores=8 --nb-ports=1 + .//app/dpdk-testpmd -l 0-15 -n 4 -- -i --disable-rss \ + --pkt-filter-mode=perfect --rxq=8 --txq=8 --nb-cores=8 \ + --nb-ports=1 Add a rule to direct ``ipv4-udp`` packet whose ``dst_ip=2.2.2.5, src_ip=2.2.2.3, src_port=32, dst_port=32`` to queue 1: .. code-block:: console - testpmd> flow_director_filter 0 mode IP add flow ipv4-udp \ - src 2.2.2.3 32 dst 2.2.2.5 32 vlan 0 flexbytes () \ - fwd pf queue 1 fd_id 1 + testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.3 \ + dst is 2.2.2.5 / udp src is 32 dst is 32 / end \ + actions mark id 1 / queue index 1 / end Check the flow director status: @@ -357,12 +437,6 @@ Check the flow director status: f_add: 0 f_remove: 0 -Delete all flow director rules on a port: - -.. code-block:: console - - testpmd> flush_flow_director 0 - Floating VEB ~~~~~~~~~~~~~ @@ -389,7 +463,7 @@ no physical uplink on the associated NIC port. To enable this feature, the user should pass a ``devargs`` parameter to the EAL, for example:: - -w 84:00.0,enable_floating_veb=1 + -a 84:00.0,enable_floating_veb=1 In this configuration the PMD will use the floating VEB feature for all the VFs created by this PF device. @@ -397,7 +471,7 @@ VFs created by this PF device. Alternatively, the user can specify which VFs need to connect to this floating VEB using the ``floating_veb_list`` argument:: - -w 84:00.0,enable_floating_veb=1,floating_veb_list=1;3-4 + -a 84:00.0,enable_floating_veb=1,floating_veb_list=1;3-4 In this example ``VF1``, ``VF3`` and ``VF4`` connect to the floating VEB, while other VFs connect to the normal VEB. @@ -418,12 +492,18 @@ which is used to configure hardware by downloading a profile to support protocols/filters which are not supported by default. The DDP functionality requires a NIC firmware version of 6.0 or greater. -Current implementation supports GTP-C/GTP-U/PPPoE/PPPoL2TP, +Current implementation supports GTP-C/GTP-U/PPPoE/PPPoL2TP/ESP, steering can be used with rte_flow API. GTPv1 package is released, and it can be downloaded from https://downloadcenter.intel.com/download/27587. +PPPoE package is released, and it can be downloaded from +https://downloadcenter.intel.com/download/28040. + +ESP-AH package is released, and it can be downloaded from +https://downloadcenter.intel.com/download/29446. + Load a profile which supports GTP and store backup profile: .. code-block:: console @@ -483,6 +563,42 @@ details please refer to :doc:`../testpmd_app_ug/index`. testpmd> set port (port_id) queue-region flush (on|off) testpmd> show port (port_id) queue-region +Generic flow API +~~~~~~~~~~~~~~~~~~~ + +- ``RSS Flow`` + + RSS Flow supports to set hash input set, hash function, enable hash + and configure queues. + For example: + Configure queues as queue 0, 1, 2, 3. + + .. code-block:: console + + testpmd> flow create 0 ingress pattern end actions rss types end \ + queues 0 1 2 3 end / end + + Enable hash and set input set for ipv4-tcp. + + .. code-block:: console + + testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \ + actions rss types ipv4-tcp l3-src-only end queues end / end + + Set symmetric hash enable for flow type ipv4-tcp. + + .. code-block:: console + + testpmd> flow create 0 ingress pattern eth / ipv4 / tcp / end \ + actions rss types ipv4-tcp end queues end func symmetric_toeplitz / end + + Set hash function as simple xor. + + .. code-block:: console + + testpmd> flow create 0 ingress pattern end actions rss types end \ + queues end func simple_xor / end + Limitations or Known issues --------------------------- @@ -503,8 +619,8 @@ L2 Payload flow type in flow director cannot be used to classify MPLS packet as with previous firmware versions. Meanwhile, the Ethertype filter can be used to classify MPLS packet by using a command in testpmd like: - testpmd> ethertype_filter 0 add mac_ignr 00:00:00:00:00:00 ethertype \ - 0x8847 fwd queue + testpmd> flow create 0 ingress pattern eth type is 0x8847 / end \ + actions queue index / end 16 Byte RX Descriptor setting on DPDK VF ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -516,8 +632,7 @@ For all available versions of the i40e driver, these drivers don't support 16 byte RX descriptor. If the Linux i40e kernel driver is used as host driver, while DPDK i40e PMD is used as the VF driver, DPDK cannot choose 16 byte receive descriptor. The reason is that the RX descriptor is already set to 32 byte by -the i40e kernel driver. That is to say, user should keep -``CONFIG_RTE_LIBRTE_I40E_16BYTE_RX_DESC=n`` in config file. +the i40e kernel driver. In the future, if the Linux i40e driver supports 16 byte RX descriptor, user should make sure the DPDK VF uses the same RX descriptor mode, 16 byte or 32 byte, as the PF driver. @@ -538,6 +653,15 @@ When a packet is over maximum frame size, the packet is dropped. However, the Rx statistics, when calling `rte_eth_stats_get` incorrectly shows it as received. +RX/TX statistics may be incorrect when register overflowed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The rx_bytes/tx_bytes statistics register is 48 bit length. +Although this limitation is enlarged to 64 bit length on the software side, +but there is no way to detect if the overflow occurred more than once. +So rx_bytes/tx_bytes statistics data is correct when statistics are +updated at least once between two overflows. + VF & TC max bandwidth setting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -552,7 +676,7 @@ bandwidth setting. TC TX scheduling mode setting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There're 2 TX scheduling modes for TCs, round robin and strict priority mode. +There are 2 TX scheduling modes for TCs, round robin and strict priority mode. If a TC is set to strict priority mode, it can consume unlimited bandwidth. It means if APP has set the max bandwidth for that TC, it comes to no effect. @@ -608,6 +732,18 @@ with DPDK, then the configuration will also impact port B in the NIC with kernel driver, which don't want to use the TPID. So PMD reports warning to clarify what is changed by writing global register. +Cloud Filter +~~~~~~~~~~~~ + +When programming cloud filters for IPv4/6_UDP/TCP/SCTP with SRC port only or DST port only, +it will make any cloud filter using inner_vlan or tunnel key invalid. Default configuration will be +recovered only by NIC core reset. + +Mirror rule limitation for X722 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Due to firmware restriction of X722, the same VSI cannot have more than one mirror rule. + High Performance of Small Packets on 40GbE NIC ---------------------------------------------- @@ -621,7 +757,18 @@ Use 16 Bytes RX Descriptor Size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As i40e PMD supports both 16 and 32 bytes RX descriptor sizes, and 16 bytes size can provide helps to high performance of small packets. -Configuration of ``CONFIG_RTE_LIBRTE_I40E_16BYTE_RX_DESC`` in config files can be changed to use 16 bytes size RX descriptors. +In ``config/rte_config.h`` set the following to use 16 bytes size RX descriptors:: + + #define RTE_LIBRTE_I40E_16BYTE_RX_DESC 1 + +Input set requirement of each pctype for FDIR +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each PCTYPE can only have one specific FDIR input set at one time. +For example, if creating 2 rte_flow rules with different input set for one PCTYPE, +it will fail and return the info "Conflict with the first rule's input set", +which means the current rule's input set conflicts with the first rule's. +Remove the first rule if want to change the input set of the PCTYPE. Example of getting best performance with l3fwd example ------------------------------------------------------ @@ -665,7 +812,7 @@ See :numref:`figure_intel_perf_test_setup` for the performance test setup. 7. The command line of running l3fwd would be something like the following:: - ./l3fwd -l 18-21 -n 4 -w 82:00.0 -w 85:00.0 \ + ./dpdk-l3fwd -l 18-21 -n 4 -a 82:00.0 -a 85:00.0 \ -- -p 0x3 --config '(0,0,18),(0,1,19),(1,0,20),(1,1,21)' This means that the application uses core 18 for port 0, queue pair 0 forwarding, core 19 for port 0, queue pair 1 forwarding, @@ -676,3 +823,9 @@ See :numref:`figure_intel_perf_test_setup` for the performance test setup. * Start creating a stream on packet generator. * Set the Ethernet II type to 0x0800. + +Tx bytes affected by the link status change +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For firmware versions prior to 6.01 for X710 series and 3.33 for X722 series, the tx_bytes statistics data is affected by +the link down event. Each time the link status changes to down, the tx_bytes decreases 110 bytes.