doc/guides/rel_notes/deprecation.rst

   1 ABI and API Deprecation
   2 =======================
   3
   4 See the :doc:`guidelines document for details of the ABI policy </contributing/versioning>`.
   5 API and ABI deprecation notices are to be posted here.
   6
   7
   8 Deprecation Notices
   9 -------------------
  10
  11 * eal: both declaring and identifying devices will be streamlined in v18.05.
  12   New functions will appear to query a specific port from buses, classes of
  13   device and device drivers. Device declaration will be made coherent with the
  14   new scheme of device identification.
  15   As such, ``rte_devargs`` device representation will change.
  16
  17   - removal of ``name`` and ``args`` fields.
  18   - The enum ``rte_devtype`` was used to identify a bus and will disappear.
  19   - The ``rte_devargs_list`` will be made private.
  20   - Functions previously deprecated will change or disappear:
  21
  22     + ``rte_eal_devargs_add``
  23     + ``rte_eal_devargs_type_count``
  24     + ``rte_eal_parse_devargs_str``, replaced by ``rte_eal_devargs_parse``
  25     + ``rte_eal_devargs_parse`` will change its format and use.
  26     + all ``rte_devargs`` related functions will be renamed, changing the
  27       ``rte_eal_devargs_`` prefix to ``rte_devargs_``.
  28
  29 * pci: Several exposed functions are misnamed.
  30   The following functions are deprecated starting from v17.11 and are replaced:
  31
  32   - ``eal_parse_pci_BDF`` replaced by ``rte_pci_addr_parse``
  33   - ``eal_parse_pci_DomBDF`` replaced by ``rte_pci_addr_parse``
  34   - ``rte_eal_compare_pci_addr`` replaced by ``rte_pci_addr_cmp``
  35
  36 * eal: The semantics of the return value for the ``rte_lcore_has_role`` function
  37   are planned to change in v18.05. The function currently returns 0 and <0 for
  38   success and failure, respectively.  This will change to 1 and 0 for true and
  39   false, respectively, to make use of the function more intuitive.
  40
  41 * eal: new ``numa_node_count`` member will be added to ``rte_config`` structure
  42   in v18.05.
  43
  44 * eal: due to internal data layout reorganization, there will be changes to
  45   several structures and functions as a result of coming changes to support
  46   memory hotplug in v18.05.
  47   ``rte_eal_get_physmem_layout`` will be deprecated and removed in subsequent
  48   releases.
  49   ``rte_mem_config`` contents will change due to switch to memseg lists.
  50   ``rte_memzone`` member ``memseg_id`` will no longer serve any useful purpose
  51   and will be removed.
  52
  53 * eal: a new set of mbuf mempool ops name APIs for user, platform and best
  54   mempool names have been defined in ``rte_mbuf`` in v18.02. The uses of
  55   ``rte_eal_mbuf_default_mempool_ops`` shall be replaced by
  56   ``rte_mbuf_best_mempool_ops``.
  57   The following function is now redundant and it is target to be deprecated
  58   in 18.05:
  59
  60   - ``rte_eal_mbuf_default_mempool_ops``
  61
  62 * mempool: several API and ABI changes are planned in v18.05.
  63   The following functions, introduced for Xen, which is not supported
  64   anymore since v17.11, are hard to use, not used anywhere else in DPDK.
  65   Therefore they will be deprecated in v18.05 and removed in v18.08:
  66
  67   - ``rte_mempool_xmem_create``
  68   - ``rte_mempool_xmem_size``
  69   - ``rte_mempool_xmem_usage``
  70
  71   The following changes are planned:
  72
  73   - removal of ``get_capabilities`` mempool ops and related flags.
  74   - substitute ``register_memory_area`` with ``populate`` ops.
  75   - addition of new ops to customize required memory chunk calculation,
  76     customize objects population and allocate contiguous
  77     block of objects if underlying driver supports it.
  78
  79 * mbuf: The control mbuf API will be removed in v18.05. The impacted
  80   functions and macros are:
  81
  82   - ``rte_ctrlmbuf_init()``
  83   - ``rte_ctrlmbuf_alloc()``
  84   - ``rte_ctrlmbuf_free()``
  85   - ``rte_ctrlmbuf_data()``
  86   - ``rte_ctrlmbuf_len()``
  87   - ``rte_is_ctrlmbuf()``
  88   - ``CTRL_MBUF_FLAG``
  89
  90   The packet mbuf API should be used as a replacement.
  91
  92 * mbuf: The opaque ``mbuf->hash.sched`` field will be updated to support generic
  93   definition in line with the ethdev TM and MTR APIs. Currently, this field
  94   is defined in librte_sched in a non-generic way. The new generic format
  95   will contain: queue ID, traffic class, color. Field size will not change.
  96
  97 * ethdev: a new Tx and Rx offload API was introduced on 17.11.
  98   In the new API, offloads are divided into per-port and per-queue offloads.
  99   Offloads are disabled by default and enabled per application request.
 100   The old offloads API is target to be deprecated on 18.05. This includes:
 101
 102   - removal of ``ETH_TXQ_FLAGS_NO*`` flags.
 103   - removal of ``txq_flags`` field from ``rte_eth_txconf`` struct.
 104   - removal of the offloads bit-field from ``rte_eth_rxmode`` struct.
 105
 106 * ethdev: the legacy filter API, including
 107   ``rte_eth_dev_filter_supported()``, ``rte_eth_dev_filter_ctrl()`` as well
 108   as filter types MACVLAN, ETHERTYPE, FLEXIBLE, SYN, NTUPLE, TUNNEL, FDIR,
 109   HASH and L2_TUNNEL, is superseded by the generic flow API (rte_flow) in
 110   PMDs that implement the latter.
 111   Target release for removal of the legacy API will be defined once most
 112   PMDs have switched to rte_flow.
 113
 114 * ethdev: A new rss level field planned in 18.05.
 115   The new API add rss_level field to ``rte_eth_rss_conf`` to enable a choice
 116   of RSS hash calculation on outer or inner header of tunneled packet.
 117
 118 * ethdev:  Currently, if the  rte_eth_rx_burst() function returns a value less
 119   than *nb_pkts*, the application will assume that no more packets are present.
 120   Some of the hw queue based hardware can only support smaller burst for RX
 121   and TX and thus break the expectation of the rx_burst API. Similar is the
 122   case for TX burst as well as ring sizes. ``rte_eth_dev_info`` will be added
 123   with following new parameters so as to support semantics for drivers to
 124   define a preferred size for Rx/Tx burst and rings.
 125
 126   - Member ``struct preferred_size`` would be added to enclose all preferred
 127     size to be fetched from driver/implementation.
 128   - Members ``uint16_t rx_burst``,  ``uint16_t tx_burst``, ``uint16_t rx_ring``,
 129     and ``uint16_t tx_ring`` would be added to ``struct preferred_size``.
 130
 131 * ethdev: A work is being planned for 18.05 to expose VF port representors
 132   as a mean to perform control and data path operation on the different VFs.
 133   As VF representor is an ethdev port, new fields are needed in order to map
 134   between the VF representor and the VF or the parent PF. Those new fields
 135   are to be included in ``rte_eth_dev_info`` struct.
 136
 137 * ethdev: The prototype and the behavior of
 138   ``dev_ops->eth_mac_addr_set()`` will change in v18.05. A return code
 139   will be added to notify the caller if an error occurred in the PMD. In
 140   ``rte_eth_dev_default_mac_addr_set()``, the new default MAC address
 141   will be copied in ``dev->data->mac_addrs[0]`` only if the operation is
 142   successful. This modification will only impact the PMDs, not the
 143   applications.
 144
 145 * i40e: The default flexible payload configuration which extracts the first 16
 146   bytes of the payload for RSS will be deprecated starting from 18.02. If
 147   required the previous behavior can be configured using existing flow
 148   director APIs. There is no ABI/API break. This change will just remove a
 149   global configuration setting and require explicit configuration.
 150
 151 * librte_meter: The API will change to accommodate configuration profiles.
 152   Most of the API functions will have an additional opaque parameter.
 153
 154 * ring: The alignment constraints on the ring structure will be relaxed
 155   to one cache line instead of two, and an empty cache line padding will
 156   be added between the producer and consumer structures. The size of the
 157   structure and the offset of the fields will remain the same on
 158   platforms with 64B cache line, but will change on other platforms.