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 * ring: Changes are planned to rte_ring APIs in release 17.05. Proposed
  12   changes include:
  13
  14     - Removing build time options for the ring:
  15       CONFIG_RTE_RING_SPLIT_PROD_CONS
  16       CONFIG_RTE_RING_PAUSE_REP_COUNT
  17     - Adding an additional parameter to enqueue functions to return the
  18       amount of free space in the ring
  19     - Adding an additional parameter to dequeue functions to return the
  20       number of remaining elements in the ring
  21     - Removing direct support for watermarks in the rings, since the
  22       additional return value from the enqueue function makes it
  23       unneeded
  24     - Adjusting the return values of the bulk() enq/deq functions to
  25       make them consistent with the burst() equivalents. [Note, parameter
  26       to these functions are changing too, per points above, so compiler
  27       will flag them as needing update in legacy code]
  28     - Updates to some library functions e.g. rte_ring_get_memsize() to
  29       allow for variably-sized ring elements.
  30
  31 * igb_uio: iomem mapping and sysfs files created for iomem and ioport in
  32   igb_uio will be removed, because we are able to detect these from what Linux
  33   has exposed, like the way we have done with uio-pci-generic. This change
  34   targets release 17.05.
  35
  36 * vfio: Some functions are planned to be exported outside librte_eal in 17.05.
  37   VFIO APIs like ``vfio_setup_device``, ``vfio_get_group_fd`` can be used by
  38   subsystem other than EAL/PCI. For that, these need to be exported symbols.
  39   Such APIs are planned to be renamed according to ``rte_*`` naming convention
  40   and exported from librte_eal.
  41
  42 * The PCI and VDEV subsystems will be converted as drivers of the new bus model.
  43   It will imply some EAL API changes in 17.05.
  44
  45 * ``eth_driver`` is planned to be removed in 17.05. This currently serves as
  46   a placeholder for PMDs to register themselves. Changes for ``rte_bus`` will
  47   provide a way to handle device initialization currently being done in
  48   ``eth_driver``. Similarly, ``rte_pci_driver`` is planned to be removed from
  49   ``rte_cryptodev_driver`` in 17.05.
  50
  51 * ethdev: An API change is planned for 17.05 for the function
  52   ``_rte_eth_dev_callback_process``. In 17.05 the function will return an ``int``
  53   instead of ``void`` and a fourth parameter ``void *ret_param`` will be added.
  54
  55 * ethdev: for 17.05 it is planned to deprecate the following nine rte_eth_dev_*
  56   functions and move them into the ixgbe PMD:
  57
  58   ``rte_eth_dev_bypass_init``, ``rte_eth_dev_bypass_state_set``,
  59   ``rte_eth_dev_bypass_state_show``, ``rte_eth_dev_bypass_event_store``,
  60   ``rte_eth_dev_bypass_event_show``, ``rte_eth_dev_wd_timeout_store``,
  61   ``rte_eth_dev_bypass_wd_timeout_show``, ``rte_eth_dev_bypass_ver_show``,
  62   ``rte_eth_dev_bypass_wd_reset``.
  63
  64   The following fields will be removed from ``struct eth_dev_ops``:
  65
  66   ``bypass_init_t``, ``bypass_state_set_t``, ``bypass_state_show_t``,
  67   ``bypass_event_set_t``, ``bypass_event_show_t``, ``bypass_wd_timeout_set_t``,
  68   ``bypass_wd_timeout_show_t``, ``bypass_ver_show_t``, ``bypass_wd_reset_t``.
  69
  70   The functions will be renamed to the following, and moved to the ``ixgbe`` PMD:
  71
  72   ``rte_pmd_ixgbe_bypass_init``, ``rte_pmd_ixgbe_bypass_state_set``,
  73   ``rte_pmd_ixgbe_bypass_state_show``, ``rte_pmd_ixgbe_bypass_event_set``,
  74   ``rte_pmd_ixgbe_bypass_event_show``, ``rte_pmd_ixgbe_bypass_wd_timeout_set``,
  75   ``rte_pmd_ixgbe_bypass_wd_timeout_show``, ``rte_pmd_ixgbe_bypass_ver_show``,
  76   ``rte_pmd_ixgbe_bypass_wd_reset``.
  77
  78 * ABI changes are planned for 17.05 in the ``rte_mbuf`` structure: some fields
  79   may be reordered to facilitate the writing of ``data_off``, ``refcnt``, and
  80   ``nb_segs`` in one operation, because some platforms have an overhead if the
  81   store address is not naturally aligned. Other mbuf fields, such as the
  82   ``port`` field, may be moved or removed as part of this mbuf work. A
  83   ``timestamp`` will also be added.
  84
  85 * The mbuf flags PKT_RX_VLAN_PKT and PKT_RX_QINQ_PKT are deprecated and
  86   are respectively replaced by PKT_RX_VLAN_STRIPPED and
  87   PKT_RX_QINQ_STRIPPED, that are better described. The old flags and
  88   their behavior will be kept until 17.02 and will be removed in 17.05.
  89
  90 * mempool: The functions ``rte_mempool_count`` and ``rte_mempool_free_count``
  91   will be removed in 17.05.
  92   They are replaced by ``rte_mempool_avail_count`` and
  93   ``rte_mempool_in_use_count`` respectively.
  94
  95 * mempool: The functions for single/multi producer/consumer are deprecated
  96   and will be removed in 17.05.
  97   It is replaced by ``rte_mempool_generic_get/put`` functions.
  98
  99 * ethdev: the legacy filter API, including
 100   ``rte_eth_dev_filter_supported()``, ``rte_eth_dev_filter_ctrl()`` as well
 101   as filter types MACVLAN, ETHERTYPE, FLEXIBLE, SYN, NTUPLE, TUNNEL, FDIR,
 102   HASH and L2_TUNNEL, is superseded by the generic flow API (rte_flow) in
 103   PMDs that implement the latter.
 104   Target release for removal of the legacy API will be defined once most
 105   PMDs have switched to rte_flow.
 106
 107 * vhost: API/ABI changes are planned for 17.05, for making DPDK vhost library
 108   generic enough so that applications can build different vhost-user drivers
 109   (instead of vhost-user net only) on top of that.
 110   Specifically, ``virtio_net_device_ops`` will be renamed to ``vhost_device_ops``.
 111   Correspondingly, some API's parameter need be changed. Few more functions also
 112   need be reworked to let it be device aware. For example, different virtio device
 113   has different feature set, meaning functions like ``rte_vhost_feature_disable``
 114   need be changed. Last, file rte_virtio_net.h will be renamed to rte_vhost.h.
 115
 116 * kni: Remove :ref:`kni_vhost_backend-label` feature (KNI_VHOST) in 17.05 release.
 117   :doc:`Vhost Library </prog_guide/vhost_lib>` is currently preferred method for
 118   guest - host communication. Just for clarification, this is not to remove KNI
 119   or VHOST feature, but KNI_VHOST which is a KNI feature enabled via a compile
 120   time option, and disabled by default.
 121
 122 * ABI changes are planned for 17.05 in the ``rte_cryptodev_ops`` structure.
 123   A pointer to a rte_cryptodev_config structure will be added to the
 124   function prototype ``cryptodev_configure_t``, as a new parameter.
 125
 126 * distributor: library API will be changed to incorporate a burst-oriented
 127   API. This will include a change to ``rte_distributor_create``
 128   to specify which type of instance to create (single or burst), and
 129   additional calls for ``rte_distributor_poll_pkt_burst`` and
 130   ``rte_distributor_return_pkt_burst``, among others.
 131
 132 * The architecture TILE-Gx and the associated mpipe driver are not
 133   maintained and will be removed in 17.05.