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: the following functions are deprecated starting from 17.05 and will
  12   be removed in 17.08:
  13
  14   - ``rte_set_log_level``, replaced by ``rte_log_set_global_level``
  15   - ``rte_get_log_level``, replaced by ``rte_log_get_global_level``
  16   - ``rte_set_log_type``, replaced by ``rte_log_set_level``
  17   - ``rte_get_log_type``, replaced by ``rte_log_get_level``
  18
  19 * devargs: An ABI change is planned for 17.08 for the structure ``rte_devargs``.
  20   The current version is dependent on bus-specific device identifier, which will
  21   be made generic and abstracted, in order to make the EAL bus-agnostic.
  22
  23   Accompanying this evolution, device command line parameters will thus support
  24   explicit bus definition in a device declaration.
  25
  26 * igb_uio: iomem mapping and sysfs files created for iomem and ioport in
  27   igb_uio will be removed, because we are able to detect these from what Linux
  28   has exposed, like the way we have done with uio-pci-generic. This change
  29   targets release 17.05.
  30
  31 * The VDEV subsystem will be converted as driver of the new bus model.
  32   It may imply some EAL API changes in 17.08.
  33
  34 * The struct ``rte_pci_driver`` is planned to be removed from
  35   ``rte_cryptodev_driver`` and ``rte_eventdev_driver`` in 17.08.
  36
  37 * ethdev: An API change is planned for 17.08 for the function
  38   ``_rte_eth_dev_callback_process``. In 17.08 the function will return an ``int``
  39   instead of ``void`` and a fourth parameter ``void *ret_param`` will be added.
  40
  41 * ethdev: for 17.08 it is planned to deprecate the following nine rte_eth_dev_*
  42   functions and move them into the ixgbe PMD:
  43
  44   ``rte_eth_dev_bypass_init``, ``rte_eth_dev_bypass_state_set``,
  45   ``rte_eth_dev_bypass_state_show``, ``rte_eth_dev_bypass_event_store``,
  46   ``rte_eth_dev_bypass_event_show``, ``rte_eth_dev_wd_timeout_store``,
  47   ``rte_eth_dev_bypass_wd_timeout_show``, ``rte_eth_dev_bypass_ver_show``,
  48   ``rte_eth_dev_bypass_wd_reset``.
  49
  50   The following fields will be removed from ``struct eth_dev_ops``:
  51
  52   ``bypass_init_t``, ``bypass_state_set_t``, ``bypass_state_show_t``,
  53   ``bypass_event_set_t``, ``bypass_event_show_t``, ``bypass_wd_timeout_set_t``,
  54   ``bypass_wd_timeout_show_t``, ``bypass_ver_show_t``, ``bypass_wd_reset_t``.
  55
  56   The functions will be renamed to the following, and moved to the ``ixgbe`` PMD:
  57
  58   ``rte_pmd_ixgbe_bypass_init``, ``rte_pmd_ixgbe_bypass_state_set``,
  59   ``rte_pmd_ixgbe_bypass_state_show``, ``rte_pmd_ixgbe_bypass_event_set``,
  60   ``rte_pmd_ixgbe_bypass_event_show``, ``rte_pmd_ixgbe_bypass_wd_timeout_set``,
  61   ``rte_pmd_ixgbe_bypass_wd_timeout_show``, ``rte_pmd_ixgbe_bypass_ver_show``,
  62   ``rte_pmd_ixgbe_bypass_wd_reset``.
  63
  64 * The mbuf flags PKT_RX_VLAN_PKT and PKT_RX_QINQ_PKT are deprecated and
  65   are respectively replaced by PKT_RX_VLAN_STRIPPED and
  66   PKT_RX_QINQ_STRIPPED, that are better described. The old flags and
  67   their behavior will be kept until 17.05 and will be removed in 17.08.
  68
  69 * ethdev: Tx offloads will no longer be enabled by default in 17.08.
  70   Instead, the ``rte_eth_txmode`` structure will be extended with
  71   bit field to enable each Tx offload.
  72   Besides of making the Rx/Tx configuration API more consistent for the
  73   application, PMDs will be able to provide a better out of the box performance.
  74   As part of the work, ``ETH_TXQ_FLAGS_NO*`` will be superseded as well.
  75
  76 * ethdev: the legacy filter API, including
  77   ``rte_eth_dev_filter_supported()``, ``rte_eth_dev_filter_ctrl()`` as well
  78   as filter types MACVLAN, ETHERTYPE, FLEXIBLE, SYN, NTUPLE, TUNNEL, FDIR,
  79   HASH and L2_TUNNEL, is superseded by the generic flow API (rte_flow) in
  80   PMDs that implement the latter.
  81   Target release for removal of the legacy API will be defined once most
  82   PMDs have switched to rte_flow.
  83
  84 * cryptodev: All PMD names definitions will be moved to the individual PMDs
  85   in 17.08.
  86
  87 * cryptodev: The following changes will be done in in 17.08:
  88
  89   - the device type enumeration ``rte_cryptodev_type`` will be removed
  90   - the following structures will be changed: ``rte_cryptodev_session``,
  91     ``rte_cryptodev_sym_session``, ``rte_cryptodev_info``, ``rte_cryptodev``
  92   - the function ``rte_cryptodev_count_devtype`` will be replaced by
  93     ``rte_cryptodev_device_count_by_driver``
  94
  95 * cryptodev: API changes are planned for 17.08 for the sessions management
  96   to make it agnostic to the underlying devices, removing coupling with
  97   crypto PMDs, so a single session can be used on multiple devices.
  98
  99   - ``struct rte_cryptodev_sym_session``, dev_id, dev_type will be removed,
 100     _private field changed to the indirect array of private data pointers of
 101     all supported devices
 102
 103   An API of followed functions will be changed to allow operate on multiple
 104   devices with one session:
 105
 106   - ``rte_cryptodev_sym_session_create``
 107   - ``rte_cryptodev_sym_session_free``
 108   - ``rte_cryptodev_sym_session_pool_create``
 109
 110   While dev_id will not be stored in the ``struct rte_cryptodev_sym_session``,
 111   directly, the change of followed API is required:
 112
 113   - ``rte_cryptodev_queue_pair_attach_sym_session``
 114   - ``rte_cryptodev_queue_pair_detach_sym_session``
 115
 116 * cryptodev: the structures ``rte_crypto_op``, ``rte_crypto_sym_op``
 117   and ``rte_crypto_sym_xform`` will be restructured in 17.08,
 118   for correctness and improvement.
 119
 120 * crypto/scheduler: the following two functions are deprecated starting
 121   from 17.05 and will be removed in 17.08:
 122
 123   - ``rte_crpytodev_scheduler_mode_get``, replaced by ``rte_cryptodev_scheduler_mode_get``
 124   - ``rte_crpytodev_scheduler_mode_set``, replaced by ``rte_cryptodev_scheduler_mode_set``
 125
 126 * librte_table: The ``key_mask`` parameter will be added to all the hash tables
 127   that currently do not have it, as well as to the hash compute function prototype.
 128   The non-"do-sig" versions of the hash tables will be removed
 129   (including the ``signature_offset`` parameter)
 130   and the "do-sig" versions renamed accordingly.