[dpdk-dev] [PATCH v2 6/6] doc: deprecate VFIO DMA map APIs

[David Marchand]

On Thu, Feb 21, 2019 at 3:51 PM Shahaf Shuler <shahafs at mellanox.com> wrote:

> As those have been replaced by rte_bus_dma_map and rte_pci_dma_unmap
> APIs.
>
> Signed-off-by: Shahaf Shuler <shahafs at mellanox.com>
> ---
>  doc/guides/prog_guide/env_abstraction_layer.rst | 2 +-
>  doc/guides/rel_notes/deprecation.rst            | 4 ++++
>  lib/librte_eal/common/include/rte_vfio.h        | 6 ++++--
>  3 files changed, 9 insertions(+), 3 deletions(-)
>
> diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst
> b/doc/guides/prog_guide/env_abstraction_layer.rst
> index 929d76dba7..6a1ddf8b4a 100644
> --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> @@ -282,7 +282,7 @@ The expected workflow is as follows:
>      - If IOVA table is not specified, IOVA addresses will be assumed to be
>        unavailable
>      - Other processes must attach to the memory area before they can use
> it
> -* Perform DMA mapping with ``rte_vfio_dma_map`` if needed
> +* Perform DMA mapping with ``rte_bus_dma_map`` if needed
>  * Use the memory area in your application
>  * If memory area is no longer needed, it can be unregistered
>      - If the area was mapped for DMA, unmapping must be performed before
> diff --git a/doc/guides/rel_notes/deprecation.rst
> b/doc/guides/rel_notes/deprecation.rst
> index 1b4fcb7e64..f7ae0d56fb 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -35,6 +35,10 @@ Deprecation Notices
>
>      + ``rte_eal_devargs_type_count``
>
> +* vfio: removal of ``rte_vfio_dma_map`` and ``rte_vfio_dma_unmap`` APIs
> which
> +  have been replaced with ``rte_bus_dma_map`` and ``rte_bus_dma_unmap``
> +  functions.  The due date for the removal targets DPDK 19.08.
> +
>  * pci: Several exposed functions are misnamed.
>    The following functions are deprecated starting from v17.11 and are
> replaced:
>
> diff --git a/lib/librte_eal/common/include/rte_vfio.h
> b/lib/librte_eal/common/include/rte_vfio.h
> index 54a0df5726..df139edea2 100644
> --- a/lib/librte_eal/common/include/rte_vfio.h
> +++ b/lib/librte_eal/common/include/rte_vfio.h
> @@ -190,6 +190,7 @@ int
>  rte_vfio_clear_group(int vfio_group_fd);
>
>  /**
> + * @deprecated
>   * Map memory region for use with VFIO.
>   *
>   * @note Require at least one device to be attached at the time of
> @@ -210,11 +211,12 @@ rte_vfio_clear_group(int vfio_group_fd);
>   *   0 if success.
>   *   -1 on error.
>   */
> -int
> +int __rte_deprecated
>  rte_vfio_dma_map(uint64_t vaddr, uint64_t iova, uint64_t len);
>
>
>  /**
> + * @deprecated
>   * Unmap memory region from VFIO.
>   *
>   * @param vaddr
> @@ -231,7 +233,7 @@ rte_vfio_dma_map(uint64_t vaddr, uint64_t iova,
> uint64_t len);
>   *   -1 on error.
>   */
>
> -int
> +int __rte_deprecated
>  rte_vfio_dma_unmap(uint64_t vaddr, uint64_t iova, uint64_t len);
>  /**
>   * Parse IOMMU group number for a device
> --
> 2.12.0
>
>
I don't know users of such apis, but you can't mark rte_vfio_dma_map as
deprecated now.
There is no stable alternative, rte_bus_dma_map() is experimental.

This has been discussed and some patches are in progress about it.
Last version: http://patchwork.dpdk.org/patch/50040/

-- 
David Marchand