doc/guides/rel_notes/updating_apps.rst

   1 Updating Applications from Previous Versions
   2 ============================================
   3
   4 Although backward compatibility is being maintained across DPDK releases, code written for previous versions of the DPDK
   5 may require some code updates to benefit from performance and user experience enhancements provided in later DPDK releases.
   6
   7 DPDK 2.0 to DPDK 2.1
   8 --------------------
   9
  10 *   The second argument of rte_pktmbuf_pool_init(mempool, opaque) is now a
  11     pointer to a struct rte_pktmbuf_pool_private instead of a uint16_t
  12     casted into a pointer. Backward compatibility is preserved when the
  13     argument was NULL which is the majority of use cases, but not if the
  14     opaque pointer was not NULL, as it is not technically feasible. In
  15     this case, the application has to be modified to properly fill a
  16     rte_pktmbuf_pool_private structure and pass it to
  17     rte_pktmbuf_pool_init().
  18
  19 *   A simpler helper rte_pktmbuf_pool_create() can be used to create a
  20     packet mbuf pool. The old way using rte_mempool_create() is still
  21     supported though and is still used for more specific cases.
  22
  23 DPDK 1.7 to DPDK 1.8
  24 --------------------
  25
  26 Note that in DPDK 1.8, the structure of the rte_mbuf has changed considerably from all previous versions.
  27 It is recommended that users familiarize themselves with the new structure defined in the file rte_mbuf.h in the release package.
  28 The follow are some common changes that need to be made to code using mbufs, following an update to DPDK 1.8:
  29
  30 *   Any references to fields in the pkt or ctrl sub-structures of the mbuf, need to be replaced with references to the field
  31     directly from the rte_mbuf, i.e. buf->pkt.data_len should be replace by buf->data_len.
  32
  33 *   Any direct references to the data field of the mbuf (original buf->pkt.data) should now be replace by the macro rte_pktmbuf_mtod
  34     to get a computed data address inside the mbuf buffer area.
  35
  36 *   Any references to the in_port mbuf field should be replace by references to the port field.
  37
  38 NOTE: The above list is not exhaustive, but only includes the most commonly required changes to code using mbufs.
  39
  40 Intel® DPDK 1.6 to DPDK 1.7
  41 ---------------------------
  42
  43 Note the following difference between 1.6 and 1.7:
  44
  45 *   The "default" target has been renamed to "native"
  46
  47 Intel® DPDK 1.5 to Intel® DPDK 1.6
  48 ----------------------------------
  49
  50 Note the following difference between 1.5 and 1.6:
  51
  52 *   The CONFIG_RTE_EAL _UNBIND_PORTS configuration option, which was deprecated in Intel® DPDK 1.4.x, has been removed in Intel® DPDK 1.6.x.
  53     Applications using the Intel® DPDK must be explicitly unbound to the igb_uio driver using the dpdk_nic_bind.py script included in the
  54     Intel® DPDK release and documented in the *Intel® DPDK Getting Started Guide*.
  55
  56 Intel® DPDK 1.4 to Intel® DPDK 1.5
  57 ----------------------------------
  58
  59 Note the following difference between 1.4 and 1.5:
  60
  61 *   Starting with version 1.5, the top-level directory created from unzipping the release package will now contain the release version number,
  62     that is, DPDK-1.5.2/ rather than just DPDK/ .
  63
  64 Intel® DPDK 1.3 to Intel® DPDK 1.4.x
  65 ------------------------------------
  66
  67 Note the following difference between releases 1.3 and 1.4.x:
  68
  69 *   In Release 1.4.x, Intel® DPDK applications will no longer unbind the network ports from the Linux* kernel driver when the application initializes.
  70     Instead, any ports to be used by Intel® DPDK must be unbound from the Linux driver and bound to the igb_uio driver before the application starts.
  71     This can be done using the pci_unbind.py script included with the Intel® DPDK release and documented in the *Intel® DPDK Getting Started Guide*.
  72
  73     If the port unbinding behavior present in previous Intel® DPDK releases is required, this can be re-enabled using the CONFIG_RTE_EAL_UNBIND_PORTS
  74     setting in the appropriate Intel® DPDK compile-time configuration file.
  75
  76 *   In Release 1.4.x, HPET support is disabled in the Intel® DPDK build configuration files, which means that the existing rte_eal_get_hpet_hz() and
  77     rte_eal_get_hpet_cycles() APIs are not available by default.
  78     For applications that require timing APIs, but not the HPET timer specifically, it is recommended that the API calls rte_get_timer_cycles()
  79     and rte_get_timer_hz() be used instead of the HPET-specific APIs.
  80     These generic APIs can work with either TSC or HPET time sources, depending on what is requested by an application,
  81     and on what is available on the system at runtime.
  82
  83     For more details on this and how to re-enable the HPET if it is needed, please consult the *Intel® DPDK Getting Started Guide*.
  84
  85 Intel® DPDK 1.2 to Intel® DPDK 1.3
  86 ----------------------------------
  87
  88 Note the following difference between releases 1.2 and 1.3:
  89
  90 *   In release 1.3, the Intel® DPDK supports two different 1 GBe drivers: igb and em.
  91     Both of them are located in the same library: lib_pmd_e1000.a.
  92     Therefore, the name of the library to link with for the igb PMD has changed from librte_pmd_igb.a to librte_pmd_e1000.a.
  93
  94 *   The rte_common.h macros, RTE_ALIGN, RTE_ALIGN_FLOOR and RTE_ALIGN_CEIL were renamed to, RTE_PTR_ALIGN, RTE_PTR_ALIGN_FLOOR
  95     and RTE_PTR_ALIGN_CEIL.
  96     The original macros are still available but they have different behavior.
  97     Not updating the macros results in strange compilation errors.
  98
  99 *   The rte_tailq is now defined statically. The rte_tailq APIs have also been changed from being public to internal use only.
 100     The old public APIs are maintained for backward compatibility reasons. Details can be found in the *Intel® DPDK API Reference*.
 101
 102 *   The method for managing mbufs on the NIC RX rings has been modified to improve performance.
 103     To allow applications to use the newer, more optimized, code path,
 104     it is recommended that the rx_free_thresh field in the rte_eth_conf structure,
 105     which is passed to the Poll Mode Driver when initializing a network port, be set to a value of 32.
 106
 107 Intel® DPDK 1.1 to Intel® DPDK 1.2
 108 ----------------------------------
 109
 110 Note the following difference between release 1.1 and release 1.2:
 111
 112 *   The names of the 1G and 10G Ethernet drivers have changed between releases 1.1 and 1.2. While the old driver names still work,
 113     it is recommended that code be updated to the new names, since the old names are deprecated and may be removed in a future
 114     release.
 115
 116     The items affected are as follows:
 117
 118     *   Any macros referring to RTE_LIBRTE_82576_PMD should be updated to refer to RTE_LIBRTE_IGB_PMD.
 119
 120     *   Any macros referring to RTE_LIBRTE_82599_PMD should be updated to refer to RTE_LIBRTE_IXGBE_PMD.
 121
 122     *   Any calls to the rte_82576_pmd_init() function should be replaced by calls to rte_igb_pmd_init().
 123
 124     *   Any calls to the rte_82599_pmd_init() function should be replaced by calls to rte_ixgbe_pmd_init().
 125
 126 *   The method used for managing mbufs on the NIC TX rings for the 10 GbE driver has been modified to improve performance.
 127     As a result, different parameter values should be passed to the rte_eth_tx_queue_setup() function.
 128     The recommended default values are to have tx_thresh.tx_wt hresh, tx_free_thresh,
 129     as well as the new parameter tx_rs_thresh (all in the struct rte_eth_txconf datatype) set to zero.
 130     See the "Configuration of Transmit and Receive Queues" section in the *Intel® DPDK Programmer's Guide* for more details.
 131
 132 .. note::
 133
 134     If the tx_free_thresh field is set to TX_RING_SIZE+1 , as was previously used in some cases to disable free threshold check,
 135     then an error is generated at port initialization time.
 136     To avoid this error, configure the TX threshold values as suggested above.