version: 20.05-rc0
[dpdk.git] / doc / guides / rel_notes / release_2_2.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright 2016 The DPDK contributors
3
4 DPDK Release 2.2
5 ================
6
7 New Features
8 ------------
9
10 * **Introduce ARMv7 and ARMv8 architectures.**
11
12   * It is now possible to build DPDK for the ARMv7 and ARMv8 platforms.
13   * ARMv7 can be tested with virtual PMD drivers.
14   * ARMv8 can be tested with virtual and physical PMD drivers.
15
16 * **Enabled freeing of ring.**
17
18   A new function ``rte_ring_free()`` has been added to allow the user to free
19   a ring if it was created with ``rte_ring_create()``.
20
21 * **Added keepalive support to EAL and example application.**
22
23 * **Added experimental cryptodev API**
24
25   The cryptographic processing of packets is provided as a preview
26   with two drivers for:
27
28   * Intel QuickAssist devices
29   * Intel AES-NI multi-buffer library
30
31   Due to its experimental state, the API may change without prior notice.
32
33 * **Added ethdev APIs for additional IEEE1588 support.**
34
35   Added functions to read, write and adjust system time in the NIC.
36   Added client slave sample application to demonstrate the IEEE1588
37   functionality.
38
39 * **Extended Statistics.**
40
41   Defined an extended statistics naming scheme to store metadata in the name
42   string of each statistic. Refer to the Extended Statistics section of the
43   Programmers Guide for more details.
44
45   Implemented the extended statistics API for the following PMDs:
46
47   * ``igb``
48   * ``igbvf``
49   * ``i40e``
50   * ``i40evf``
51   * ``fm10k``
52   * ``virtio``
53
54 * **Added API in ethdev to retrieve RX/TX queue information.**
55
56   *  Added the ability for the upper layer to query RX/TX queue information.
57   *  Added new fields in ``rte_eth_dev_info`` to represent information about
58      RX/TX descriptors min/max/align numbers, per queue, for the device.
59
60 * **Added RSS dynamic configuration to bonding.**
61
62 * **Updated the e1000 base driver.**
63
64   The e1000 base driver was updated with several features including the
65   following:
66
67   * Added new i218 devices
68   * Allowed both ULP and EEE in Sx state
69   * Initialized 88E1543 (Marvell 1543) PHY
70   * Added flags to set EEE advertisement modes
71   * Supported inverted format ETrackId
72   * Added bit to disable packetbuffer read
73   * Added defaults for i210 RX/TX PBSIZE
74   * Check more errors for ESB2 init and reset
75   * Check more NVM read errors
76   * Return code after setting receive address register
77   * Removed all NAHUM6LP_HW tags
78
79 * **Added e1000 RX interrupt support.**
80
81 * **Added igb TSO support for both PF and VF.**
82
83 * **Added RSS enhancements to Intel x550 NIC.**
84
85   * Added support for 512 entry RSS redirection table.
86   * Added support for per VF RSS redirection table.
87
88 * **Added Flow director enhancements on Intel x550 NIC.**
89
90   * Added 2 new flow director modes on x550.
91     One is MAC VLAN mode, the other is tunnel mode.
92
93 * **Updated the i40e base driver.**
94
95   The i40e base driver was updated with several changes including the
96   following:
97
98   *  Added promiscuous on VLAN support
99   *  Added a workaround to drop all flow control frames
100   *  Added VF capabilities to virtual channel interface
101   *  Added TX Scheduling related AQ commands
102   *  Added additional PCTYPES supported for FortPark RSS
103   *  Added parsing for CEE DCBX TLVs
104   *  Added FortPark specific registers
105   *  Added AQ functions to handle RSS Key and LUT programming
106   *  Increased PF reset max loop limit
107
108 * **Added i40e vector RX/TX.**
109
110 * **Added i40e RX interrupt support.**
111
112 * **Added i40e flow control support.**
113
114 * **Added DCB support to i40e PF driver.**
115
116 * **Added RSS/FD input set granularity on Intel X710/XL710.**
117
118 * **Added different GRE key length for input set on Intel X710/XL710.**
119
120 * **Added flow director support in i40e VF.**
121
122 * **Added i40e support of early X722 series.**
123
124   Added early X722 support, for evaluation only, as the hardware is alpha.
125
126 * **Added fm10k vector RX/TX.**
127
128 * **Added fm10k TSO support for both PF and VF.**
129
130 * **Added fm10k VMDQ support.**
131
132 * **New NIC Boulder Rapid support.**
133
134   Added support for the Boulder Rapid variant of Intel's fm10k NIC family.
135
136 * **Enhanced support for the Chelsio CXGBE driver.**
137
138   *  Added support for Jumbo Frames.
139   *  Optimized forwarding performance for Chelsio T5 40GbE cards.
140
141 * **Improved enic TX packet rate.**
142
143   Reduced frequency of TX tail pointer updates to the NIC.
144
145 * **Added support for link status interrupts in mlx4.**
146
147 * **Added partial support (TX only) for secondary processes in mlx4.**
148
149 * **Added support for Mellanox ConnectX-4 adapters (mlx5).**
150
151   The mlx5 poll-mode driver implements support for Mellanox ConnectX-4 EN
152   and Mellanox ConnectX-4 Lx EN families of 10/25/40/50/100 Gb/s adapters.
153
154   Like mlx4, this PMD is only available for Linux and is disabled by default
155   due to external dependencies (libibverbs and libmlx5).
156
157 * **Added driver for Netronome nfp-6xxx card.**
158
159   Support for using Netronome nfp-6xxx with PCI VFs.
160
161 * **Added virtual szedata2 driver for COMBO cards.**
162
163   Added virtual PMD for COMBO-100G and COMBO-80G cards.
164   PMD is disabled in default configuration.
165
166 * **Enhanced support for virtio driver.**
167
168   * Virtio ring layout optimization (fixed avail ring)
169   * Vector RX
170   * Simple TX
171
172 * **Added vhost-user multiple queue support.**
173
174 * **Added port hotplug support to vmxnet3.**
175
176 * **Added port hotplug support to xenvirt.**
177
178 * **Added ethtool shim and sample application.**
179
180 * **Added experimental performance thread example application.**
181
182   The new sample application demonstrates L3 forwarding with different threading
183   models: pthreads, cgroups, or lightweight threads. The example includes
184   a simple cooperative scheduler.
185
186   Due to its experimental state this application may change without notice.
187   The application is supported only for Linux x86_64.
188
189 * **Enhancements to the IP pipeline application.**
190
191   The following features have been added to the ``ip_pipeline``
192   application;
193
194   * Added Multiple Producers/Multiple Consumers (MPSC)
195     and fragmentation/reassembly support to software rings.
196
197   * Added a dynamic pipeline reconfiguration feature that
198     allows binding a pipeline to other threads at runtime
199     using CLI commands.
200
201   * Added enable/disable of ``promisc`` mode from ``ip_pipeline``
202     configuration file.
203
204   * Added check on RX queues and TX queues of each link
205     whether they are used correctly in the ``ip_pipeline``
206     configuration file.
207
208   * Added flow id parameters to the flow-classification
209     table entries.
210
211   * Added more functions to the routing pipeline:
212     ARP table enable/disable, Q-in-Q and MPLS encapsulation,
213     add color (traffic-class for QoS) to the MPLS tag.
214
215   * Added flow-actions pipeline for traffic metering/marking
216     (for e.g. Two Rate Three Color Marker (trTCM)), policer etc.
217
218   * Modified the pass-through pipeline's actions-handler to
219     implement a generic approach to extract fields from the
220     packet's header and copy them to packet metadata.
221
222
223 Resolved Issues
224 ---------------
225
226 EAL
227 ~~~
228
229 * **eal/linux: Fixed epoll timeout.**
230
231   Fixed issue where the ``rte_epoll_wait()`` function didn't return when the
232   underlying call to ``epoll_wait()`` timed out.
233
234
235 Drivers
236 ~~~~~~~
237
238 * **e1000/base: Synchronize PHY interface on non-ME systems.**
239
240   On power up, the MAC - PHY interface needs to be set to PCIe, even if the
241   cable is disconnected. In ME systems, the ME handles this on exit from the
242   Sx (Sticky mode) state. In non-ME, the driver handles it. Added a check for
243   non-ME system to the driver code that handles it.
244
245 * **e1000/base: Increased timeout of reset check.**
246
247   Previously, in ``check_reset_block`` RSPCIPHY was polled for 100 ms before
248   determining that the ME veto was set. This was not enough and it was
249   increased to 300 ms.
250
251 * **e1000/base: Disabled IPv6 extension header parsing on 82575.**
252
253   Disabled IPv6 options as per hardware limitation.
254
255 * **e1000/base: Prevent ULP flow if cable connected.**
256
257   Enabling ULP on link down when the cable is connected caused an infinite
258   loop of link up/down indications in the NDIS driver.
259   The driver now enables ULP only when the cable is disconnected.
260
261 * **e1000/base: Support different EEARBC for i210.**
262
263   EEARBC has changed on i210. It means EEARBC has a different address on
264   i210 than on other NICs. So, add a new entity named EEARBC_I210 to the
265   register list and make sure the right one is being used on i210.
266
267 * **e1000/base: Fix K1 configuration.**
268
269   Added fix for the following updates to the K1 configurations:
270   TX idle period for entering K1 should be 128 ns.
271   Minimum TX idle period in K1 should be 256 ns.
272
273 * **e1000/base: Fix link detect flow.**
274
275   Fix link detect flow in case where auto-negotiate is not enabled, by calling
276   ``e1000_setup_copper_link_generic`` instead of ``e1000_phy_setup_autoneg``.
277
278 * **e1000/base: Fix link check for i354 M88E1112 PHY.**
279
280   The ``e1000_check_for_link_media_swap()`` function is supposed to check PHY
281   page 0 for copper and PHY page 1 for "other" (fiber) links. The driver
282   switched back from page 1 to page 0 too soon, before
283   ``e1000_check_for_link_82575()`` is executed and was never finding the link
284   on the fiber (other).
285
286   If the link is copper, as the M88E1112 page address is set to 1, it should be
287   set back to 0 before checking this link.
288
289 * **e1000/base: Fix beacon duration for i217.**
290
291   Fix for I217 Packet Loss issue - The Management Engine sets the FEXTNVM4
292   Beacon Duration incorrectly. This fix ensures that the correct value will
293   always be set. Correct value for this field is 8 usec.
294
295 * **e1000/base: Fix TIPG for non 10 half duplex mode.**
296
297   TIPG value is increased when setting speed to 10 half duplex to prevent
298   packet loss. However, it was never decreased again when speed
299   changed. This caused performance issues in the NDIS driver.
300   Fix this to restore TIPG to default value on non 10 half duplex.
301
302 * **e1000/base: Fix reset of DH89XXCC SGMII.**
303
304   For DH89XXCC_SGMII, a write flush leaves registers of this device trashed
305   (0xFFFFFFFF). Add check for this device.
306
307   Also, after both Port SW Reset and Device Reset case, the platform should
308   wait at least 3ms before reading any registers. Remove this condition since
309   waiting is conditionally executed only for Device Reset.
310
311 * **e1000/base: Fix redundant PHY power down for i210.**
312
313   Bit 11 of PHYREG 0 is used to power down PHY. The use of PHYREG 16 is
314   no longer necessary.
315
316 * **e1000/base: fix jumbo frame CRC failures.**
317
318   Change the value of register 776.20[11:2] for jumbo mode from 0x1A to 0x1F.
319   This is to enlarge the gap between read and write pointers in the TX FIFO.
320
321 * **e1000/base: Fix link flap on 82579.**
322
323   Several customers have reported a link flap issue on 82579. The symptoms
324   are random and intermittent link losses when 82579 is connected to specific
325   switches. the Issue was root caused as an inter-operability problem between
326   the NIC and at least some Broadcom PHYs in the Energy Efficient Ethernet
327   wake mechanism.
328
329   To fix the issue, we are disabling the Phase Locked Loop shutdown in 100M
330   Low Power Idle. This solution will cause an increase of power in 100M EEE
331   link. It may cost an additional 28mW in this specific mode.
332
333 * **igb: Fixed IEEE1588 frame identification in I210.**
334
335   Fixed issue where the flag ``PKT_RX_IEEE1588_PTP`` was not being set
336   in the Intel I210 NIC, as the EtherType in RX descriptor is in bits 8:10 of
337   Packet Type and not in the default bits 0:2.
338
339 * **igb: Fixed VF start with PF stopped.**
340
341   VF needs the PF interrupt support initialized even if not started.
342
343 * **igb: Fixed VF MAC address when using with DPDK PF.**
344
345   Assign a random MAC address in VF when not assigned by PF.
346
347 * **igb: Removed CRC bytes from byte counter statistics.**
348
349 * **ixgbe: Fixed issue with X550 DCB.**
350
351   Fixed a DCB issue with x550 where for 8 TCs (Traffic Classes), if a packet
352   with user priority 6 or 7 was injected to the NIC, then the NIC would only
353   put 3 packets into the queue. There was also a similar issue for 4 TCs.
354
355 * **ixgbe: Removed burst size restriction of vector RX.**
356
357   Fixed issue where a burst size less than 32 didn't receive anything.
358
359 * **ixgbe: Fixed VF start with PF stopped.**
360
361   VF needs the PF interrupt support initialized even if not started.
362
363 * **ixgbe: Fixed TX hang when RS distance exceeds HW limit.**
364
365   Fixed an issue where the TX queue can hang when a lot of highly fragmented
366   packets have to be sent. As part of that fix, ``tx_rs_thresh`` for ixgbe PMD
367   is not allowed to be greater then to 32 to comply with HW restrictions.
368
369 * **ixgbe: Fixed rx error statistic counter.**
370
371   Fixed an issue that the rx error counter of ixgbe was not accurate. The
372   mac short packet discard count (mspdc) was added to the counter. Mac local
373   faults and mac remote faults are removed as they do not count packets but
374   errors, and jabber errors were removed as they are already accounted for
375   by the CRC error counter. Finally the XEC (l3 / l4 checksum error) counter
376   was removed due to errata, see commit 256ff05a9cae for details.
377
378 * **ixgbe: Removed CRC bytes from byte counter statistics.**
379
380 * **i40e: Fixed base driver allocation when not using first numa node.**
381
382   Fixed i40e issue that occurred when a DPDK application didn't initialize
383   ports if memory wasn't available on socket 0.
384
385 * **i40e: Fixed maximum of 64 queues per port.**
386
387   Fixed an issue in i40e where it would not support more than 64 queues per
388   port, even though the hardware actually supports it. The real number of
389   queues may vary, as long as the total number of queues used in PF, VFs, VMDq
390   and FD does not exceeds the hardware maximum.
391
392 * **i40e: Fixed statistics of packets.**
393
394   Added discarding packets on VSI to the stats and rectify the old statistics.
395
396 * **i40e: Fixed issue of not freeing memzone.**
397
398   Fixed an issue of not freeing a memzone in the call to free the memory for
399   adminq DMA.
400
401 * **i40e: Removed CRC bytes from byte counter statistics.**
402
403 * **mlx: Fixed driver loading.**
404
405   The mlx drivers were unable to load when built as a shared library,
406   due to a missing symbol in the mempool library.
407
408 * **mlx4: Performance improvements.**
409
410   Fixed bugs in TX and RX flows that improves mlx4 performance.
411
412 * **mlx4: Fixed TX loss after initialization.**
413
414 * **mlx4: Fixed scattered TX with too many segments.**
415
416 * **mlx4: Fixed memory registration for indirect mbuf data.**
417
418 * **vhost: Fixed Qemu shutdown.**
419
420   Fixed issue with libvirt ``virsh destroy`` not killing the VM.
421
422 * **virtio: Fixed crash after changing link state.**
423
424   Fixed IO permission in the interrupt handler.
425
426 * **virtio: Fixed crash when releasing queue.**
427
428   Fixed issue when releasing null control queue.
429
430
431 Libraries
432 ~~~~~~~~~
433
434 * **hash: Fixed memory allocation of Cuckoo Hash key table.**
435
436   Fixed issue where an incorrect Cuckoo Hash key table size could be
437   calculated limiting the size to 4GB.
438
439 * **hash: Fixed incorrect lookup if key is all zero.**
440
441   Fixed issue in hash library that occurred if an all zero
442   key was not added to the table and the key was looked up,
443   resulting in an incorrect hit.
444
445 * **hash: Fixed thread scaling by reducing contention.**
446
447   Fixed issue in the hash library where, using multiple cores with
448   hardware transactional memory support, thread scaling did not work,
449   due to the global ring that is shared by all cores.
450
451
452 Examples
453 ~~~~~~~~
454
455 * **l3fwd: Fixed crash with IPv6.**
456
457 * **vhost_xen: Fixed compile error.**
458
459
460 Other
461 ~~~~~
462
463 * This release drops compatibility with Linux kernel 2.6.33. The minimum
464   kernel requirement is now 2.6.34.
465
466
467 Known Issues
468 ------------
469
470 * Some drivers do not fill in the packet type when receiving.
471   As the l3fwd example application requires this info, the i40e vector
472   driver must be disabled to benefit of the packet type with i40e.
473
474 * Some (possibly all) VF drivers (e.g. i40evf) do not handle any PF reset
475   events/requests in the VF driver. This means that the VF driver may not work
476   after a PF reset in the host side. The workaround is to avoid triggering any
477   PF reset events/requests on the host side.
478
479 * 100G link report support is missing.
480
481 * **Mellanox PMDs (mlx4 & mlx5):**
482
483   * PMDs do not support CONFIG_RTE_BUILD_COMBINE_LIBS and
484     CONFIG_RTE_BUILD_SHARED_LIB simultaneously.
485
486   * There is performance degradation for small packets when the PMD is
487     compiled with ``SGE_WR_N = 4`` compared to the performance when ``SGE_WR_N
488     = 1``. If scattered packets are not used it is recommended to compile the
489     PMD with ``SGE_WR_N = 1``.
490
491   * When a Multicast or Broadcast packet is sent to the SR-IOV mlx4 VF,
492     it is returned back to the port.
493
494   * PMDs report "bad" L4 checksum when IP packet is received.
495
496   * mlx5 PMD reports "bad" checksum although the packet has "good" checksum.
497     Will be fixed in upcoming MLNX_OFED release.
498
499
500 API Changes
501 -----------
502
503 * The deprecated flow director API is removed.
504   It was replaced by ``rte_eth_dev_filter_ctrl()``.
505
506 * The ``dcb_queue`` is renamed to ``dcb_tc`` in following dcb configuration
507   structures: ``rte_eth_dcb_rx_conf``, ``rte_eth_dcb_tx_conf``,
508   ``rte_eth_vmdq_dcb_conf``, ``rte_eth_vmdq_dcb_tx_conf``.
509
510 * The ``rte_eth_rx_queue_count()`` function now returns "int" instead of
511   "uint32_t" to allow the use of negative values as error codes on return.
512
513 * The function ``rte_eal_pci_close_one()`` is removed.
514   It was replaced by ``rte_eal_pci_detach()``.
515
516 * The deprecated ACL API ``ipv4vlan`` is removed.
517
518 * The deprecated hash function ``rte_jhash2()`` is removed.
519   It was replaced by ``rte_jhash_32b()``.
520
521 * The deprecated KNI functions are removed:
522   ``rte_kni_create()``, ``rte_kni_get_port_id()`` and ``rte_kni_info_get()``.
523
524 * The deprecated ring PMD functions are removed:
525   ``rte_eth_ring_pair_create()`` and ``rte_eth_ring_pair_attach()``.
526
527 * The devargs union field ``virtual`` is renamed to ``virt`` for C++
528   compatibility.
529
530
531 ABI Changes
532 -----------
533
534 * The EAL and ethdev structures ``rte_intr_handle`` and ``rte_eth_conf`` were
535   changed to support RX interrupt. This was already included in 2.1 under the
536   ``CONFIG_RTE_NEXT_ABI`` #define.
537
538 * The ethdev flow director entries for SCTP were changed.
539   This was already included in 2.1 under the ``CONFIG_RTE_NEXT_ABI`` #define.
540
541 * The ethdev flow director structure ``rte_eth_fdir_flow_ext`` structure was
542   changed. New fields were added to support flow director filtering in VF.
543
544 * The size of the ethdev structure ``rte_eth_hash_filter_info`` is changed
545   by adding a new element ``rte_eth_input_set_conf`` in a union.
546
547 * New fields ``rx_desc_lim`` and ``tx_desc_lim`` are added into
548   ``rte_eth_dev_info`` structure.
549
550 * For debug builds, the functions ``rte_eth_rx_burst()``, ``rte_eth_tx_burst()``
551   ``rte_eth_rx_descriptor_done()`` and ``rte_eth_rx_queue_count()`` will
552   no longer be separate functions in the DPDK libraries. Instead, they will
553   only be present in the ``rte_ethdev.h`` header file.
554
555 * The maximum number of queues per port ``CONFIG_RTE_MAX_QUEUES_PER_PORT`` is
556   increased to 1024.
557
558 * The mbuf structure was changed to support the unified packet type.
559   This was already included in 2.1 under the ``CONFIG_RTE_NEXT_ABI`` #define.
560
561 * The dummy malloc library is removed. The content was moved into EAL in 2.1.
562
563 * The LPM structure is changed. The deprecated field ``mem_location`` is
564   removed.
565
566 * librte_table LPM: A new parameter to hold the table name will be added to
567   the LPM table parameter structure.
568
569 * librte_table hash: The key mask parameter is added to the hash table
570   parameter structure for 8-byte key and 16-byte key extendable bucket
571   and LRU tables.
572
573 * librte_port: Macros to access the packet meta-data stored within the packet
574   buffer has been adjusted to cover the packet mbuf structure.
575
576 * librte_cfgfile: Allow longer names and values by increasing the constants
577   ``CFG_NAME_LEN`` and ``CFG_VALUE_LEN`` to 64 and 256 respectively.
578
579 * vhost: a new field enabled is added to the ``vhost_virtqueue`` structure.
580
581 * vhost: a new field ``virt_qp_nb`` is added to ``virtio_net`` structure, and
582   the ``virtqueue`` field is moved to the end of virtio_net structure.
583
584 * vhost: a new operation ``vring_state_changed`` is added to
585   ``virtio_net_device_ops`` structure.
586
587 * vhost: a few spaces are reserved both at ``vhost_virtqueue`` and
588   ``virtio_net`` structure for future extension.
589
590
591 Shared Library Versions
592 -----------------------
593
594 The libraries prepended with a plus sign were incremented in this version.
595
596 .. code-block:: diff
597
598    + libethdev.so.2
599    + librte_acl.so.2
600    + librte_cfgfile.so.2
601      librte_cmdline.so.1
602      librte_distributor.so.1
603    + librte_eal.so.2
604    + librte_hash.so.2
605      librte_ip_frag.so.1
606      librte_ivshmem.so.1
607      librte_jobstats.so.1
608    + librte_kni.so.2
609      librte_kvargs.so.1
610    + librte_lpm.so.2
611    + librte_mbuf.so.2
612      librte_mempool.so.1
613      librte_meter.so.1
614    + librte_pipeline.so.2
615      librte_pmd_bond.so.1
616    + librte_pmd_ring.so.2
617    + librte_port.so.2
618      librte_power.so.1
619      librte_reorder.so.1
620      librte_ring.so.1
621      librte_sched.so.1
622    + librte_table.so.2
623      librte_timer.so.1
624    + librte_vhost.so.2