From c9b13d944088fb7cb9eb8b2c91cc64354c1425bb Mon Sep 17 00:00:00 2001 From: John McNamara Date: Fri, 10 Nov 2017 12:27:15 +0000 Subject: [PATCH] doc: update release notes for 17.11 Fix grammar, spelling and formatting of DPDK 17.11 release notes. Signed-off-by: John McNamara --- doc/guides/rel_notes/release_17_11.rst | 327 ++++++++++++------------- 1 file changed, 152 insertions(+), 175 deletions(-) diff --git a/doc/guides/rel_notes/release_17_11.rst b/doc/guides/rel_notes/release_17_11.rst index 4e04f20461..5361eb1cd8 100644 --- a/doc/guides/rel_notes/release_17_11.rst +++ b/doc/guides/rel_notes/release_17_11.rst @@ -43,21 +43,20 @@ New Features * **Extended port_id range from uint8_t to uint16_t.** - Increased port_id range from 8 bits to 16 bits in order to support more than - 256 ports in dpdk. All ethdev APIs which have port_id as parameter are changed - in the meantime. + Increased the ``port_id`` range from 8 bits to 16 bits in order to support + more than 256 ports in DPDK. All ethdev APIs which have ``port_id`` as + parameter have been changed. * **Modified the return type of rte_eth_stats_reset.** - Changed return type of ``rte_eth_stats_reset`` from ``void`` to ``int`` - so the caller may know whether a device supports the operation or not + Changed return type of ``rte_eth_stats_reset`` from ``void`` to ``int`` so + that the caller can determine whether a device supports the operation or not and if the operation was carried out. * **Added a new driver for Marvell Armada 7k/8k devices.** - Added the new mrvl net driver for Marvell Armada 7k/8k devices. See the - "Network Interface Controller Drivers" document for more details on this new - driver. + Added the new ``mrvl`` net driver for Marvell Armada 7k/8k devices. See the + :doc:`../nics/mrvl` NIC guide for more details on this new driver. * **Updated mlx4 driver.** @@ -89,20 +88,20 @@ New Features Updated the mlx5 driver including the following changes: - * Enabled PMD to run on top of upstream linux kernel and rdma-core libs. - By that removed the dependency on specific Mellanox OFED libraries. + * Enabled the PMD to run on top of upstream Linux kernel and rdma-core + libs, removing the dependency on specific Mellanox OFED libraries. * Improved PMD latency performance. * Improved PMD memory footprint. - * Supported vectorized Rx/Tx burst for ARMv8. - * Supported secondary process. - * Supported flow counters. - * Supported Rx hardware timestamp offload. - * Supported device removal event. + * Added support for vectorized Rx/Tx burst for ARMv8. + * Added support for secondary process. + * Added support for flow counters. + * Added support for Rx hardware timestamp offload. + * Added support for device removal event. * **Added SoftNIC PMD.** - Added new SoftNIC PMD. This virtual device offers applications a software - fallback support for traffic management. + Added a new SoftNIC PMD. This virtual device provides applications with + software fallback support for traffic management. * **Added support for NXP DPAA Devices.** @@ -112,24 +111,23 @@ New Features * DPAA Mempool driver for supporting offloaded packet memory pool * DPAA PMD for DPAA devices - See the "Network Interface Controller Drivers" document for more details of - this new driver. + See the :doc:`../nics/dpaa` document for more details of this new driver. * **Updated support for Cavium OCTEONTX Device.** - Updated support for Cavium's OCTEONTX device(CN83xx). This includes: + Updated support for Cavium's OCTEONTX device (CN83xx). This includes: * OCTEONTX Mempool driver for supporting offloaded packet memory pool * OCTEONTX Ethdev PMD * OCTEONTX Eventdev-Ethdev Rx adapter - See the "Network Interface Controller Drivers" document for more details of - this new driver. + See the :doc:`../nics/octeontx` document for more details of this new driver. -* **nfp: Added PF support.** +* **Added PF support to the Netronome NFP PMD.** - Previously Netronome's NFP PMD had just support for VFs. PF support is - just as a basic DPDK port and has no VF management yet. + Added PF support to the Netronome NFP PMD. Previously the NFP PMD only + supported VFs. PF support is just as a basic DPDK port and has no VF + management yet. PF support comes with firmware upload support which allows the PMD to independently work from kernel netdev NFP drivers. @@ -143,113 +141,115 @@ New Features * Support for Flow API * Support for Tx and Rx descriptor status functions -* **Add bus agnostic functions to cryptodev for PMD initialisation** +* **Added bus agnostic functions to cryptodev for PMD initialization** - Adds new PMD assist functions ``rte_cryptodev_pmd_parse_input_args()``, - ``rte_cryptodev_pmd_create()`` and ``rte_cryptodev_pmd_destroy()`` which - are bus independent for driver to manage creation and destruction of new - device instances. + Added new PMD assist, bus independent, functions + ``rte_cryptodev_pmd_parse_input_args()``, ``rte_cryptodev_pmd_create()`` and + ``rte_cryptodev_pmd_destroy()`` for drivers to manage creation and + destruction of new device instances. * **Updated QAT crypto PMD.** - Performance enhancements: + Added several performance enhancements: * Removed atomics from the internal queue pair structure. - * Coalesce writes to HEAD CSR on response processing. - * Coalesce writes to TAIL CSR on request processing. + * Added coalesce writes to HEAD CSR on response processing. + * Added coalesce writes to TAIL CSR on request processing. - Additional support for: - - * AES CCM algorithm. + In addition support was added for the AES CCM algorithm. * **Updated the AESNI MB PMD.** The AESNI MB PMD has been updated with additional support for: - * DES CBC algorithm. - * DES DOCSIS BPI algorithm. + * The DES CBC algorithm. + * The DES DOCSIS BPI algorithm. - This requires the IPSec Multi-buffer library 0.47. For more details, - check out the AESNI MB PMD documenation. + This change requires version 0.47 of the IPSec Multi-buffer library. For + more details see the :doc:`../cryptodevs/aesni_mb` documentation. * **Updated the OpenSSL PMD.** The OpenSSL PMD has been updated with additional support for: - * DES CBC algorithm. - * AES CCM algorithm. + * The DES CBC algorithm. + * The AES CCM algorithm. * **Added NXP DPAA SEC crypto PMD.** - A new "dpaa_sec" hardware based crypto PMD for NXP DPAA devices has been - added. See the "Crypto Device Drivers" document for more details on this - driver. + A new ``dpaa_sec`` hardware based crypto PMD for NXP DPAA devices has been + added. See the :doc:`../cryptodevs/dpaa_sec` document for more details. * **Added MRVL crypto PMD.** A new crypto PMD has been added, which provides several ciphering and hashing algorithms. All cryptography operations use the MUSDK library crypto API. + See the :doc:`../cryptodevs/mrvl` document for more details. * **Add new benchmarking mode to dpdk-test-crypto-perf application.** - Added new "PMD cyclecount" benchmark mode to dpdk-test-crypto-perf application - that displays more detailed breakdown of CPU cycles used by hardware + Added a new "PMD cyclecount" benchmark mode to the ``dpdk-test-crypto-perf`` + application to display a detailed breakdown of CPU cycles used by hardware acceleration. * **Added the Security Offload Library.** - Added an experimental library - rte_security. It provide security APIs for - protocols like IPSec using inline ipsec offload to ethernet device or full - protocol offload with lookaside crypto device. + Added an experimental library - ``rte_security``. This provide security APIs + for protocols like IPSec using inline ipsec offload to ethernet devices or + full protocol offload with lookaside crypto devices. - See the "Security_Library" section of the DPDK Programmers Guide document, - for more information. + See the :doc:`../prog_guide/rte_security` section of the DPDK Programmers + Guide document for more information. -* **Updated DPAA2_SEC crypto driver.** +* **Updated the DPAA2_SEC crypto driver to support rte_security.** - Updated dpaa2_sec crypto PMD to support rte_security lookaside protocol - offload for IPSec. + Updated the ``dpaa2_sec`` crypto PMD to support ``rte_security`` lookaside + protocol offload for IPSec. -* **Updated IXGBE ethernet driver.** +* **Updated the IXGBE ethernet driver to support rte_security.** - Updated ixgbe ethernet PMD to support rte_security inline IPSec offload. + Updated ixgbe ethernet PMD to support ``rte_security`` inline IPSec offload. -* **Updated ipsec-secgw application** +* **Updated ipsec-secgw application to support rte_security.** - Updated ipsec-secgw sample application to support rte_security actions for - ipsec inline and full protocol offload using lookaside crypto offload. + Updated the ``ipsec-secgw`` sample application to support ``rte_security`` + actions for ipsec inline and full protocol offload using lookaside crypto + offload. * **Added IOMMU support to libvhost-user** - Implemented device IOTLB in Vhost-user backend, and enabled Virtio's IOMMU - feature. The feature is disabled by default, and can be enabled by setting - RTE_VHOST_USER_IOMMU_SUPPORT flag at vhost device registration time. + Implemented device IOTLB in the Vhost-user backend, and enabled Virtio's + IOMMU feature. The feature is disabled by default, and can be enabled by + setting ``RTE_VHOST_USER_IOMMU_SUPPORT`` flag at vhost device registration + time. * **Added the Event Ethernet Adapter Library.** - Added the Event Ethernet Adapter library. It provices APIs for - eventdev applications to configure the ethdev to eventdev packet flow. + Added the Event Ethernet Adapter library. This library provides APIs for + eventdev applications to configure the ethdev for eventdev packet flow. -* **Updated DPAA2 Event PMD.** +* **Updated DPAA2 Event PMD for the Event Ethernet Adapter.** - Added support for eventdev ethernet adapter for DPAA2. + Added support for the eventdev ethernet adapter for DPAA2. * **Added Membership library (rte_member).** - Added membership library. It provides an API for DPDK applications to insert a - new member, delete an existing member, or query the existence of a member in a - given set, or a group of sets. For the case of a group of sets the library - will return not only whether the element has been inserted before in one of - the sets but also which set it belongs to. + Added a new data structure library called the Membership Library. The Membership Library is an extension and generalization of a traditional - filter (for example Bloom Filter) structure that has multiple usages in a wide - variety of workloads and applications. In general, the Membership Library is a - data structure that provides a “set-summary” and responds to set-membership - queries whether a certain member belongs to a set(s). + filter (for example Bloom Filter) structure that has multiple usages in a + wide variety of workloads and applications. In general, the Membership + Library is a data structure that provides a "set-summary" and responds to + set-membership queries whether a certain member belongs to a set(s). + + The library provides APIs for DPDK applications to insert a new member, + delete an existing member, and query the existence of a member in a given + set, or a group of sets. For the case of a group of sets the library will + return not only whether the element has been inserted in one of the sets but + also which set it belongs to. - See the :ref:`Membership Library ` documentation in - the Programmers Guide document, for more information. + See the :doc:`../prog_guide/member_lib` documentation in the Programmers + Guide, for more information. * **Added the Generic Segmentation Offload Library.** @@ -269,9 +269,9 @@ New Features * **Added the Flow Classification Library.** - Added the Flow Classification library, it provides an API for DPDK - applications to classify an input packet by matching it against a set of flow - rules. It uses the librte_table API to manage the flow rules. + Added an experimental Flow Classification library to provide APIs for DPDK + applications to classify an input packet by matching it against a set of + flow rules. It uses the ``librte_table`` API to manage the flow rules. Resolved Issues @@ -294,9 +294,6 @@ Resolved Issues ========================================================= -EAL -~~~ - * **Service core fails to call service callback due to atomic lock** In a specific configuration of multi-thread unsafe services and service @@ -305,36 +302,6 @@ EAL looked like another thread was executing the service callback. The logic for atomic locking of the services has been fixed and refactored for readability. -Drivers -~~~~~~~ - - -Libraries -~~~~~~~~~ - - -Examples -~~~~~~~~ - - -Other -~~~~~ - - -Known Issues ------------- - -.. This section should contain new known issues in this release. Sample format: - - * **Add title in present tense with full stop.** - - Add a short 1-2 sentence description of the known issue in the present - tense. Add information on any known workarounds. - - This section is a comment. do not overwrite or remove it. - Also, make sure to start the actual text at the margin. - ========================================================= - API Changes ----------- @@ -349,43 +316,46 @@ API Changes Also, make sure to start the actual text at the margin. ========================================================= -* **Ethdev device name length increased** +* **Ethdev device name length increased.** - The size of internal device name is increased to 64 characters - to allow for storing longer bus specific name. + The size of internal device name has been increased to 64 characters + to allow for storing longer bus specific names. -* **Ethdev flag RTE_ETH_DEV_DETACHABLE was removed** +* **Removed the Ethdev RTE_ETH_DEV_DETACHABLE flag.** - This flag is not necessary anymore, with the new hotplug implementation. - It is now removed from the ether library. Its semantic is expressed at the bus - and PMD level. + Removed the Ethdev ``RTE_ETH_DEV_DETACHABLE`` flag. This flag is not + required anymore, with the new hotplug implementation. It has been removed + from the ether library. Its semantics are now expressed at the bus and PMD + level. * **Service cores API updated for usability** - The service cores API has been changed, removing pointers from the API - where possible, instead using integer IDs to identify each service. This - simplifed application code, aids debugging, and provides better + The service cores API has been changed, removing pointers from the API where + possible, and instead using integer IDs to identify each service. This + simplifies application code, aids debugging, and provides better encapsulation. A summary of the main changes made is as follows: * Services identified by ID not by ``rte_service_spec`` pointer * Reduced API surface by using ``set`` functions instead of enable/disable * Reworked ``rte_service_register`` to provide the service ID to registrar - * Rework start and stop APIs into ``rte_service_runstate_set`` - * Added API to set runstate of service implementation to indicate readyness + * Reworked start and stop APIs into ``rte_service_runstate_set`` + * Added API to set runstate of service implementation to indicate readiness -* **The following changes made in mempool library** +* **The following changes have been made in the mempool library** - * Moved ``flags`` datatype from int to unsigned int for ``rte_mempool``. + * Moved ``flags`` datatype from ``int`` to ``unsigned int`` for + ``rte_mempool``. * Removed ``__rte_unused int flag`` param from ``rte_mempool_generic_put`` and ``rte_mempool_generic_get`` API. * Added ``flags`` param in ``rte_mempool_xmem_size`` and ``rte_mempool_xmem_usage``. + * ``rte_mem_phy2mch`` was used in Xen dom0 to obtain the physical address; + remove this API as Xen dom0 support was removed. -* ``rte_mem_phy2mch`` was used in Xen dom0 to obtain the physical address; - remove this API as Xen dom0 support was removed. +* **Added IOVA aliases related to physical address handling.** -* **Some data type, structure members and functions related to physical address - are deprecated and have new alias with IOVA wording.** + Some data types, structure members and functions related to physical address + handling are deprecated and have new aliases with IOVA wording. For example: * ``phys_addr_t`` can be often replaced by ``rte_iova_t`` of same size. * ``RTE_BAD_PHYS_ADDR`` is often replaced by ``RTE_BAD_IOVA`` of same value. @@ -393,10 +363,13 @@ API Changes * ``rte_mem_virt2phy()`` can often be replaced by ``rte_mem_virt2iova``. * ``rte_malloc_virt2phy`` is aliased with ``rte_malloc_virt2iova``. * ``rte_memzone.phys_addr`` is aliased with ``rte_memzone.iova``. - * ``rte_mempool_objhdr.physaddr`` is aliased with ``rte_mempool_objhdr.iova``. - * ``rte_mempool_memhdr.phys_addr`` is aliased with ``rte_mempool_memhdr.iova``. + * ``rte_mempool_objhdr.physaddr`` is aliased with + ``rte_mempool_objhdr.iova``. + * ``rte_mempool_memhdr.phys_addr`` is aliased with + ``rte_mempool_memhdr.iova``. * ``rte_mempool_virt2phy()`` can be replaced by ``rte_mempool_virt2iova()``. - * ``rte_mempool_populate_phys*()`` are aliased with ``rte_mempool_populate_iova*()`` + * ``rte_mempool_populate_phys*()`` are aliased with + ``rte_mempool_populate_iova*()`` * ``rte_mbuf.buf_physaddr`` is aliased with ``rte_mbuf.buf_iova``. * ``rte_mbuf_data_dma_addr*()`` are aliased with ``rte_mbuf_data_iova*()``. * ``rte_pktmbuf_mtophys*`` are aliased with ``rte_pktmbuf_iova*()``. @@ -406,26 +379,26 @@ API Changes The PCI bus previously implemented within the EAL has been moved. A first part has been added as an RTE library providing PCI helpers to parse device locations or other such utilities. - A second part consisting in the actual bus driver has been moved to its + A second part consisting of the actual bus driver has been moved to its proper subdirectory, without changing its functionalities. - As such, several PCI-related functions are not proposed by the EAL anymore: - - * rte_pci_detach - * rte_pci_dump - * rte_pci_ioport_map - * rte_pci_ioport_read - * rte_pci_ioport_unmap - * rte_pci_ioport_write - * rte_pci_map_device - * rte_pci_probe - * rte_pci_probe_one - * rte_pci_read_config - * rte_pci_register - * rte_pci_scan - * rte_pci_unmap_device - * rte_pci_unregister - * rte_pci_write_config + As such, several PCI-related functions are not exposed by the EAL anymore: + + * ``rte_pci_detach`` + * ``rte_pci_dump`` + * ``rte_pci_ioport_map`` + * ``rte_pci_ioport_read`` + * ``rte_pci_ioport_unmap`` + * ``rte_pci_ioport_write`` + * ``rte_pci_map_device`` + * ``rte_pci_probe`` + * ``rte_pci_probe_one`` + * ``rte_pci_read_config`` + * ``rte_pci_register`` + * ``rte_pci_scan`` + * ``rte_pci_unmap_device`` + * ``rte_pci_unregister`` + * ``rte_pci_write_config`` These functions are made available either as part of ``librte_pci`` or ``librte_bus_pci``. @@ -433,6 +406,7 @@ API Changes * **Moved vdev bus APIs outside of the EAL** Moved the following APIs from ``librte_eal`` to ``librte_bus_vdev``: + * ``rte_vdev_init`` * ``rte_vdev_register`` * ``rte_vdev_uninit`` @@ -441,13 +415,14 @@ API Changes * **Add return value to stats_get dev op API** The ``stats_get`` dev op API return value has been changed to be int. - By this way PMDs can return an error value in case of failure at stats + In this way PMDs can return an error value in case of failure at stats getting process time. -* **Modified the rte_cryptodev_allocate_driver function in the cryptodev library.** +* **Modified the rte_cryptodev_allocate_driver function.** - The function ``rte_cryptodev_allocate_driver()`` has been modified. - An extra parameter ``struct cryptodev_driver *crypto_drv`` has been added. + Modified the ``rte_cryptodev_allocate_driver()`` function in the cryptodev + library. An extra parameter ``struct cryptodev_driver *crypto_drv`` has been + added. * **Removed virtual device bus specific functions from librte_cryptodev.** @@ -456,8 +431,9 @@ API Changes and have been replaced by non bus specific functions ``rte_cryptodev_pmd_parse_input_args()`` and ``rte_cryptodev_pmd_create()``. -* ``rte_cryptodev_create_vdev`` was removed to avoid the dependency on vdev - in librte_cryptodev; instead, users can call rte_vdev_init() directly. + The ``rte_cryptodev_create_vdev()`` function was removed to avoid the + dependency on vdev in librte_cryptodev; instead, users can call + ``rte_vdev_init()`` directly. * **Removed PCI device bus specific functions from librte_cryptodev.** @@ -470,29 +446,30 @@ API Changes The functions ``rte_set_log_level()``, ``rte_get_log_level()``, ``rte_set_log_type()`` and ``rte_get_log_type()`` have been removed. + They are respectively replaced by ``rte_log_set_global_level()``, ``rte_log_get_global_level()``, ``rte_log_set_level()`` and ``rte_log_get_level()``. -* **Removed ``mbuf`` flags ``PKT_RX_VLAN_PKT`` and ``PKT_RX_QINQ_PKT``.** +* **Removed mbuf flags PKT_RX_VLAN_PKT and PKT_RX_QINQ_PKT.** The ``mbuf`` flags ``PKT_RX_VLAN_PKT`` and ``PKT_RX_QINQ_PKT`` have - been removed since their behavior were not properly described. + been removed since their behavior was not properly described. -* **Added ``mbuf`` flags ``PKT_RX_VLAN`` and ``PKT_RX_QINQ``.** +* **Added mbuf flags PKT_RX_VLAN and PKT_RX_QINQ.** Two ``mbuf`` flags have been added to indicate that the VLAN identifier has been saved in in the ``mbuf`` structure. For instance: - - if VLAN is not stripped and TCI is saved: ``PKT_RX_VLAN`` - - if VLAN is stripped and TCI is saved: ``PKT_RX_VLAN | PKT_RX_VLAN_STRIPPED`` + - If VLAN is not stripped and TCI is saved: ``PKT_RX_VLAN`` + - If VLAN is stripped and TCI is saved: ``PKT_RX_VLAN | PKT_RX_VLAN_STRIPPED`` * **Modified the vlan_offload_set_t function prototype in the ethdev library.** - Changed the function prototype of ``vlan_offload_set_t``. The return value - has been changed from ``void`` to ``int`` so the caller to knows whether - the backing device supports the operation or if the operation was - successfully performed. + Modified the ``vlan_offload_set_t`` function prototype in the ethdev + library. The return value has been changed from ``void`` to ``int`` so the + caller can determine whether the backing device supports the operation or if + the operation was successfully performed. ABI Changes @@ -511,17 +488,17 @@ ABI Changes * **Extended port_id range.** The size of the field ``port_id`` in the ``rte_eth_dev_data`` structure - changed, as described in the `New Features` section. + has changed, as described in the `New Features` section above. * **New parameter added to rte_eth_dev.** - New parameter ``security_ctx`` added to ``rte_eth_dev`` to support security - operations like IPSec inline. + A new parameter ``security_ctx`` has been added to ``rte_eth_dev`` to + support security operations like IPSec inline. * **New parameter added to rte_cryptodev.** - New parameter ``security_ctx`` added to ``rte_cryptodev`` to support security - operations like lookaside crypto. + A new parameter ``security_ctx`` has been added to ``rte_cryptodev`` to + support security operations like lookaside crypto. Removed Items @@ -536,10 +513,10 @@ Removed Items Also, make sure to start the actual text at the margin. ========================================================= -* Xen dom0 in EAL was removed, as well as xenvirt PMD and vhost_xen. +* Xen dom0 in EAL has been removed, as well as the xenvirt PMD and vhost_xen. * The crypto performance unit tests have been removed, - replaced by the dpdk-test-crypto-perf application. + replaced by the ``dpdk-test-crypto-perf`` application. Shared Library Versions -- 2.20.1