net/iavf: deprecate i40evf PMD
[dpdk.git] / doc / guides / rel_notes / deprecation.rst
index a7d5c1b..9584d6b 100644 (file)
@@ -11,57 +11,9 @@ here.
 Deprecation Notices
 -------------------
 
-* meson: The minimum supported version of meson for configuring and building
-  DPDK will be increased to v0.47.1 (from 0.41) from DPDK 19.05 onwards. For
-  those users with a version earlier than 0.47.1, an updated copy of meson
-  can be got using the ``pip3`` tool (or ``python3 -m pip``) for downloading
-  python packages.
-
 * kvargs: The function ``rte_kvargs_process`` will get a new parameter
   for returning key match count. It will ease handling of no-match case.
 
-* eal: To be more inclusive in choice of naming, the DPDK project
-  will replace uses of master/slave in the API's and command line arguments.
-
-  References to master/slave in relation to lcore will be renamed
-  to initial/worker.  The function ``rte_get_master_lcore()``
-  will be renamed to ``rte_get_initial_lcore()``.
-  For the 20.11 release, both names will be present and the
-  old function will be marked with the deprecated tag.
-  The old function will be removed in a future version.
-
-  The iterator for worker lcores will also change:
-  ``RTE_LCORE_FOREACH_SLAVE`` will be replaced with
-  ``RTE_LCORE_FOREACH_WORKER``.
-
-  The ``master-lcore`` argument to testpmd will be replaced
-  with ``initial-lcore``. The old ``master-lcore`` argument
-  will produce a runtime notification in 20.11 release, and
-  be removed completely in a future release.
-
-* eal: The terms blacklist and whitelist to describe devices used
-  by DPDK will be replaced in the 20.11 relase.
-  This will apply to command line arguments as well as macros.
-
-  The macro ``RTE_DEV_BLACKLISTED`` will be replaced with ``RTE_DEV_EXCLUDED``
-  and ``RTE_DEV_WHITELISTED`` will be replaced with ``RTE_DEV_INCLUDED``
-  ``RTE_BUS_SCAN_BLACKLIST`` and ``RTE_BUS_SCAN_WHITELIST`` will be
-  replaced with ``RTE_BUS_SCAN_EXCLUDED`` and ``RTE_BUS_SCAN_INCLUDED``
-  respectively. Likewise ``RTE_DEVTYPE_BLACKLISTED_PCI`` and
-  ``RTE_DEVTYPE_WHITELISTED_PCI`` will be replaced with
-  ``RTE_DEVTYPE_EXCLUDED`` and ``RTE_DEVTYPE_INCLUDED``.
-
-  The old macros will be marked as deprecated in 20.11 and any
-  usage will cause a compile warning. They will be removed in
-  a future release.
-
-  The command line arguments to ``rte_eal_init`` will change from
-  ``-b, --pci-blacklist`` to ``-x, --exclude`` and
-  ``-w, --pci-whitelist`` to ``-i, --include``.
-  The old command line arguments will continue to be accepted in 20.11
-  but will cause a runtime warning message. The old arguments will
-  be removed in a future release.
-
 * eal: The function ``rte_eal_remote_launch`` will return new error codes
   after read or write error on the pipe, instead of calling ``rte_panic``.
 
@@ -92,44 +44,10 @@ Deprecation Notices
   us extending existing enum/define.
   One solution can be using a fixed size array instead of ``.*MAX.*`` value.
 
-* mbuf: Some fields will be converted to dynamic API in DPDK 20.11
-  in order to reserve more space for the dynamic fields, as explained in
-  `this presentation <https://www.youtube.com/watch?v=Ttl6MlhmzWY>`_.
-  The following static fields will be moved as dynamic:
-
-  - ``timestamp``
-  - ``userdata`` / ``udata64``
-  - ``seqn``
-
-  As a consequence, the layout of the ``struct rte_mbuf`` will be re-arranged,
-  avoiding impact on vectorized implementation of the driver datapaths,
-  while evaluating performance gains of a better use of the first cache line.
-
-
-* 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.
-  The legacy API will be removed in DPDK 20.11.
-
 * ethdev: The flow director API, including ``rte_eth_conf.fdir_conf`` field,
   and the related structures (``rte_fdir_*`` and ``rte_eth_fdir_*``),
   will be removed in DPDK 20.11.
 
