doc: announce transition to vDPA port close function

  There is a layer violation in the vDPA API which encourages to destroy
a full device with rte_dev_remove() instead of just closing the port.
The plan is to introduce a new function in 21.08, promote in 21.11,
and deprecate rte_vdpa_get_rte_device() in 21.11.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 doc/guides/rel_notes/deprecation.rst | 8 ++++++++
 1 file changed, 8 insertions(+)
  

On 5/18/21 10:34 AM, Thomas Monjalon wrote:
> There is a layer violation in the vDPA API which encourages to destroy
> a full device with rte_dev_remove() instead of just closing the port.
> The plan is to introduce a new function in 21.08, promote in 21.11,
> and deprecate rte_vdpa_get_rte_device() in 21.11.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>

Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
  

18/05/2021 09:34, Thomas Monjalon:
> There is a layer violation in the vDPA API which encourages to destroy
> a full device with rte_dev_remove() instead of just closing the port.
> The plan is to introduce a new function in 21.08, promote in 21.11,
> and deprecate rte_vdpa_get_rte_device() in 21.11.

I forgot this issue.
Let's hope I (or someone else) will introduce the "close" function
so we can remove this layer violation from DPDK 22.11.
  

On 5/18/21 09:34, Thomas Monjalon wrote:
> There is a layer violation in the vDPA API which encourages to destroy
> a full device with rte_dev_remove() instead of just closing the port.
> The plan is to introduce a new function in 21.08, promote in 21.11,
> and deprecate rte_vdpa_get_rte_device() in 21.11.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
>   doc/guides/rel_notes/deprecation.rst | 8 ++++++++
>   1 file changed, 8 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index 9584d6bfd7..30f84403eb 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -126,6 +126,14 @@ Deprecation Notices
>     can still be used if users specify the devarg "driver=i40evf". I40evf will
>     be deleted in DPDK 21.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 21.11,
> +  when its usage will be replaced with a function ``rte_vdpa_close()``.
> +  The new function should enter in 21.08 and get promoted to stable in 21.11.
> +  A port close function will allow to close a single port without destroying
> +  the rest of the device.
> +
>   * 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

Maybe there was some changes since you posted the announce, but I don't
see why rte_vdpa_close() would be needed. It seems the only user of
rte_vdpa_get_rte_device() is the internal vDPA example, and it only use
it to get and print the device name.

Thanks,
Maxime
  

12/07/2022 11:16, Maxime Coquelin:
> 
> On 5/18/21 09:34, Thomas Monjalon wrote:
> > There is a layer violation in the vDPA API which encourages to destroy
> > a full device with rte_dev_remove() instead of just closing the port.
> > The plan is to introduce a new function in 21.08, promote in 21.11,
> > and deprecate rte_vdpa_get_rte_device() in 21.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 21.11,
> > +  when its usage will be replaced with a function ``rte_vdpa_close()``.
> > +  The new function should enter in 21.08 and get promoted to stable in 21.11.
> > +  A port close function will allow to close a single port without destroying
> > +  the rest of the device.
> 
> Maybe there was some changes since you posted the announce, but I don't
> see why rte_vdpa_close() would be needed. It seems the only user of
> rte_vdpa_get_rte_device() is the internal vDPA example, and it only use
> it to get and print the device name.

You're right, it was an oversight.
So we need only to get the rte_device name.

I propose to replace
	struct rte_device *rte_vdpa_get_rte_device(struct rte_vdpa_device *vdpa_dev);
with
	const char *rte_vdpa_get_name(void);
  

12/07/2022 14:26, Thomas Monjalon:
> 12/07/2022 11:16, Maxime Coquelin:
> > 
> > On 5/18/21 09:34, Thomas Monjalon wrote:
> > > There is a layer violation in the vDPA API which encourages to destroy
> > > a full device with rte_dev_remove() instead of just closing the port.
> > > The plan is to introduce a new function in 21.08, promote in 21.11,
> > > and deprecate rte_vdpa_get_rte_device() in 21.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 21.11,
> > > +  when its usage will be replaced with a function ``rte_vdpa_close()``.
> > > +  The new function should enter in 21.08 and get promoted to stable in 21.11.
> > > +  A port close function will allow to close a single port without destroying
> > > +  the rest of the device.
> > 
> > Maybe there was some changes since you posted the announce, but I don't
> > see why rte_vdpa_close() would be needed. It seems the only user of
> > rte_vdpa_get_rte_device() is the internal vDPA example, and it only use
> > it to get and print the device name.
> 
> You're right, it was an oversight.
> So we need only to get the rte_device name.
> 
> I propose to replace
> 	struct rte_device *rte_vdpa_get_rte_device(struct rte_vdpa_device *vdpa_dev);
> with
> 	const char *rte_vdpa_get_name(void);

sorry, I missed a parameter :)
It would be:
	const char *rte_vdpa_get_name(struct rte_vdpa_device *vdpa_dev);

Or do you prefer "rte_vdpa_get_device_name"?
  

On 7/12/22 14:28, Thomas Monjalon wrote:
> 12/07/2022 14:26, Thomas Monjalon:
>> 12/07/2022 11:16, Maxime Coquelin:
>>>
>>> On 5/18/21 09:34, Thomas Monjalon wrote:
>>>> There is a layer violation in the vDPA API which encourages to destroy
>>>> a full device with rte_dev_remove() instead of just closing the port.
>>>> The plan is to introduce a new function in 21.08, promote in 21.11,
>>>> and deprecate rte_vdpa_get_rte_device() in 21.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 21.11,
>>>> +  when its usage will be replaced with a function ``rte_vdpa_close()``.
>>>> +  The new function should enter in 21.08 and get promoted to stable in 21.11.
>>>> +  A port close function will allow to close a single port without destroying
>>>> +  the rest of the device.
>>>
>>> Maybe there was some changes since you posted the announce, but I don't
>>> see why rte_vdpa_close() would be needed. It seems the only user of
>>> rte_vdpa_get_rte_device() is the internal vDPA example, and it only use
>>> it to get and print the device name.
>>
>> You're right, it was an oversight.
>> So we need only to get the rte_device name.
>>
>> I propose to replace
>> 	struct rte_device *rte_vdpa_get_rte_device(struct rte_vdpa_device *vdpa_dev);
>> with
>> 	const char *rte_vdpa_get_name(void);
> 
> sorry, I missed a parameter :)
> It would be:
> 	const char *rte_vdpa_get_name(struct rte_vdpa_device *vdpa_dev);
> 
> Or do you prefer "rte_vdpa_get_device_name"?
> 
> 
> 
rte_vdpa_get_device_name may be prefered to avoid confusion with the
socket name.

Thanks,
Maxime