[v2] doc: announce transition to vDPA device name function

  There is a layer violation in the vDPA API for getting the device name.
Instead of providing the name at vDPA level,
a function returns the low-level device object.
The plan is to introduce a new function in 22.11, promote in 23.07,
and remove rte_vdpa_get_rte_device() in 23.11.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
v2: one year passed, update with a new plan
    v1 was proposing a close function, only device name is needed
---
 doc/guides/rel_notes/deprecation.rst | 7 +++++++
 1 file changed, 7 insertions(+)
  

On 7/12/22 15:36, Thomas Monjalon wrote:
> There is a layer violation in the vDPA API for getting the device name.
> Instead of providing the name at vDPA level,
> a function returns the low-level device object.
> The plan is to introduce a new function in 22.11, promote in 23.07,
> and remove rte_vdpa_get_rte_device() in 23.11.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
> v2: one year passed, update with a new plan
>      v1 was proposing a close function, only device name is needed
> ---
>   doc/guides/rel_notes/deprecation.rst | 7 +++++++
>   1 file changed, 7 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index 4e5b23c53d..0f7fefbf6a 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -107,6 +107,13 @@ Deprecation Notices
>     alternative is implemented.
>     The legacy actions should be removed in DPDK 22.11.
>   
> +* vdpa: The vDPA API should not try to manipulate or export
> +  any ``rte_device`` object, which belongs to the bus layer.
> +  The function ``rte_vdpa_get_rte_device()`` will be deprecated in 23.07,
> +  when its usage will be replaced with ``rte_vdpa_get_device_name()``.
> +  The new function should enter in 22.11 and get promoted to stable in 23.07.
> +  The target is to remove ``rte_vdpa_get_rte_device()`` in 23.11.
> +
>   * cryptodev: Hide structures ``rte_cryptodev_sym_session`` and
>     ``rte_cryptodev_asym_session`` to remove unnecessary indirection between
>     session and the private data of session. An opaque pointer can be exposed

Acked-by: Maxime Coquelin <maxime.coquelin@redhat.com>

Thanks,
Maxime
  

From: Thomas Monjalon 
> There is a layer violation in the vDPA API for getting the device name.
> Instead of providing the name at vDPA level, a function returns the low-level
> device object.
> The plan is to introduce a new function in 22.11, promote in 23.07, and remove
> rte_vdpa_get_rte_device() in 23.11.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
> v2: one year passed, update with a new plan
>     v1 was proposing a close function, only device name is needed
> ---
>  doc/guides/rel_notes/deprecation.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst
> b/doc/guides/rel_notes/deprecation.rst
> index 4e5b23c53d..0f7fefbf6a 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -107,6 +107,13 @@ Deprecation Notices
>    alternative is implemented.
>    The legacy actions should be removed in DPDK 22.11.
> 
> +* vdpa: The vDPA API should not try to manipulate or export
> +  any ``rte_device`` object, which belongs to the bus layer.
> +  The function ``rte_vdpa_get_rte_device()`` will be deprecated in
> +23.07,
> +  when its usage will be replaced with ``rte_vdpa_get_device_name()``.
> +  The new function should enter in 22.11 and get promoted to stable in 23.07.
> +  The target is to remove ``rte_vdpa_get_rte_device()`` in 23.11.
> +
>  * cryptodev: Hide structures ``rte_cryptodev_sym_session`` and
>    ``rte_cryptodev_asym_session`` to remove unnecessary indirection between
>    session and the private data of session. An opaque pointer can be exposed
> --
> 2.36.1

Acked-by: Matan Azrad <matan@nvidia.com>
  

On Tue, Jul 12, 2022 at 3:36 PM Thomas Monjalon <thomas@monjalon.net> wrote:
>
> There is a layer violation in the vDPA API for getting the device name.
> Instead of providing the name at vDPA level,
> a function returns the low-level device object.

Exposing a rte_device (as an opaque pointer) in upper device classes
seems a good thing to me.
With the API rework I proposed, we will have accessors to get this
object characteristics (like here, a name identifying it).
Having the vDPA API returns a pointer to a rte_device object makes it
possible to reuse those accessors, nothing more needed.

If the rte_device object is extended in any (unforeseen at the moment)
way in the future, it would still be a matter of using the relevant
accessor.
No update needed in the vDPA API at this point in the future.


On the other hand, what you propose here seems to go the other way.
With each device classes needing to expose, through its own means /
API, the underlying rte_device characteristics.
  

13/07/2022 15:26, David Marchand:
> On Tue, Jul 12, 2022 at 3:36 PM Thomas Monjalon <thomas@monjalon.net> wrote:
> >
> > There is a layer violation in the vDPA API for getting the device name.
> > Instead of providing the name at vDPA level,
> > a function returns the low-level device object.
> 
> Exposing a rte_device (as an opaque pointer) in upper device classes
> seems a good thing to me.
> With the API rework I proposed, we will have accessors to get this
> object characteristics (like here, a name identifying it).
> Having the vDPA API returns a pointer to a rte_device object makes it
> possible to reuse those accessors, nothing more needed.
> 
> If the rte_device object is extended in any (unforeseen at the moment)
> way in the future, it would still be a matter of using the relevant
> accessor.
> No update needed in the vDPA API at this point in the future.
> 
> 
> On the other hand, what you propose here seems to go the other way.
> With each device classes needing to expose, through its own means /
> API, the underlying rte_device characteristics.

I realize we don't have a guideline about this API aspect:
should we expose underlying handles?

I understand your point and I think it is valid.
I suggest cancelling this deprecation for now.
Once we have a guideline agreed in doc/guides/contributing/design.rst
we can revisit some API.

For instance, I've avoided to expose rte_device in gpudev,
and the NUMA socket is directly reported in gpudev infos.
Another approach would be to expose the pointer to rte_device.