-* ethdev: The legacy L2 tunnel filtering API is deprecated as the rest of
-  the legacy filtering API.
-  The functions ``rte_eth_dev_l2_tunnel_eth_type_conf`` and
-  ``rte_eth_dev_l2_tunnel_offload_set`` which were not marked as deprecated,
-  will be removed in DPDK 20.11.
-
-* ethdev: Update API functions returning ``void`` to return ``int`` with
-  negative errno values to indicate various error conditions (e.g.
-  invalid port ID, unsupported operation, failed operation):
-
-  - ``rte_eth_dev_stop``
-  - ``rte_eth_dev_close``
-
 * ethdev: New offload flags ``DEV_RX_OFFLOAD_FLOW_MARK`` will be added in 19.11.
   This will allow application to enable or disable PMDs from updating
   ``rte_mbuf::hash::fdir``.
@@ -138,10 +56,30 @@ Deprecation Notices
   In 19.11 PMDs will still update the field even when the offload is not
   enabled.
 
-* ethdev: Add new fields to ``rte_eth_rxconf`` to configure the receiving
-  queues to split ingress packets into multiple segments according to the
-  specified lengths into the buffers allocated from the specified
-  memory pools. The backward compatibility to existing API is preserved.
+* ethdev: ``uint32_t max_rx_pkt_len`` field of ``struct rte_eth_rxmode``, will be
+  replaced by a new ``uint32_t mtu`` field of ``struct rte_eth_conf`` in v21.11.
+  The new ``mtu`` field will be used to configure the initial device MTU via
+  ``rte_eth_dev_configure()`` API.
+  Later MTU can be changed by ``rte_eth_dev_set_mtu()`` API as done now.
+  The existing ``(struct rte_eth_dev)->data->mtu`` variable will be used to store
+  the configured ``mtu`` value,
+  and this new ``(struct rte_eth_dev)->data->dev_conf.mtu`` variable will
+  be used to store the user configuration request.
+  Unlike ``max_rx_pkt_len``, which was valid only when ``JUMBO_FRAME`` enabled,
+  ``mtu`` field will be always valid.
+  When ``mtu`` config is not provided by the application, default ``RTE_ETHER_MTU``
+  value will be used.
+  ``(struct rte_eth_dev)->data->mtu`` should be updated after MTU set successfully,
+  either by ``rte_eth_dev_configure()`` or ``rte_eth_dev_set_mtu()``.
+
+  An application may need to configure device for a specific Rx packet size, like for
+  cases ``DEV_RX_OFFLOAD_SCATTER`` is not supported and device received packet size
+  can't be bigger than Rx buffer size.
+  To cover these cases an application needs to know the device packet overhead to be
+  able to calculate the ``mtu`` corresponding to a Rx buffer size, for this
+  ``(struct rte_eth_dev_info).max_rx_pktlen`` will be kept,
+  the device packet overhead can be calculated as:
+  ``(struct rte_eth_dev_info).max_rx_pktlen - (struct rte_eth_dev_info).max_mtu``
 
 * ethdev: ``rx_descriptor_done`` dev_ops and ``rte_eth_rx_descriptor_done``
   will be removed in 21.11.
@@ -154,53 +92,48 @@ Deprecation Notices
   as deprecated in DPDK 20.11, along with the associated macros ``ETH_MIRROR_*``.
   This API will be fully removed in DPDK 21.11.
 
