1 ABI and API Deprecation
2 =======================
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.
11 * ring: Changes are planned to rte_ring APIs in release 17.05. Proposed
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
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.
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.
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.
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.
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.
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.
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:
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``.
64 The following fields will be removed from ``struct eth_dev_ops``:
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``.
70 The functions will be renamed to the following, and moved to the ``ixgbe`` PMD:
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``.
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.
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.
90 * ethdev: the legacy filter API, including
91 ``rte_eth_dev_filter_supported()``, ``rte_eth_dev_filter_ctrl()`` as well
92 as filter types MACVLAN, ETHERTYPE, FLEXIBLE, SYN, NTUPLE, TUNNEL, FDIR,
93 HASH and L2_TUNNEL, is superseded by the generic flow API (rte_flow) in
94 PMDs that implement the latter.
95 Target release for removal of the legacy API will be defined once most
96 PMDs have switched to rte_flow.
98 * vhost: API/ABI changes are planned for 17.05, for making DPDK vhost library
99 generic enough so that applications can build different vhost-user drivers
100 (instead of vhost-user net only) on top of that.
101 Specifically, ``virtio_net_device_ops`` will be renamed to ``vhost_device_ops``.
102 Correspondingly, some API's parameter need be changed. Few more functions also
103 need be reworked to let it be device aware. For example, different virtio device
104 has different feature set, meaning functions like ``rte_vhost_feature_disable``
105 need be changed. Last, file rte_virtio_net.h will be renamed to rte_vhost.h.
107 * ABI changes are planned for 17.05 in the ``rte_cryptodev_ops`` structure.
108 A pointer to a rte_cryptodev_config structure will be added to the
109 function prototype ``cryptodev_configure_t``, as a new parameter.
111 * cryptodev: A new parameter ``max_nb_sessions_per_qp`` will be added to
112 ``rte_cryptodev_info.sym``. Some drivers may support limited number of
113 sessions per queue_pair. With this new parameter application will know
114 how many sessions can be mapped to each queue_pair of a device.
116 * distributor: library API will be changed to incorporate a burst-oriented
117 API. This will include a change to ``rte_distributor_create``
118 to specify which type of instance to create (single or burst), and
119 additional calls for ``rte_distributor_poll_pkt_burst`` and
120 ``rte_distributor_return_pkt_burst``, among others.