deprecation.rst revision 97f17497
1ABI and API Deprecation
2=======================
3
4See the :doc:`guidelines document for details of the ABI policy </contributing/versioning>`.
5API and ABI deprecation notices are to be posted here.
6
7
8Deprecation Notices
9-------------------
10
11* The ethdev hotplug API is going to be moved to EAL with a notification
12  mechanism added to crypto and ethdev libraries so that hotplug is now
13  available to both of them. This API will be stripped of the device arguments
14  so that it only cares about hotplugging.
15
16* Structures embodying pci and vdev devices are going to be reworked to
17  integrate new common rte_device / rte_driver objects (see
18  http://dpdk.org/ml/archives/dev/2016-January/031390.html).
19  ethdev and crypto libraries will then only handle those objects so that they
20  do not need to care about the kind of devices that are being used, making it
21  easier to add new buses later.
22
23* The EAL function pci_config_space_set is deprecated in release 16.04
24  and will be removed from 16.07.
25  Macros CONFIG_RTE_PCI_CONFIG, CONFIG_RTE_PCI_EXTENDED_TAG and
26  CONFIG_RTE_PCI_MAX_READ_REQUEST_SIZE will be removed.
27  The /sys entries extended_tag and max_read_request_size created by igb_uio
28  will be removed.
29
30* ABI changes are planned for struct rte_pci_id, i.e., add new field ``class``.
31  This new added ``class`` field can be used to probe pci device by class
32  related info. This change should impact size of struct rte_pci_id and struct
33  rte_pci_device. The release 16.04 does not contain these ABI changes, but
34  release 16.07 will.
35
36* The following fields have been deprecated in rte_eth_stats:
37  ibadcrc, ibadlen, imcasts, fdirmatch, fdirmiss,
38  tx_pause_xon, rx_pause_xon, tx_pause_xoff, rx_pause_xoff
39
40* The xstats API and rte_eth_xstats struct will be changed to allow retrieval
41  of values without any string copies or parsing.
42  No backwards compatibility is planned, as it would require code duplication
43  in every PMD that supports xstats.
44
45* ABI changes are planned for adding four new flow types. This impacts
46  RTE_ETH_FLOW_MAX. The release 2.2 does not contain these ABI changes,
47  but release 2.3 will. [postponed]
48
49* ABI change is planned for the rte_mempool structure to allow mempool
50  cache support to be dynamic depending on the mempool being created
51  needing cache support. Saves about 1.5M of memory per rte_mempool structure
52  by removing the per lcore cache memory. Change will occur in DPDK 16.07
53  release and will skip the define RTE_NEXT_ABI in DPDK 16.04 release. The
54  code affected is app/test/test_mempool.c and librte_mempool/rte_mempool.[ch].
55  The rte_mempool.local_cache will be converted from an array to a pointer to
56  allow for dynamic allocation of the per lcore cache memory.
57
58* ABI will change for rte_mempool struct to move the cache-related fields
59  to the more appropriate rte_mempool_cache struct. The mempool API is
60  also changed to enable external cache management that is not tied to EAL
61  threads. Some mempool get and put calls are removed in favor of a more
62  compact API. The ones that remain are backwards compatible and use the
63  per-lcore default cache if available. This change targets release 16.07.
64
65* The rte_mempool struct will be changed in 16.07 to facilitate the new
66  external mempool manager functionality.
67  The ring element will be replaced with a more generic 'pool' opaque pointer
68  to allow new mempool handlers to use their own user-defined mempool
69  layout. Also newly added to rte_mempool is a handler index.
70  The existing API will be backward compatible, but there will be new API
71  functions added to facilitate the creation of mempools using an external
72  handler. The 16.07 release will contain these changes.
73
74* The rte_mempool allocation will be changed in 16.07:
75  allocation of large mempool in several virtual memory chunks, new API
76  to populate a mempool, new API to free a mempool, allocation in
77  anonymous mapping, drop of specific dom0 code. These changes will
78  induce a modification of the rte_mempool structure, plus a
79  modification of the API of rte_mempool_obj_iter(), implying a breakage
80  of the ABI.
81
82* ABI changes are planned for struct rte_port_source_params in order to
83  support PCAP file reading feature. The release 16.04 contains this ABI
84  change wrapped by RTE_NEXT_ABI macro. Release 16.07 will contain this
85  change, and no backwards compatibility is planned.
86
87* A librte_vhost public structures refactor is planned for DPDK 16.07
88  that requires both ABI and API change.
89  The proposed refactor would expose DPDK vhost dev to applications as
90  a handle, like the way kernel exposes an fd to user for locating a
91  specific file, and to keep all major structures internally, so that
92  we are likely to be free from ABI violations in future.
93