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 Intel IPsec Multi-Buffer version will be bumped 173 to a minimum version of v1.4. 174 This will effect the KASUMI, SNOW3G, ZUC, AESNI GCM, AESNI MB and CHACHAPOLY 175 SW PMDs. 176 177* eventdev: The single-event (non-burst) enqueue and dequeue operations, 178 used by static inline burst enqueue and dequeue functions in ``rte_eventdev.h``, 179 will be removed in DPDK 23.11. 180 This simplification includes changing the layout and potentially also 181 the size of the public ``rte_event_fp_ops`` struct, breaking the ABI. 182 Since these functions are not called directly by the application, 183 the API remains unaffected. 184 185* pipeline: The pipeline library legacy API (functions rte_pipeline_*) 186 will be deprecated and subsequently removed in DPDK 24.11 release. 187 Before this, the new pipeline library API (functions rte_swx_pipeline_*) 188 will gradually transition from experimental to stable status. 189 190* table: The table library legacy API (functions rte_table_*) 191 will be deprecated and subsequently removed in DPDK 24.11 release. 192 Before this, the new table library API (functions rte_swx_table_*) 193 will gradually transition from experimental to stable status. 194 195* port: The port library legacy API (functions rte_port_*) 196 will be deprecated and subsequently removed in DPDK 24.11 release. 197 Before this, the new port library API (functions rte_swx_port_*) 198 will gradually transition from experimental to stable status. 199 200* graph: The graph library data structures will be modified 201 to support node specific errors. 202 The structures ``rte_node``, ``rte_node_register`` 203 and ``rte_graph_cluster_node_stats`` will be extended 204 to include node error counters and error description. 205