[dpdk-dev] [PATCH] doc: announce ABI change for mbuf structure

[Olivier Matz]

On 07/19/2016 05:07 PM, Richardson, Bruce wrote:
> 
> 
>> -----Original Message-----
>> From: Olivier Matz [mailto:olivier.matz at 6wind.com]
>> Sent: Tuesday, July 19, 2016 4:04 PM
>> To: Richardson, Bruce <bruce.richardson at intel.com>
>> Cc: dev at dpdk.org; jerin.jacob at caviumnetworks.com;
>> thomas.monjalon at 6wind.com
>> Subject: Re: [dpdk-dev] [PATCH] doc: announce ABI change for mbuf
>> structure
>>
>> Hi Bruce,
>>
>> On 07/19/2016 04:40 PM, Bruce Richardson wrote:
>>> On Tue, Jul 19, 2016 at 04:01:15PM +0200, Olivier Matz wrote:
>>>> For 16.11, the mbuf structure will be modified implying ABI breakage.
>>>> Some discussions already took place here:
>>>> http://www.dpdk.org/dev/patchwork/patch/12878/
>>>>
>>>> Signed-off-by: Olivier Matz <olivier.matz at 6wind.com>
>>>> ---
>>>>  doc/guides/rel_notes/deprecation.rst | 6 ++++++
>>>>  1 file changed, 6 insertions(+)
>>>>
>>>> diff --git a/doc/guides/rel_notes/deprecation.rst
>>>> b/doc/guides/rel_notes/deprecation.rst
>>>> index f502f86..2245bc2 100644
>>>> --- a/doc/guides/rel_notes/deprecation.rst
>>>> +++ b/doc/guides/rel_notes/deprecation.rst
>>>> @@ -41,3 +41,9 @@ Deprecation Notices
>>>>  * The mempool functions for single/multi producer/consumer are
>> deprecated and
>>>>    will be removed in 16.11.
>>>>    It is replaced by rte_mempool_generic_get/put functions.
>>>> +
>>>> +* ABI changes are planned for 16.11 in the ``rte_mbuf`` structure:
>>>> +some
>>>> +  fields will be reordered to facilitate the writing of
>>>> +``data_off``,
>>>> +  ``refcnt``, and ``nb_segs`` in one operation. Indeed, some
>>>> +platforms
>>>> +  have an overhead if the store address is not naturally aligned.
>>>> +The
>>>> +  useless ``port`` field will also be removed at the same occasion.
>>>> --
>>>
>>> Have we fully bottomed out on the mbuf changes. I'm not sure that once
>>> patches start getting considered for merge, new opinions may come
>>> forward. For instance, is the "port" field really "useless"?
>>>
>>> Would it not be better to put in a less specific deprecation notice?
>>> What happens if this notice goes in and the final changes are
>>> different from those called out here?
>>
>> Yes, you are right. What about the following text?
>>
>> ABI changes are planned for 16.11 in the ``rte_mbuf`` structure: some
>> fields may be reordered to facilitate the writing of ``data_off``,
>> ``refcnt``, and ``nb_segs`` in one operation. Indeed, some platforms have
>> an overhead if the store address is not naturally aligned. The ``port``
>> field may also be removed at the same occasion.
>>
> Better. Two suggestions:
> 1. change "Indeed" to "because" and join the sentences.
> 2. change the last sentence to be even more general: "Other mbuf fields, such as the port field, may be moved or removed as part of this mbuf work".

It's much better indeed ;)
Thanks Bruce, I'll submit a v2.