known_issues.rst revision 6cfa4f77
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
32Known Issues and Limitations in Legacy Releases
33===============================================
34
35This section describes known issues with the DPDK software that aren't covered in the version specific release
36notes sections.
37
38
39Unit 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
58Pause 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
78In 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
98The 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
117HPET 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
138HPET 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
161Not 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
200Multi-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
222Packets 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
244SR-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
276PMD 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
296Some 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
322Kernel 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
342Twinpond 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
361Discrepancies 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
382Error 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
404Intel® 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
424Differences 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
446Binding 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
467GCC 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
486Ethertype 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
516Cannot 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
535Devices 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
565VM 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
584DPDK 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
604The 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
625I40e 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).
643