[1/2] doc: announce rte_dev_probe() API change

  In order to simplify the use of rte_dev_probe() and
rte_dev_remove() by applications, rte_dev_probe() will
return a reference on the rte_device stating DPDK v20.11.

Signed-off-by: Maxime Coquelin <maxime.coquelin@redhat.com>
---
 doc/guides/rel_notes/deprecation.rst | 5 +++++
 1 file changed, 5 insertions(+)
  

On 08/06/20 17:53 +0200, Maxime Coquelin wrote:
> In order to simplify the use of rte_dev_probe() and
> rte_dev_remove() by applications, rte_dev_probe() will
> return a reference on the rte_device stating DPDK v20.11.
> 
> Signed-off-by: Maxime Coquelin <maxime.coquelin@redhat.com>
> ---
>  doc/guides/rel_notes/deprecation.rst | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index 0bee924255..47151eac0b 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -138,3 +138,8 @@ Deprecation Notices
>    driver probe scheme. The legacy virtio support will be available through
>    the existing VFIO/UIO based kernel driver scheme.
>    More details at https://patches.dpdk.org/patch/69351/

On the principle ok, formulation seems heavy though (but I'm not a
native speaker so ymmv...):

> +
> +* eal: Change ``rte_dev_probe`` API to return a pointer on the probed
> +  rte_device or NULL instead of 0 or an error code in DPDK v20.11.

The 'in DPDK v20.11' is confusing here (it could equally apply to first
or second part of the sentence). Given the context it's obvious, but
maybe:

Change ``rte_dev_probe`` API in DPDK v20.11 to return a pointer on ...

> +                                                                   This
> +  change will help calling application in avoiding to iterate the devices
> +  list when willing to call rte_dev_remove() later.

How about:

   This change will allow applications avoid iterating on devices after a
   probe to get access to the new rte_device.

> -- 
> 2.26.2
>
  

On 6/11/20 10:08 AM, Gaëtan Rivet wrote:
> On 08/06/20 17:53 +0200, Maxime Coquelin wrote:
>> In order to simplify the use of rte_dev_probe() and
>> rte_dev_remove() by applications, rte_dev_probe() will
>> return a reference on the rte_device stating DPDK v20.11.
>>
>> Signed-off-by: Maxime Coquelin <maxime.coquelin@redhat.com>
>> ---
>>  doc/guides/rel_notes/deprecation.rst | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
>> index 0bee924255..47151eac0b 100644
>> --- a/doc/guides/rel_notes/deprecation.rst
>> +++ b/doc/guides/rel_notes/deprecation.rst
>> @@ -138,3 +138,8 @@ Deprecation Notices
>>    driver probe scheme. The legacy virtio support will be available through
>>    the existing VFIO/UIO based kernel driver scheme.
>>    More details at https://patches.dpdk.org/patch/69351/
> 
> On the principle ok, formulation seems heavy though (but I'm not a
> native speaker so ymmv...):
> 
>> +
>> +* eal: Change ``rte_dev_probe`` API to return a pointer on the probed
>> +  rte_device or NULL instead of 0 or an error code in DPDK v20.11.
> 
> The 'in DPDK v20.11' is confusing here (it could equally apply to first
> or second part of the sentence). Given the context it's obvious, but
> maybe:
> 
> Change ``rte_dev_probe`` API in DPDK v20.11 to return a pointer on ...
> 
>> +                                                                   This
>> +  change will help calling application in avoiding to iterate the devices
>> +  list when willing to call rte_dev_remove() later.
> 
> How about:
> 
>    This change will allow applications avoid iterating on devices after a
>    probe to get access to the new rte_device.
> 

Good suggestions, I'll fix that.

Thanks,
Maxime