doc: announce ABI change on eal and kni

  For the purpose of removing instances of rte_panic
from the init sequence, some void functions need to change
to return an error code.The planned modifications of 19.08
require to change one eal function and one kni function.

Signed-off-by: Arnon Warshavsky <arnon@qwilt.com>
---
 doc/guides/rel_notes/deprecation.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)
  

On Sun, 28 Apr 2019 17:58:48 +0300
Arnon Warshavsky <arnon@qwilt.com> wrote:

These deprecation notices are unnecessary. These are not public API's.

> +* eal: Modify function return value for the sake of removing rte_panic
> +       from the init sequence in version 19.08.
> +  - In ``lib/librte_eal/common/eal_thread.h`` replace
> +    ``void eal_thread_init_master(unsigned lcore_id)``
> +    to return ``int``

This function is never exported (see rte_eal_version.map) and therefore be marked private to the EAL, and not a public API.


> +* kni: Modify function return value for the sake of removing rte_panic
> +       from the init sequence in version 19.08.
> +  - In ``lib/librte_kni/rte_kni_fifo.h`` replace
> +    ``static void kni_fifo_init(struct rte_kni_fifo *fifo, unsigned size)``
> +    to return ``int``

This is not a public API really so no deprecation needed.
It is just an include file used internally by library and the driver.
  

On 4/28/2019 5:23 PM, Stephen Hemminger wrote:
> On Sun, 28 Apr 2019 17:58:48 +0300
> Arnon Warshavsky <arnon@qwilt.com> wrote:
> 
> These deprecation notices are unnecessary. These are not public API's.

+1

> 
>> +* eal: Modify function return value for the sake of removing rte_panic
>> +       from the init sequence in version 19.08.
>> +  - In ``lib/librte_eal/common/eal_thread.h`` replace
>> +    ``void eal_thread_init_master(unsigned lcore_id)``
>> +    to return ``int``
> 
> This function is never exported (see rte_eal_version.map) and therefore be marked private to the EAL, and not a public API.
> 
> 
>> +* kni: Modify function return value for the sake of removing rte_panic
>> +       from the init sequence in version 19.08.
>> +  - In ``lib/librte_kni/rte_kni_fifo.h`` replace
>> +    ``static void kni_fifo_init(struct rte_kni_fifo *fifo, unsigned size)``
>> +    to return ``int``
> 
> This is not a public API really so no deprecation needed.
> It is just an include file used internally by library and the driver.
>
  

On Mon, 29 Apr 2019 10:28:36 +0100
Ferruh Yigit <ferruh.yigit@intel.com> wrote:

> > 
> >   
> >> +* kni: Modify function return value for the sake of removing rte_panic
> >> +       from the init sequence in version 19.08.
> >> +  - In ``lib/librte_kni/rte_kni_fifo.h`` replace
> >> +    ``static void kni_fifo_init(struct rte_kni_fifo *fifo, unsigned size)``
> >> +    to return ``int``  
> > 
> > This is not a public API really so no deprecation needed.
> > It is just an include file used internally by library and the driver.
> >   

This does introduce the possibility of kernel/library version mismatch.
You might want to add a magic number to shared data structure.
  

On 4/29/2019 5:24 PM, Stephen Hemminger wrote:
> On Mon, 29 Apr 2019 10:28:36 +0100
> Ferruh Yigit <ferruh.yigit@intel.com> wrote:
> 
>>>
>>>   
>>>> +* kni: Modify function return value for the sake of removing rte_panic
>>>> +       from the init sequence in version 19.08.
>>>> +  - In ``lib/librte_kni/rte_kni_fifo.h`` replace
>>>> +    ``static void kni_fifo_init(struct rte_kni_fifo *fifo, unsigned size)``
>>>> +    to return ``int``  
>>>
>>> This is not a public API really so no deprecation needed.
>>> It is just an include file used internally by library and the driver.
>>>   
> 
> This does introduce the possibility of kernel/library version mismatch.
> You might want to add a magic number to shared data structure.
> 

Changing 'kni_fifo_init()' return type shouldn't be a problem at all,
perhaps it would be a problem if the content of the fifo changed but it is not
the case.
  

>
>
> Changing 'kni_fifo_init()' return type shouldn't be a problem at all,
> perhaps it would be a problem if the content of the fifo changed but it is
> not
> the case.
>

Should I move this patch to deferred or reject?
  

07/05/2019 11:57, Arnon Warshavsky:
> >
> >
> > Changing 'kni_fifo_init()' return type shouldn't be a problem at all,
> > perhaps it would be a problem if the content of the fifo changed but it is
> > not
> > the case.
> >
> 
> Should I move this patch to deferred or reject?

It can be set to "rejected".

I am preparing a deprecation notice for rte_eal_remote_launch
and rte_metrics_init.
  

>
>
>
> I am preparing a deprecation notice for rte_eal_remote_launch
> and rte_metrics_init.
>
>
> hmm, I followed panic and not exit, so missed rte_metrics_init.
rte_eal_remote_launch currently returns int. what deprecation goes there?
  

08/05/2019 22:22, Arnon Warshavsky:
> > I am preparing a deprecation notice for rte_eal_remote_launch
> > and rte_metrics_init.
> >
> hmm, I followed panic and not exit, so missed rte_metrics_init.
> rte_eal_remote_launch currently returns int. what deprecation goes there?

We probably need to add a new error code for rte_eal_remote_launch.
It is just a doxygen change, but it is part of the API.