ceph/src/dpdk/doc/guides/rel_notes/known_issues.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   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     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31
  32 Known Issues and Limitations in Legacy Releases
  33 ===============================================
  34
  35 This section describes known issues with the DPDK software that aren't covered in the version specific release
  36 notes sections.
  37
  38
  39 Unit Test for Link Bonding may fail at test_tlb_tx_burst()
  40 ----------------------------------------------------------
  41
  42 **Description**:
  43    Unit tests will fail in ``test_tlb_tx_burst()`` function with error for uneven distribution of packets.
  44
  45 **Implication**:
  46    Unit test link_bonding_autotest will fail.
  47
  48 **Resolution/Workaround**:
  49    There is no workaround available.
  50
  51 **Affected Environment/Platform**:
  52    Fedora 20.
  53
  54 **Driver/Module**:
  55    Link Bonding.
  56
  57
  58 Pause Frame Forwarding does not work properly on igb
  59 ----------------------------------------------------
  60
  61 **Description**:
  62    For igb devices rte_eth_flow_ctrl_set does not work as expected.
  63    Pause frames are always forwarded on igb, regardless of the ``RFCE``, ``MPMCF`` and ``DPF`` registers.
  64
  65 **Implication**:
  66    Pause frames will never be rejected by the host on 1G NICs and they will always be forwarded.
  67
  68 **Resolution/Workaround**:
  69    There is no workaround available.
  70
  71 **Affected Environment/Platform**:
  72    All.
  73
  74 **Driver/Module**:
  75    Poll Mode Driver (PMD).
  76
  77
  78 In packets provided by the PMD, some flags are missing
  79 ------------------------------------------------------
  80
  81 **Description**:
  82    In packets provided by the PMD, some flags are missing.
  83    The application does not have access to information provided by the hardware
  84    (packet is broadcast, packet is multicast, packet is IPv4 and so on).
  85
  86 **Implication**:
  87    The ``ol_flags`` field in the ``rte_mbuf`` structure is not correct and should not be used.
  88
  89 **Resolution/Workaround**:
  90    The application has to parse the Ethernet header itself to get the information, which is slower.
  91
  92 **Affected Environment/Platform**:
  93    All.
  94
  95 **Driver/Module**:
  96    Poll Mode Driver (PMD).
  97
  98 The rte_malloc library is not fully implemented
  99 -----------------------------------------------
 100
 101 **Description**:
 102    The ``rte_malloc`` library is not fully implemented.
 103
 104 **Implication**:
 105    All debugging features of rte_malloc library described in architecture documentation are not yet implemented.
 106
 107 **Resolution/Workaround**:
 108    No workaround available.
 109
 110 **Affected Environment/Platform**:
 111    All.
 112
 113 **Driver/Module**:
 114    ``rte_malloc``.
 115
 116
 117 HPET reading is slow
 118 --------------------
 119
 120 **Description**:
 121    Reading the HPET chip is slow.
 122
 123 **Implication**:
 124    An application that calls ``rte_get_hpet_cycles()`` or ``rte_timer_manage()`` runs slower.
 125
 126 **Resolution/Workaround**:
 127    The application should not call these functions too often in the main loop.
 128    An alternative is to use the TSC register through ``rte_rdtsc()`` which is faster,
 129    but specific to an lcore and is a cycle reference, not a time reference.
 130
 131 **Affected Environment/Platform**:
 132    All.
 133
 134 **Driver/Module**:
 135    Environment Abstraction Layer (EAL).
 136
 137
 138 HPET timers do not work on the Osage customer reference platform
 139 ----------------------------------------------------------------
 140
 141 **Description**:
 142    HPET timers do not work on the Osage customer reference platform which includes an Intel® Xeon® processor 5500
 143    series processor) using the released BIOS from Intel.
 144
 145 **Implication**:
 146    On Osage boards, the implementation of the ``rte_delay_us()`` function must be changed to not use the HPET timer.
 147
 148 **Resolution/Workaround**:
 149    This can be addressed by building the system with the ``CONFIG_RTE_LIBEAL_USE_HPET=n``
 150    configuration option or by using the ``--no-hpet`` EAL option.
 151
 152 **Affected Environment/Platform**:
 153    The Osage customer reference platform.
 154    Other vendor platforms with Intel®  Xeon® processor 5500 series processors should
 155    work correctly, provided the BIOS supports HPET.
 156
 157 **Driver/Module**:
 158    ``lib/librte_eal/common/include/rte_cycles.h``
 159
 160
 161 Not all variants of supported NIC types have been used in testing
 162 -----------------------------------------------------------------
 163
 164 **Description**:
 165    The supported network interface cards can come in a number of variants with different device ID's.
 166    Not all of these variants have been tested with the DPDK.
 167
 168    The NIC device identifiers used during testing:
 169
 170    * Intel® Ethernet Controller XL710 for 40GbE QSFP+ [8086:1584]
 171    * Intel® Ethernet Controller XL710 for 40GbE QSFP+ [8086:1583]
 172    * Intel® Ethernet Controller X710 for 10GbE SFP+ [8086:1572]
 173    * Intel® 82576 Gigabit Ethernet Controller [8086:10c9]
 174    * Intel® 82576 Quad Copper Gigabit Ethernet Controller [8086:10e8]
 175    * Intel® 82580 Dual Copper Gigabit Ethernet Controller [8086:150e]
 176    * Intel® I350 Quad Copper Gigabit Ethernet Controller [8086:1521]
 177    * Intel® 82599 Dual Fibre 10 Gigabit Ethernet Controller [8086:10fb]
 178    * Intel® Ethernet Server Adapter X520-T2 [8086: 151c]
 179    * Intel® Ethernet Controller X540-T2 [8086:1528]
 180    * Intel® 82574L Gigabit Network Connection [8086:10d3]
 181    * Emulated Intel® 82540EM Gigabit Ethernet Controller [8086:100e]
 182    * Emulated Intel® 82545EM Gigabit Ethernet Controller [8086:100f]
 183    * Intel® Ethernet Server Adapter X520-4 [8086:154a]
 184    * Intel® Ethernet Controller I210 [8086:1533]
 185
 186 **Implication**:
 187    Risk of issues with untested variants.
 188
 189 **Resolution/Workaround**:
 190    Use tested NIC variants. For those supported Ethernet controllers, additional device
 191    IDs may be added to the software if required.
 192
 193 **Affected Environment/Platform**:
 194    All.
 195
 196 **Driver/Module**:
 197    Poll-mode drivers
 198
 199
 200 Multi-process sample app requires exact memory mapping
 201 ------------------------------------------------------
 202
 203 **Description**:
 204    The multi-process example application assumes that
 205    it is possible to map the hugepage memory to the same virtual addresses in client and server applications.
 206    Occasionally, very rarely with 64-bit, this does not occur and a client application will fail on startup.
 207    The Linux "address-space layout randomization" security feature can sometimes cause this to occur.
 208
 209 **Implication**:
 210    A multi-process client application fails to initialize.
 211
 212 **Resolution/Workaround**:
 213    See the "Multi-process Limitations" section in the DPDK Programmer's Guide for more information.
 214
 215 **Affected Environment/Platform**:
 216    All.
 217
 218 **Driver/Module**:
 219    Multi-process example application
 220
 221
 222 Packets are not sent by the 1 GbE/10 GbE SR-IOV driver when the source MAC is not the MAC assigned to the VF NIC
 223 ----------------------------------------------------------------------------------------------------------------
 224
 225 **Description**:
 226    The 1 GbE/10 GbE SR-IOV driver can only send packets when the Ethernet header's source MAC address is the same as
 227    that of the VF NIC.
 228    The reason for this is that the Linux ``ixgbe`` driver module in the host OS has its anti-spoofing feature enabled.
 229
 230 **Implication**:
 231    Packets sent using the 1 GbE/10 GbE SR-IOV driver must have the source MAC address correctly set to that of the VF NIC.
 232    Packets with other source address values are dropped by the NIC if the application attempts to transmit them.
 233
 234 **Resolution/Workaround**:
 235    Configure the Ethernet source address in each packet to match that of the VF NIC.
 236
 237 **Affected Environment/Platform**:
 238    All.
 239
 240 **Driver/Module**:
 241    1 GbE/10 GbE VF Poll Mode Driver (PMD).
 242
 243
 244 SR-IOV drivers do not fully implement the rte_ethdev API
 245 --------------------------------------------------------
 246
 247 **Description**:
 248    The SR-IOV drivers only supports the following rte_ethdev API functions:
 249
 250    * rte_eth_dev_configure()
 251    * rte_eth_tx_queue_setup()
 252    * rte_eth_rx_queue_setup()
 253    * rte_eth_dev_info_get()
 254    * rte_eth_dev_start()
 255    * rte_eth_tx_burst()
 256    * rte_eth_rx_burst()
 257    * rte_eth_dev_stop()
 258    * rte_eth_stats_get()
 259    * rte_eth_stats_reset()
 260    * rte_eth_link_get()
 261    * rte_eth_link_get_no_wait()
 262
 263 **Implication**:
 264    Calling an unsupported function will result in an application error.
 265
 266 **Resolution/Workaround**:
 267    Do not use other rte_ethdev API functions in applications that use the SR-IOV drivers.
 268
 269 **Affected Environment/Platform**:
 270    All.
 271
 272 **Driver/Module**:
 273    VF Poll Mode Driver (PMD).
 274
 275
 276 PMD does not work with --no-huge EAL command line parameter
 277 -----------------------------------------------------------
 278
 279 **Description**:
 280    Currently, the DPDK does not store any information about memory allocated by ``malloc()` (for example, NUMA node,
 281    physical address), hence PMD drivers do not work when the ``--no-huge`` command line parameter is supplied to EAL.
 282
 283 **Implication**:
 284    Sending and receiving data with PMD will not work.
 285
 286 **Resolution/Workaround**:
 287    Use huge page memory or use VFIO to map devices.
 288
 289 **Affected Environment/Platform**:
 290    Systems running the DPDK on Linux
 291
 292 **Driver/Module**:
 293    Poll Mode Driver (PMD).
 294
 295
 296 Some hardware off-load functions are not supported by the VF Driver
 297 -------------------------------------------------------------------
 298
 299 **Description**:
 300    Currently, configuration of the following items is not supported by the VF driver:
 301
 302    * IP/UDP/TCP checksum offload
 303    * Jumbo Frame Receipt
 304    * HW Strip CRC
 305
 306 **Implication**:
 307    Any configuration for these items in the VF register will be ignored.
 308    The behavior is dependent on the current PF setting.
 309
 310 **Resolution/Workaround**:
 311    For the PF (Physical Function) status on which the VF driver depends, there is an option item under PMD in the
 312    config file.
 313    For others, the VF will keep the same behavior as PF setting.
 314
 315 **Affected Environment/Platform**:
 316    All.
 317
 318 **Driver/Module**:
 319    VF (SR-IOV) Poll Mode Driver (PMD).
 320
 321
 322 Kernel crash on IGB port unbinding
 323 ----------------------------------
 324
 325 **Description**:
 326    Kernel crash may occur when unbinding 1G ports from the igb_uio driver, on 2.6.3x kernels such as shipped
 327    with Fedora 14.
 328
 329 **Implication**:
 330    Kernel crash occurs.
 331
 332 **Resolution/Workaround**:
 333    Use newer kernels or do not unbind ports.
 334
 335 **Affected Environment/Platform**:
 336    2.6.3x kernels such as  shipped with Fedora 14
 337
 338 **Driver/Module**:
 339    IGB Poll Mode Driver (PMD).
 340
 341
 342 Twinpond and Ironpond NICs do not report link status correctly
 343 --------------------------------------------------------------
 344
 345 **Description**:
 346    Twin Pond/Iron Pond NICs do not bring the physical link down when shutting down the port.
 347
 348 **Implication**:
 349    The link is reported as up even after issuing ``shutdown`` command unless the cable is physically disconnected.
 350
 351 **Resolution/Workaround**:
 352    None.
 353
 354 **Affected Environment/Platform**:
 355    Twin Pond and Iron Pond NICs
 356
 357 **Driver/Module**:
 358    Poll Mode Driver (PMD).
 359
 360
 361 Discrepancies between statistics reported by different NICs
 362 -----------------------------------------------------------
 363
 364 **Description**:
 365    Gigabit Ethernet devices from Intel include CRC bytes when calculating packet reception statistics regardless
 366    of hardware CRC stripping state, while 10-Gigabit Ethernet devices from Intel do so only when hardware CRC
 367    stripping is disabled.
 368
 369 **Implication**:
 370    There may be a  discrepancy in how different NICs display packet reception statistics.
 371
 372 **Resolution/Workaround**:
 373    None
 374
 375 **Affected Environment/Platform**:
 376    All.
 377
 378 **Driver/Module**:
 379    Poll Mode Driver (PMD).
 380
 381
 382 Error reported opening files on DPDK initialization
 383 ---------------------------------------------------
 384
 385 **Description**:
 386    On DPDK application startup, errors may be reported when opening files as part of the initialization process.
 387    This occurs if a large number, for example, 500 or more, or if hugepages are used, due to the per-process
 388    limit on the number of open files.
 389
 390 **Implication**:
 391    The DPDK application may fail to run.
 392
 393 **Resolution/Workaround**:
 394    If using 2 MB hugepages, consider switching to a fewer number of 1 GB pages.
 395    Alternatively, use the ``ulimit`` command to increase the number of files which can be opened by a process.
 396
 397 **Affected Environment/Platform**:
 398    All.
 399
 400 **Driver/Module**:
 401    Environment Abstraction Layer (EAL).
 402
 403
 404 Intel® QuickAssist Technology sample application does not work on a 32-bit OS on Shumway
 405 ----------------------------------------------------------------------------------------
 406
 407 **Description**:
 408    The Intel® Communications Chipset 89xx Series device does not fully support NUMA on a 32-bit OS.
 409    Consequently, the sample application cannot work properly on Shumway, since it requires NUMA on both nodes.
 410
 411 **Implication**:
 412    The sample application cannot work in 32-bit mode with emulated NUMA, on multi-socket boards.
 413
 414 **Resolution/Workaround**:
 415    There is no workaround available.
 416
 417 **Affected Environment/Platform**:
 418    Shumway
 419
 420 **Driver/Module**:
 421    All.
 422
 423
 424 Differences in how different Intel NICs handle maximum packet length for jumbo frame
 425 ------------------------------------------------------------------------------------
 426
 427 **Description**:
 428    10 Gigabit Ethernet devices from Intel do not take VLAN tags into account when calculating packet size
 429    while Gigabit Ethernet devices do so for jumbo frames.
 430
 431 **Implication**:
 432    When receiving packets with VLAN tags, the actual maximum size of useful payload that Intel Gigabit Ethernet
 433    devices are able to receive is 4 bytes (or 8 bytes in the case of packets with extended VLAN tags) less than
 434    that of Intel 10 Gigabit Ethernet devices.
 435
 436 **Resolution/Workaround**:
 437    Increase the configured maximum packet size when using Intel Gigabit Ethernet devices.
 438
 439 **Affected Environment/Platform**:
 440    All.
 441
 442 **Driver/Module**:
 443    Poll Mode Driver (PMD).
 444
 445
 446 Binding PCI devices to igb_uio fails on Linux kernel 3.9 when more than one device is used
 447 ------------------------------------------------------------------------------------------
 448
 449 **Description**:
 450    A known bug in the uio driver included in Linux kernel version 3.9 prevents more than one PCI device to be
 451    bound to the igb_uio driver.
 452
 453 **Implication**:
 454    The Poll Mode Driver (PMD) will crash on initialization.
 455
 456 **Resolution/Workaround**:
 457    Use earlier or later kernel versions, or apply the following
 458    `patch  <https://github.com/torvalds/linux/commit/5ed0505c713805f89473cdc0bbfb5110dfd840cb>`_.
 459
 460 **Affected Environment/Platform**:
 461    Linux systems with kernel version 3.9
 462
 463 **Driver/Module**:
 464    igb_uio module
 465
 466
 467 GCC might generate Intel® AVX instructions for processors without Intel® AVX support
 468 ------------------------------------------------------------------------------------
 469
 470 **Description**:
 471    When compiling DPDK (and any DPDK app), gcc may generate Intel® AVX instructions, even when the
 472    processor does not support Intel® AVX.
 473
 474 **Implication**:
 475    Any DPDK app might crash while starting up.
 476
 477 **Resolution/Workaround**:
 478    Either compile using icc or set ``EXTRA_CFLAGS='-O3'`` prior to compilation.
 479
 480 **Affected Environment/Platform**:
 481    Platforms which processor does not support Intel® AVX.
 482
 483 **Driver/Module**:
 484    Environment Abstraction Layer (EAL).
 485
 486 Ethertype filter could receive other packets (non-assigned) in Niantic
 487 ----------------------------------------------------------------------
 488
 489 **Description**:
 490    On Intel®  Ethernet Controller 82599EB When Ethertype filter (priority enable) was set, unmatched packets also
 491    could be received on the assigned queue, such as ARP packets without 802.1q tags or with the user priority not
 492    equal to set value.
 493    Launch the testpmd by disabling RSS and with multiply queues, then add the ethertype filter like the following
 494    and then start forwarding::
 495
 496       add_ethertype_filter 0 ethertype 0x0806 priority enable 3 queue 2 index 1
 497
 498    When sending ARP packets without 802.1q tag and with user priority as non-3 by tester, all the ARP packets can
 499    be received on the assigned queue.
 500
 501 **Implication**:
 502    The user priority comparing in Ethertype filter cannot work probably.
 503    It is a NIC's issue due to the following: "In fact, ETQF.UP is not functional, and the information will
 504    be added in errata of 82599 and X540."
 505
 506 **Resolution/Workaround**:
 507    None
 508
 509 **Affected Environment/Platform**:
 510    All.
 511
 512 **Driver/Module**:
 513    Poll Mode Driver (PMD).
 514
 515
 516 Cannot set link speed on Intel® 40G Ethernet controller
 517 -------------------------------------------------------
 518
 519 **Description**:
 520    On Intel® 40G Ethernet Controller you cannot set the link to specific speed.
 521
 522 **Implication**:
 523    The link speed cannot be changed forcibly, though it can be configured by application.
 524
 525 **Resolution/Workaround**:
 526    None
 527
 528 **Affected Environment/Platform**:
 529    All.
 530
 531 **Driver/Module**:
 532    Poll Mode Driver (PMD).
 533
 534
 535 Devices bound to igb_uio with VT-d enabled do not work on Linux kernel 3.15-3.17
 536 --------------------------------------------------------------------------------
 537
 538 **Description**:
 539    When VT-d is enabled (``iommu=pt intel_iommu=on``), devices are 1:1 mapped.
 540    In the Linux kernel unbinding devices from drivers removes that mapping which result in IOMMU errors.
 541    Introduced in Linux `kernel 3.15 commit
 542    <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/drivers/iommu/intel-iommu.c?id=816997d03bca9fabcee65f3481eb0297103eceb7>`_,
 543    solved in Linux `kernel 3.18 commit
 544    <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/drivers/iommu/intel-iommu.c?id=1196c2fb0407683c2df92d3d09f9144d42830894>`_.
 545
 546 **Implication**:
 547    Devices will not be allowed to access memory, resulting in following kernel errors::
 548
 549       dmar: DRHD: handling fault status reg 2
 550       dmar: DMAR:[DMA Read] Request device [02:00.0] fault addr a0c58000
 551       DMAR:[fault reason 02] Present bit in context entry is clear
 552
 553 **Resolution/Workaround**:
 554    Use earlier or later kernel versions, or avoid driver binding on boot by blacklisting the driver modules.
 555    I.e., in the case of ``ixgbe``, we can pass the kernel command line option: ``modprobe.blacklist=ixgbe``.
 556    This way we do not need to unbind the device to bind it to igb_uio.
 557
 558 **Affected Environment/Platform**:
 559    Linux systems with kernel versions 3.15 to 3.17.
 560
 561 **Driver/Module**:
 562    ``igb_uio`` module.
 563
 564
 565 VM power manager may not work on systems with more than 64 cores
 566 ----------------------------------------------------------------
 567
 568 **Description**:
 569    When using VM power manager on a system with more than 64 cores, VM(s) should not use cores 64 or higher.
 570
 571 **Implication**:
 572    VM power manager should not be used with VM(s) that are using cores 64 or above.
 573
 574 **Resolution/Workaround**:
 575    Do not use cores 64 or above.
 576
 577 **Affected Environment/Platform**:
 578    Platforms with more than 64 cores.
 579
 580 **Driver/Module**:
 581    VM power manager application.
 582
 583
 584 DPDK may not build on some Intel CPUs using clang < 3.7.0
 585 ---------------------------------------------------------
 586
 587 **Description**:
 588    When compiling DPDK with an earlier version than 3.7.0 of clang, CPU flags are not detected on some Intel platforms
 589    such as Intel Broadwell/Skylake (and possibly future CPUs), and therefore compilation fails due to missing intrinsics.
 590
 591 **Implication**:
 592    DPDK will not build when using a clang version < 3.7.0.
 593
 594 **Resolution/Workaround**:
 595    Use clang 3.7.0 or higher, or gcc.
 596
 597 **Affected Environment/Platform**:
 598    Platforms with Intel Broadwell/Skylake using an old clang version.
 599
 600 **Driver/Module**:
 601    Environment Abstraction Layer (EAL).
 602
 603
 604 The last EAL argument is replaced by the program name in argv[]
 605 ---------------------------------------------------------------
 606
 607 **Description**:
 608    The last EAL argument is replaced by program name in ``argv[]`` after ``eal_parse_args`` is called.
 609    This is the intended behavior but it causes the pointer to the last EAL argument to be lost.
 610
 611 **Implication**:
 612   If the last EAL argument in ``argv[]`` is generated by a malloc function, changing it will cause memory
 613   issues when freeing the argument.
 614
 615 **Resolution/Workaround**:
 616    An application should not consider the value in ``argv[]`` as unchanged.
 617
 618 **Affected Environment/Platform**:
 619    ALL.
 620
 621 **Driver/Module**:
 622    Environment Abstraction Layer (EAL).
 623
 624
 625 I40e VF may not receive packets in the promiscuous mode
 626 -------------------------------------------------------
 627
 628 **Description**:
 629    Promiscuous mode is not supported by the DPDK i40e VF driver when using the
 630    i40e Linux kernel driver as host driver.
 631
 632 **Implication**:
 633    The i40e VF does not receive packets when the destination MAC address is unknown.
 634
 635 **Resolution/Workaround**:
 636    Use a explicit destination MAC address that matches the VF.
 637
 638 **Affected Environment/Platform**:
 639    All.
 640
 641 **Driver/Module**:
 642    Poll Mode Driver (PMD).