X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Frel_notes%2Fdeprecation.rst;h=f6d28fe97fe91326d983d4bcc7c962ad5cce4abb;hb=d8cda718e13ce3b238489217832dc5ed28557206;hp=327fc2bf6639ebc25bcd929e7a6099b014b89272;hpb=c7970afddfb2f06fea587b69cba69006151716fc;p=dpdk.git diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index 327fc2bf66..d2dd302db6 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -8,85 +8,95 @@ API and ABI deprecation notices are to be posted here. Deprecation Notices ------------------- -* The ethdev hotplug API is going to be moved to EAL with a notification - mechanism added to crypto and ethdev libraries so that hotplug is now - available to both of them. This API will be stripped of the device arguments - so that it only cares about hotplugging. - -* Structures embodying pci and vdev devices are going to be reworked to - integrate new common rte_device / rte_driver objects (see - http://dpdk.org/ml/archives/dev/2016-January/031390.html). - ethdev and crypto libraries will then only handle those objects so that they - do not need to care about the kind of devices that are being used, making it - easier to add new buses later. - -* The EAL function pci_config_space_set is deprecated in release 16.04 - and will be removed from 16.07. - Macros CONFIG_RTE_PCI_CONFIG, CONFIG_RTE_PCI_EXTENDED_TAG and - CONFIG_RTE_PCI_MAX_READ_REQUEST_SIZE will be removed. - The /sys entries extended_tag and max_read_request_size created by igb_uio - will be removed. - -* ABI changes are planned for struct rte_pci_id, i.e., add new field ``class``. - This new added ``class`` field can be used to probe pci device by class - related info. This change should impact size of struct rte_pci_id and struct - rte_pci_device. The release 16.04 does not contain these ABI changes, but - release 16.07 will. - -* The following fields have been deprecated in rte_eth_stats: - ibadcrc, ibadlen, imcasts, fdirmatch, fdirmiss, - tx_pause_xon, rx_pause_xon, tx_pause_xoff, rx_pause_xoff - -* The xstats API and rte_eth_xstats struct will be changed to allow retrieval - of values without any string copies or parsing. - No backwards compatibility is planned, as it would require code duplication - in every PMD that supports xstats. - -* ABI changes are planned for adding four new flow types. This impacts - RTE_ETH_FLOW_MAX. The release 2.2 does not contain these ABI changes, - but release 2.3 will. [postponed] - -* ABI change is planned for the rte_mempool structure to allow mempool - cache support to be dynamic depending on the mempool being created - needing cache support. Saves about 1.5M of memory per rte_mempool structure - by removing the per lcore cache memory. Change will occur in DPDK 16.07 - release and will skip the define RTE_NEXT_ABI in DPDK 16.04 release. The - code affected is app/test/test_mempool.c and librte_mempool/rte_mempool.[ch]. - The rte_mempool.local_cache will be converted from an array to a pointer to - allow for dynamic allocation of the per lcore cache memory. - -* ABI will change for rte_mempool struct to move the cache-related fields - to the more appropriate rte_mempool_cache struct. The mempool API is - also changed to enable external cache management that is not tied to EAL - threads. Some mempool get and put calls are removed in favor of a more - compact API. The ones that remain are backwards compatible and use the - per-lcore default cache if available. This change targets release 16.07. - -* The rte_mempool struct will be changed in 16.07 to facilitate the new - external mempool manager functionality. - The ring element will be replaced with a more generic 'pool' opaque pointer - to allow new mempool handlers to use their own user-defined mempool - layout. Also newly added to rte_mempool is a handler index. - The existing API will be backward compatible, but there will be new API - functions added to facilitate the creation of mempools using an external - handler. The 16.07 release will contain these changes. - -* The rte_mempool allocation will be changed in 16.07: - allocation of large mempool in several virtual memory chunks, new API - to populate a mempool, new API to free a mempool, allocation in - anonymous mapping, drop of specific dom0 code. These changes will - induce a modification of the rte_mempool structure, plus a - modification of the API of rte_mempool_obj_iter(), implying a breakage - of the ABI. - -* ABI changes are planned for struct rte_port_source_params in order to - support PCAP file reading feature. The release 16.04 contains this ABI - change wrapped by RTE_NEXT_ABI macro. Release 16.07 will contain this - change, and no backwards compatibility is planned. - -* A librte_vhost public structures refactor is planned for DPDK 16.07 - that requires both ABI and API change. - The proposed refactor would expose DPDK vhost dev to applications as - a handle, like the way kernel exposes an fd to user for locating a - specific file, and to keep all major structures internally, so that - we are likely to be free from ABI violations in future. +* eal: DPDK runtime configuration file (located at + ``/var/run/._config``) will be moved. The new path will be as follows: + + - if DPDK is running as root, path will be set to + ``/var/run/dpdk//config`` + - if DPDK is not running as root and $XDG_RUNTIME_DIR is set, path will be set + to ``$XDG_RUNTIME_DIR/dpdk//config`` + - if DPDK is not running as root and $XDG_RUNTIME_DIR is not set, path will be + set to ``/tmp/dpdk//config`` + +* eal: both declaring and identifying devices will be streamlined in v18.05. + New functions will appear to query a specific port from buses, classes of + device and device drivers. Device declaration will be made coherent with the + new scheme of device identification. + As such, ``rte_devargs`` device representation will change. + + - removal of ``name`` and ``args`` fields. + - The enum ``rte_devtype`` was used to identify a bus and will disappear. + - Functions previously deprecated will change or disappear: + + + ``rte_eal_devargs_type_count`` + + ``rte_eal_devargs_parse`` will change its format and use. + +* pci: Several exposed functions are misnamed. + The following functions are deprecated starting from v17.11 and are replaced: + + - ``eal_parse_pci_BDF`` replaced by ``rte_pci_addr_parse`` + - ``eal_parse_pci_DomBDF`` replaced by ``rte_pci_addr_parse`` + - ``rte_eal_compare_pci_addr`` replaced by ``rte_pci_addr_cmp`` + +* eal: a new set of mbuf mempool ops name APIs for user, platform and best + mempool names have been defined in ``rte_mbuf`` in v18.02. The uses of + ``rte_eal_mbuf_default_mempool_ops`` shall be replaced by + ``rte_mbuf_best_mempool_ops``. + The following function is deprecated since 18.05, and will be removed + in 18.08: + + - ``rte_eal_mbuf_default_mempool_ops`` + +* mbuf: The opaque ``mbuf->hash.sched`` field will be updated to support generic + definition in line with the ethdev TM and MTR APIs. Currently, this field + is defined in librte_sched in a non-generic way. The new generic format + will contain: queue ID, traffic class, color. Field size will not change. + +* ethdev: a new Tx and Rx offload API was introduced on 17.11. + In the new API, offloads are divided into per-port and per-queue offloads. + Offloads are disabled by default and enabled per application request. + + In later releases the old offloading API will be deprecated, which will include: + - removal of ``ETH_TXQ_FLAGS_NO*`` flags. + - removal of ``txq_flags`` field from ``rte_eth_txconf`` struct. + - removal of the offloads bit-field from ``rte_eth_rxmode`` struct. + +* ethdev: the legacy filter API, including + ``rte_eth_dev_filter_supported()``, ``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. + +* pdump: As we changed to use generic IPC, some changes in APIs and structure + are expected in subsequent release. + + - ``rte_pdump_set_socket_dir`` will be removed; + - The parameter, ``path``, of ``rte_pdump_init`` will be removed; + - The enum ``rte_pdump_socktype`` will be removed. + +* cryptodev: The following changes will be made in the library + for 18.08: + + - Removal of ``sym`` structure in ``rte_cryptodev_info`` structure, + containing fields not relevant anymore since the session mempool + is not internal in the crypto device anymore. + - Replacement of ``pci_dev`` field with the more generic ``rte_device`` + structure. + - Functions ``rte_cryptodev_queue_pair_attach_sym_session()`` and + ``rte_cryptodev_queue_pair_dettach_sym_session()`` will be deprecated from + 18.05 and removed in 18.08, as there are no drivers doing anything useful + with them. + - Functions ``rte_cryptodev_queue_pair_start()`` and + ``rte_cryptodev_queue_pair_stop()`` will be deprecated from 18.05 + and removed in 18.08, as there are no drivers doing anything useful + with them. + - Some feature flags such as ``RTE_CRYPTODEV_FF_MBUF_SCATTER_GATHER`` are ambiguous, + so some will be replaced by more explicit flags. + - Function ``rte_cryptodev_get_header_session_size()`` will be deprecated + in 18.05, and it gets replaced with ``rte_cryptodev_sym_get_header_session_size()``. + It will be removed in 18.08. + - Function ``rte_cryptodev_get_private_session_size()`` will be deprecated + in 18.05, and it gets replaced with ``rte_cryptodev_sym_get_private_session_size()``. + It will be removed in 18.08.