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 * 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.
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:
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_``.
29 * pci: Several exposed functions are misnamed.
30 The following functions are deprecated starting from v17.11 and are replaced:
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``
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.
41 * eal: a new set of mbuf mempool ops name APIs for user, platform and best
42 mempool names have been defined in ``rte_mbuf`` in v18.02. The uses of
43 ``rte_eal_mbuf_default_mempool_ops`` shall be replaced by
44 ``rte_mbuf_best_mempool_ops``.
45 The following function is now redundant and it is target to be deprecated
48 - ``rte_eal_mbuf_default_mempool_ops``
50 * mempool: several API and ABI changes are planned in v18.05.
51 The following functions, introduced for Xen, which is not supported
52 anymore since v17.11, are hard to use, not used anywhere else in DPDK.
53 Therefore they will be deprecated in v18.05 and removed in v18.08:
55 - ``rte_mempool_xmem_create``
56 - ``rte_mempool_xmem_size``
57 - ``rte_mempool_xmem_usage``
59 The following changes are planned:
61 - removal of ``get_capabilities`` mempool ops and related flags.
62 - substitute ``register_memory_area`` with ``populate`` ops.
63 - addition of new ops to customize required memory chunk calculation,
64 customize objects population and allocate contiguous
65 block of objects if underlying driver supports it.
67 * mbuf: The opaque ``mbuf->hash.sched`` field will be updated to support generic
68 definition in line with the ethdev TM and MTR APIs. Currently, this field
69 is defined in librte_sched in a non-generic way. The new generic format
70 will contain: queue ID, traffic class, color. Field size will not change.
72 * ethdev: a new Tx and Rx offload API was introduced on 17.11.
73 In the new API, offloads are divided into per-port and per-queue offloads.
74 Offloads are disabled by default and enabled per application request.
76 The old ethdev - drivers offload interface will be deprecated on 18.05.
78 - removal of the conversion in ethdev from new offloading API to old API for drivers.
80 In later releases the old offloading API will be deprecated, which will include:
81 - removal of ``ETH_TXQ_FLAGS_NO*`` flags.
82 - removal of ``txq_flags`` field from ``rte_eth_txconf`` struct.
83 - removal of the offloads bit-field from ``rte_eth_rxmode`` struct.
85 * ethdev: the legacy filter API, including
86 ``rte_eth_dev_filter_supported()``, ``rte_eth_dev_filter_ctrl()`` as well
87 as filter types MACVLAN, ETHERTYPE, FLEXIBLE, SYN, NTUPLE, TUNNEL, FDIR,
88 HASH and L2_TUNNEL, is superseded by the generic flow API (rte_flow) in
89 PMDs that implement the latter.
90 Target release for removal of the legacy API will be defined once most
91 PMDs have switched to rte_flow.
93 * ethdev: A new rss level field planned in 18.05.
94 The new API add rss_level field to ``rte_eth_rss_conf`` to enable a choice
95 of RSS hash calculation on outer or inner header of tunneled packet.
97 * ethdev: A work is being planned for 18.05 to expose VF port representors
98 as a mean to perform control and data path operation on the different VFs.
99 As VF representor is an ethdev port, new fields are needed in order to map
100 between the VF representor and the VF or the parent PF. Those new fields
101 are to be included in ``rte_eth_dev_info`` struct.
103 * i40e: The default flexible payload configuration which extracts the first 16
104 bytes of the payload for RSS will be deprecated starting from 18.02. If
105 required the previous behavior can be configured using existing flow
106 director APIs. There is no ABI/API break. This change will just remove a
107 global configuration setting and require explicit configuration.
109 * ring: The alignment constraints on the ring structure will be relaxed
110 to one cache line instead of two, and an empty cache line padding will
111 be added between the producer and consumer structures. The size of the
112 structure and the offset of the fields will remain the same on
113 platforms with 64B cache line, but will change on other platforms.