[PATCH] doc: announce ABI change for mbuf structure

[PATCH] doc: announce ABI change for mbuf structure

[Olivier Matz]

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@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.
-- 
2.8.1

Re: [PATCH] doc: announce ABI change for mbuf structure

[Bruce Richardson]

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@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?

/Bruce

Re: [PATCH] doc: announce ABI change for mbuf structure

[Olivier Matz]

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@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.


Thanks,
Olivier

Re: [PATCH] doc: announce ABI change for mbuf structure

[Richardson, Bruce]

> -----Original Message-----
> From: Olivier Matz [mailto:olivier.matz@6wind.com]
> Sent: Tuesday, July 19, 2016 4:04 PM
> To: Richardson, Bruce <bruce.richardson@intel.com>
> Cc: dev@dpdk.org; jerin.jacob@caviumnetworks.com;
> thomas.monjalon@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@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".

/Bruce

Re: [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@6wind.com]
>> Sent: Tuesday, July 19, 2016 4:04 PM
>> To: Richardson, Bruce <bruce.richardson@intel.com>
>> Cc: dev@dpdk.org; jerin.jacob@caviumnetworks.com;
>> thomas.monjalon@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@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.

[PATCH v2] doc: announce ABI change for mbuf structure

[Olivier Matz]

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@6wind.com>
---

v1->v2:
- reword the sentences to keep things more open, as suggested by Bruce

 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..b9f5a93 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
+  may be reordered to facilitate the writing of ``data_off``, ``refcnt``, and
+  ``nb_segs`` in one operation, because some platforms have an overhead if the
+  store address is not naturally aligned. Other mbuf fields, such as the
+  ``port`` field, may be moved or removed as part of this mbuf work.
-- 
2.8.1

Re: [PATCH v2] doc: announce ABI change for mbuf structure

[Ferruh Yigit]

On 7/20/2016 8:16 AM, 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@6wind.com>
> ---
> 
> v1->v2:
> - reword the sentences to keep things more open, as suggested by Bruce
> 
>  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..b9f5a93 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
> +  may be reordered to facilitate the writing of ``data_off``, ``refcnt``, and
> +  ``nb_segs`` in one operation, because some platforms have an overhead if the
> +  store address is not naturally aligned. Other mbuf fields, such as the
> +  ``port`` field, may be moved or removed as part of this mbuf work.
> 

Not directly related to this patch, but generally for deprecation
notices, does it make sense to tag explicitly which library effected, like:

* librte_mbuf [perhaps with version here]:
  Explanation about deprecation ...

For this case it is more clear which library effected, but sometimes
that is not obvious from deprecation notice.

Also when checked for if specific library effected, it is harder to find
with current notes.

Thanks,
ferruh

Re: [PATCH v2] doc: announce ABI change for mbuf structure

[Thomas Monjalon]

> 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@6wind.com>

Acked-by: Thomas Monjalon <thomas.monjalon@6wind.com>

Re: [PATCH v2] doc: announce ABI change for mbuf structure

[Ananyev, Konstantin]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Olivier Matz
> Sent: Wednesday, July 20, 2016 8:16 AM
> To: dev@dpdk.org
> Cc: jerin.jacob@caviumnetworks.com; thomas.monjalon@6wind.com; Richardson, Bruce <bruce.richardson@intel.com>
> Subject: [dpdk-dev] [PATCH v2] doc: announce ABI change for mbuf structure
> 
> 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@6wind.com>
> ---
> 
> v1->v2:
> - reword the sentences to keep things more open, as suggested by Bruce
> 
>  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..b9f5a93 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
> +  may be reordered to facilitate the writing of ``data_off``, ``refcnt``, and
> +  ``nb_segs`` in one operation, because some platforms have an overhead if the
> +  store address is not naturally aligned. Other mbuf fields, such as the
> +  ``port`` field, may be moved or removed as part of this mbuf work.
> --

Acked-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
> 2.8.1

Re: [PATCH v2] doc: announce ABI change for mbuf structure

[John Daley (johndale)]

> 
> 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@6wind.com>
> ---

Acked-by: John Daley <johndale@cisco.com>

Also, definitely +1 on trying to get m->next into the first cache line.

Re: [PATCH v2] doc: announce ABI change for mbuf structure

[Jerin Jacob]

On Wed, Jul 20, 2016 at 09:16:14AM +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@6wind.com>
Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>

Re: [PATCH v2] doc: announce ABI change for mbuf structure

[Thomas Monjalon]

> > 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@6wind.com>
> 
> Acked-by: Thomas Monjalon <thomas.monjalon@6wind.com>
Acked-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
Acked-by: John Daley <johndale@cisco.com>
Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>

Applied, thanks