1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright 2018 The DPDK contributors 3 4ABI and API Deprecation 5======================= 6 7See the guidelines document for details of the :doc:`ABI policy 8<../contributing/abi_policy>`. 9 10With DPDK 23.11, there will be a new major ABI version: 24. 11This means that during the development of 23.11, 12new items may be added to structs or enums, 13even if those additions involve an ABI compatibility breakage. 14 15Other API and ABI deprecation notices are to be posted below. 16 17Deprecation Notices 18------------------- 19 20* build: The ``enable_kmods`` option is deprecated and will be removed in a future release. 21 Setting/clearing the option has no impact on the build. 22 Instead, kernel modules will be always built for OS's where out-of-tree kernel modules 23 are required for DPDK operation. 24 Currently, this means that modules will only be built for FreeBSD. 25 No modules are shipped with DPDK for either Linux or Windows. 26 27* kvargs: The function ``rte_kvargs_process`` will get a new parameter 28 for returning key match count. It will ease handling of no-match case. 29 30* telemetry: The functions ``rte_tel_data_add_array_u64`` and ``rte_tel_data_add_dict_u64``, 31 used by telemetry callbacks for adding unsigned integer values to be returned to the user, 32 are renamed to ``rte_tel_data_add_array_uint`` and ``rte_tel_data_add_dict_uint`` respectively. 33 As such, the old function names are deprecated and will be removed in a future release. 34 35* rte_atomicNN_xxx: These APIs do not take memory order parameter. This does 36 not allow for writing optimized code for all the CPU architectures supported 37 in DPDK. DPDK has adopted the atomic operations from 38 https://gcc.gnu.org/onlinedocs/gcc/_005f_005fatomic-Builtins.html. These 39 operations must be used for patches that need to be merged in 20.08 onwards. 40 This change will not introduce any performance degradation. 41 42* rte_smp_*mb: These APIs provide full barrier functionality. However, many 43 use cases do not require full barriers. To support such use cases, DPDK has 44 adopted atomic operations from 45 https://gcc.gnu.org/onlinedocs/gcc/_005f_005fatomic-Builtins.html. These 46 operations and a new wrapper ``rte_atomic_thread_fence`` instead of 47 ``__atomic_thread_fence`` must be used for patches that need to be merged in 48 20.08 onwards. This change will not introduce any performance degradation. 49 50* lib: will fix extending some enum/define breaking the ABI. There are multiple 51 samples in DPDK that enum/define terminated with a ``.*MAX.*`` value which is 52 used by iterators, and arrays holding these values are sized with this 53 ``.*MAX.*`` value. So extending this enum/define increases the ``.*MAX.*`` 54 value which increases the size of the array and depending on how/where the 55 array is used this may break the ABI. 56 ``RTE_ETH_FLOW_MAX`` is one sample of the mentioned case, adding a new flow 57 type will break the ABI because of ``flex_mask[RTE_ETH_FLOW_MAX]`` array 58 usage in following public struct hierarchy: 59 ``rte_eth_fdir_flex_conf -> rte_eth_fdir_conf -> rte_eth_conf (in the middle)``. 60 Need to identify this kind of usages and fix in 20.11, otherwise this blocks 61 us extending existing enum/define. 62 One solution can be using a fixed size array instead of ``.*MAX.*`` value. 63 64* net: A new IPv6 address structure will be introduced in DPDK 24.11. 65 It will replace all ad-hoc ``uint8_t[16]`` arrays in all public APIs and structures. 66 The following libraries and symbols are expected to be affected: 67 68 ethdev 69 - ``struct rte_flow_item_icmp6_nd_ns`` 70 - ``struct rte_flow_item_icmp6_nd_na`` 71 - ``struct rte_flow_action_set_ipv6`` 72 - ``struct rte_flow_tunnel`` 73 fib 74 - ``rte_fib6_add()`` 75 - ``rte_fib6_delete()`` 76 - ``rte_fib6_lookup_bulk()`` 77 gro 78 - ``struct tcp6_flow_key`` 79 hash 80 - ``struct rte_ipv6_tuple`` 81 ipsec 82 - ``struct rte_ipsec_sadv6_key`` 83 lpm 84 - ``rte_lpm6_add()`` 85 - ``rte_lpm6_is_rule_present()`` 86 - ``rte_lpm6_delete()`` 87 - ``rte_lpm6_delete_bulk_func()`` 88 - ``rte_lpm6_lookup()`` 89 - ``rte_lpm6_lookup_bulk_func()`` 90 net 91 - ``struct rte_ipv6_hdr`` 92 node 93 - ``rte_node_ip6_route_add()`` 94 pipeline 95 - ``struct rte_table_action_ipv6_header`` 96 rib 97 - ``rte_rib6_lookup()`` 98 - ``rte_rib6_lookup_exact()`` 99 - ``rte_rib6_get_nxt()`` 100 - ``rte_rib6_insert()`` 101 - ``rte_rib6_remove()`` 102 - ``rte_rib6_get_ip()`` 103 table 104 - ``struct rte_table_lpm_ipv6_key`` 105 106* net, ethdev: The flow item ``RTE_FLOW_ITEM_TYPE_VXLAN_GPE`` 107 is replaced with ``RTE_FLOW_ITEM_TYPE_VXLAN``. 108 The struct ``rte_flow_item_vxlan_gpe`` and its mask ``rte_flow_item_vxlan_gpe_mask`` 109 are replaced with ``rte_flow_item_vxlan`` and ``rte_flow_item_vxlan_mask``. 110 The flow item ``RTE_FLOW_ITEM_TYPE_VXLAN_GPE``, 111 the structs ``rte_flow_item_vxlan_gpe``, ``rte_flow_item_vxlan_gpe_mask``, 112 and the header struct ``rte_vxlan_gpe_hdr`` with the macro ``RTE_ETHER_VXLAN_GPE_HLEN`` 113 will be removed in DPDK 25.11. 114 115* ethdev: The flow API matching pattern structures, ``struct rte_flow_item_*``, 116 should start with relevant protocol header structure from lib/net/. 117 The individual protocol header fields and the protocol header struct 118 may be kept together in a union as a first migration step. 119 In future (target is DPDK 23.11), the protocol header fields will be cleaned 120 and only protocol header struct will remain. 121 122 These items are not compliant (not including struct from lib/net/): 123 124 - ``rte_flow_item_ah`` 125 - ``rte_flow_item_e_tag`` 126 - ``rte_flow_item_geneve`` 127 - ``rte_flow_item_geneve_opt`` 128 - ``rte_flow_item_gre`` 129 - ``rte_flow_item_icmp6`` 130 - ``rte_flow_item_icmp6_nd_na`` 131 - ``rte_flow_item_icmp6_nd_ns`` 132 - ``rte_flow_item_icmp6_nd_opt`` 133 - ``rte_flow_item_icmp6_nd_opt_sla_eth`` 134 - ``rte_flow_item_icmp6_nd_opt_tla_eth`` 135 - ``rte_flow_item_igmp`` 136 - ``rte_flow_item_ipv6_ext`` 137 - ``rte_flow_item_l2tpv3oip`` 138 - ``rte_flow_item_mpls`` 139 - ``rte_flow_item_nsh`` 140 - ``rte_flow_item_nvgre`` 141 - ``rte_flow_item_pfcp`` 142 - ``rte_flow_item_pppoe`` 143 - ``rte_flow_item_pppoe_proto_id`` 144 145* ethdev: Queue specific stats fields will be removed from ``struct rte_eth_stats``. 146 Mentioned fields are: ``q_ipackets``, ``q_opackets``, ``q_ibytes``, ``q_obytes``, 147 ``q_errors``. 148 Instead queue stats will be received via xstats API. Current method support 149 will be limited to maximum 256 queues. 150 Also compile time flag ``RTE_ETHDEV_QUEUE_STAT_CNTRS`` will be removed. 151 152* ethdev: Flow actions ``PF`` and ``VF`` have been deprecated since DPDK 21.11 153 and are yet to be removed. That still has not happened because there are net 154 drivers which support combined use of either action ``PF`` or action ``VF`` 155 with action ``QUEUE``, namely, i40e, ixgbe and txgbe (L2 tunnel rule). 156 It is unclear whether it is acceptable to just drop support for 157 such a complex use case, so maintainers of the said drivers 158 should take a closer look at this and provide assistance. 159 160* ethdev: Actions ``OF_DEC_NW_TTL``, ``SET_IPV4_SRC``, ``SET_IPV4_DST``, 161 ``SET_IPV6_SRC``, ``SET_IPV6_DST``, ``SET_TP_SRC``, ``SET_TP_DST``, 162 ``DEC_TTL``, ``SET_TTL``, ``SET_MAC_SRC``, ``SET_MAC_DST``, ``INC_TCP_SEQ``, 163 ``DEC_TCP_SEQ``, ``INC_TCP_ACK``, ``DEC_TCP_ACK``, ``SET_IPV4_DSCP``, 164 ``SET_IPV6_DSCP``, ``SET_TAG``, ``SET_META`` are marked as legacy and 165 superseded by the generic ``RTE_FLOW_ACTION_TYPE_MODIFY_FIELD``. 166 The legacy actions should be removed 167 once ``MODIFY_FIELD`` alternative is implemented in drivers. 168 169* fib: A new flag field will be introduced in ``rte_fib_conf`` structure 170 in DPDK 24.11. This field will be used to pass extra configuration settings. 171 172* cryptodev: The function ``rte_cryptodev_cb_fn`` will be updated 173 to have another parameter ``qp_id`` to return the queue pair ID 174 which got error interrupt to the application, 175 so that application can reset that particular queue pair. 176 177* cryptodev: The Intel IPsec Multi-Buffer version will be bumped 178 to a minimum version of v1.4. 179 This will effect the KASUMI, SNOW3G, ZUC, AESNI GCM, AESNI MB and CHACHAPOLY 180 SW PMDs. 181 182* ipsec: The IPsec library is updated to support sequence number provided 183 by application. To allow the same, two new API functions are being introduced: 184 ``rte_ipsec_pkt_crypto_sqn_assign`` and ``rte_ipsec_pkt_crypto_xprepare``. 185 It separates the sequence number update functionality 186 from the existing ``rte_ipsec_pkt_crypto_prepare`` function. 187 Corresponding configure structure changes are being made for the new API. 188 Additionally a new flag ``RTE_IPSEC_SAFLAG_SQN_ASSIGN_DISABLE`` 189 is introduced to disable sequence number assignment in IPsec library. 190 191* eventdev: The single-event (non-burst) enqueue and dequeue operations, 192 used by static inline burst enqueue and dequeue functions in ``rte_eventdev.h``, 193 will be removed in DPDK 23.11. 194 This simplification includes changing the layout and potentially also 195 the size of the public ``rte_event_fp_ops`` struct, breaking the ABI. 196 Since these functions are not called directly by the application, 197 the API remains unaffected. 198 199* pipeline: The pipeline library legacy API (functions rte_pipeline_*) 200 will be deprecated and subsequently removed in DPDK 24.11 release. 201 Before this, the new pipeline library API (functions rte_swx_pipeline_*) 202 will gradually transition from experimental to stable status. 203 204* table: The table library legacy API (functions rte_table_*) 205 will be deprecated and subsequently removed in DPDK 24.11 release. 206 Before this, the new table library API (functions rte_swx_table_*) 207 will gradually transition from experimental to stable status. 208 209* port: The port library legacy API (functions rte_port_*) 210 will be deprecated and subsequently removed in DPDK 24.11 release. 211 Before this, the new port library API (functions rte_swx_port_*) 212 will gradually transition from experimental to stable status. 213 214* graph: The graph library data structures will be modified 215 to support node specific errors. 216 The structures ``rte_node``, ``rte_node_register`` 217 and ``rte_graph_cluster_node_stats`` will be extended 218 to include node error counters and error description. 219