12. ABI and API Deprecation
See the guidelines document for details of the ABI policy. API and ABI deprecation notices are to be posted here.
12.1. Deprecation Notices
ring: Changes are planned to rte_ring APIs in release 17.05. Proposed changes include:
- Removing build time options for the ring: CONFIG_RTE_RING_SPLIT_PROD_CONS CONFIG_RTE_RING_PAUSE_REP_COUNT
- Adding an additional parameter to enqueue functions to return the amount of free space in the ring
- Adding an additional parameter to dequeue functions to return the number of remaining elements in the ring
- Removing direct support for watermarks in the rings, since the additional return value from the enqueue function makes it unneeded
- Adjusting the return values of the bulk() enq/deq functions to make them consistent with the burst() equivalents. [Note, parameter to these functions are changing too, per points above, so compiler will flag them as needing update in legacy code]
- Updates to some library functions e.g. rte_ring_get_memsize() to allow for variably-sized ring elements.
igb_uio: iomem mapping and sysfs files created for iomem and ioport in igb_uio will be removed, because we are able to detect these from what Linux has exposed, like the way we have done with uio-pci-generic. This change targets release 17.05.
vfio: Some functions are planned to be exported outside librte_eal in 17.05. VFIO APIs like
vfio_get_group_fdcan be used by subsystem other than EAL/PCI. For that, these need to be exported symbols. Such APIs are planned to be renamed according to
rte_*naming convention and exported from librte_eal.
The PCI and VDEV subsystems will be converted as drivers of the new bus model. It will imply some EAL API changes in 17.05.
eth_driveris planned to be removed in 17.05. This currently serves as a placeholder for PMDs to register themselves. Changes for
rte_buswill provide a way to handle device initialization currently being done in
rte_pci_driveris planned to be removed from
ethdev: An API change is planned for 17.05 for the function
_rte_eth_dev_callback_process. In 17.05 the function will return an
voidand a fourth parameter
void *ret_paramwill be added.
ethdev: for 17.05 it is planned to deprecate the following nine rte_eth_dev_* functions and move them into the ixgbe PMD:
The following fields will be removed from
The functions will be renamed to the following, and moved to the
ABI changes are planned for 17.05 in the
rte_mbufstructure: some fields may be reordered to facilitate the writing of
nb_segsin one operation, because some platforms have an overhead if the store address is not naturally aligned. Other mbuf fields, such as the
portfield, may be moved or removed as part of this mbuf work. A
timestampwill also be added.
The mbuf flags PKT_RX_VLAN_PKT and PKT_RX_QINQ_PKT are deprecated and are respectively replaced by PKT_RX_VLAN_STRIPPED and PKT_RX_QINQ_STRIPPED, that are better described. The old flags and their behavior will be kept until 17.02 and will be removed in 17.05.
mempool: The functions
rte_mempool_free_countwill be removed in 17.05. They are replaced by
mempool: The functions for single/multi producer/consumer are deprecated and will be removed in 17.05. It is replaced by
ethdev: the legacy filter API, including
rte_eth_dev_filter_ctrl()as well as filter types MACVLAN, ETHERTYPE, FLEXIBLE, SYN, NTUPLE, TUNNEL, FDIR, HASH and L2_TUNNEL, is superseded by the generic flow API (rte_flow) in PMDs that implement the latter. Target release for removal of the legacy API will be defined once most PMDs have switched to rte_flow.
vhost: API/ABI changes are planned for 17.05, for making DPDK vhost library generic enough so that applications can build different vhost-user drivers (instead of vhost-user net only) on top of that. Specifically,
virtio_net_device_opswill be renamed to
vhost_device_ops. Correspondingly, some API’s parameter need be changed. Few more functions also need be reworked to let it be device aware. For example, different virtio device has different feature set, meaning functions like
rte_vhost_feature_disableneed be changed. Last, file rte_virtio_net.h will be renamed to rte_vhost.h.
kni: Remove KNI Working as a Kernel vHost Backend feature (KNI_VHOST) in 17.05 release. Vhost Library is currently preferred method for guest - host communication. Just for clarification, this is not to remove KNI or VHOST feature, but KNI_VHOST which is a KNI feature enabled via a compile time option, and disabled by default.
ABI changes are planned for 17.05 in the
rte_cryptodev_opsstructure. A pointer to a rte_cryptodev_config structure will be added to the function prototype
cryptodev_configure_t, as a new parameter.
cryptodev: A new parameter
max_nb_sessions_per_qpwill be added to
rte_cryptodev_info.sym. Some drivers may support limited number of sessions per queue_pair. With this new parameter application will know how many sessions can be mapped to each queue_pair of a device.
distributor: library API will be changed to incorporate a burst-oriented API. This will include a change to
rte_distributor_createto specify which type of instance to create (single or burst), and additional calls for
rte_distributor_return_pkt_burst, among others.
The architecture TILE-Gx and the associated mpipe driver are not maintained and will be removed in 17.05.