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

["Richardson, Bruce" <bruce.richardson@intel.com>]

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