-* ethdev: The ``struct rte_flow_item_eth`` and ``struct rte_flow_item_vlan``
-  structs will be modified, to include an additional value, indicating existence
-  or absence of a VLAN header following the current header, as proposed in RFC
-  https://mails.dpdk.org/archives/dev/2020-August/177536.html.
-
-* ethdev: The ``struct rte_flow_item_ipv6`` struct will be modified to include
-  additional values, indicating existence or absence of IPv6 extension headers
-  following the IPv6 header, as proposed in RFC
-  https://mails.dpdk.org/archives/dev/2020-August/177257.html.
-
-* security: The API ``rte_security_session_create`` takes only single mempool
-  for session and session private data. So the application need to create
-  mempool for twice the number of sessions needed and will also lead to
-  wastage of memory as session private data need more memory compared to session.
-  Hence the API will be modified to take two mempool pointers - one for session
-  and one for private data.
-
-* cryptodev: ``RTE_CRYPTO_AEAD_LIST_END`` from ``enum rte_crypto_aead_algorithm``,
-  ``RTE_CRYPTO_CIPHER_LIST_END`` from ``enum rte_crypto_cipher_algorithm`` and
-  ``RTE_CRYPTO_AUTH_LIST_END`` from ``enum rte_crypto_auth_algorithm``
-  will be removed.
-
-* cryptodev: support for using IV with all sizes is added, J0 still can
-  be used but only when IV length in following structs ``rte_crypto_auth_xform``,
-  ``rte_crypto_aead_xform`` is set to zero. When IV length is greater or equal
-  to one it means it represents IV, when is set to zero it means J0 is used
-  directly, in this case 16 bytes of J0 need to be passed.
-
-* scheduler: The functions ``rte_cryptodev_scheduler_slave_attach``,
-  ``rte_cryptodev_scheduler_slave_detach`` and
-  ``rte_cryptodev_scheduler_slaves_get`` will be replaced in 20.11 by
-  ``rte_cryptodev_scheduler_worker_attach``,
-  ``rte_cryptodev_scheduler_worker_detach`` and
-  ``rte_cryptodev_scheduler_workers_get`` accordingly.
-
-* eventdev: Following structures will be modified to support DLB PMD
-  and future extensions:
-
-  - ``rte_event_dev_info``
-  - ``rte_event_dev_config``
-  - ``rte_event_port_conf``
-
-  Patches containing justification, documentation, and proposed modifications
-  can be found at:
-
-  - https://patches.dpdk.org/patch/71457/
-  - https://patches.dpdk.org/patch/71456/
+* ethdev: Attribute ``shared`` of the ``struct rte_flow_action_count``
+  is deprecated and will be removed in DPDK 21.11. Shared counters should
+  be managed using shared actions API (``rte_flow_shared_action_create`` etc).
+
+* ethdev: The flow API matching pattern structures, ``struct rte_flow_item_*``,
+  should start with relevant protocol header.
+  Some matching pattern structures implements this by duplicating protocol header
+  fields in the struct. To clarify the intention and to be sure protocol header
+  is intact, will replace those fields with relevant protocol header struct.
+  In v21.02 both individual protocol header fields and the protocol header struct
+  will be added as union, target is switch usage to the protocol header by time.
+  In v21.11 LTS, protocol header fields will be cleaned and only protocol header
+  struct will remain.
+
+* ethdev: Queue specific stats fields will be removed from ``struct rte_eth_stats``.
+  Mentioned fields are: ``q_ipackets``, ``q_opackets``, ``q_ibytes``, ``q_obytes``,
+  ``q_errors``.
+  Instead queue stats will be received via xstats API. Current method support
+  will be limited to maximum 256 queues.
+  Also compile time flag ``RTE_ETHDEV_QUEUE_STAT_CNTRS`` will be removed.
+
+* ethdev: The offload flag ``PKT_RX_EIP_CKSUM_BAD`` will be removed and
+  replaced by the new flag ``PKT_RX_OUTER_IP_CKSUM_BAD``. The new name is more
+  consistent with existing outer header checksum status flag naming, which
+  should help in reducing confusion about its usage.
+
+* i40e: As there are both i40evf and iavf pmd, the functions of them are
+  duplicated. And now more and more advanced features are developed on iavf.
+  To keep consistent with kernel driver's name
+  (https://patchwork.ozlabs.org/patch/970154/), i40evf is no need to maintain.
+  Starting from 21.05, the default VF driver of i40e will be iavf, but i40evf
+  can still be used if users specify the devarg "driver=i40evf". I40evf will
+  be deleted in DPDK 21.11.
+
+* eventdev: The structure ``rte_event_eth_rx_adapter_queue_conf`` will be
+  extended to include ``rte_event_eth_rx_adapter_event_vector_config`` elements
+  and the function ``rte_event_eth_rx_adapter_queue_event_vector_config`` will
+  be removed in DPDK 21.11.
+
+  An application can enable event vectorization by passing the desired vector
+  values to the function ``rte_event_eth_rx_adapter_queue_add`` using
+  the structure ``rte_event_eth_rx_adapter_queue_add``.
 
 * sched: To allow more traffic classes, flexible mapping of pipe queues to
   traffic classes, and subport level configuration of pipes and queues
@@ -211,16 +144,6 @@ Deprecation Notices
 * metrics: The function ``rte_metrics_init`` will have a non-void return
   in order to notify errors instead of calling ``rte_exit``.
 
-* power: ``rte_power_set_env`` function will no longer return 0 on attempt
-  to set new power environment if power environment was already initialized.
-  In this case the function will return -1 unless the environment is unset first
-  (using ``rte_power_unset_env``). Other function usage scenarios will not change.
-
 * cmdline: ``cmdline`` structure will be made opaque to hide platform-specific
   content. On Linux and FreeBSD, supported prior to DPDK 20.11,
   original structure will be kept until DPDK 21.11.
-
-* dpdk-setup.sh: This old script relies on deprecated stuff, and especially
-  ``make``. Given environments are too much variables for such a simple script,
-  it will be removed in DPDK 20.11.
-  Some useful parts may be converted into specific scripts.