[dpdk-dev,v3,7/7] abi: announce mbuf addition for ieee1588 in DPDK 2.2

Add announcement of a dedicated additional field in the mbuf
to support ieee1588 in DPDK 2.2.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
---
 doc/guides/rel_notes/abi.rst | 5 +++++
 1 file changed, 5 insertions(+)
  

2015-07-02 16:16, John McNamara:
> --- a/doc/guides/rel_notes/abi.rst
> +++ b/doc/guides/rel_notes/abi.rst
>  Deprecation Notices
>  -------------------
> +
> +* In DPDK 2.1 the IEEE1588/802.1AS support in the i40e driver makes use of the
> +  ``udata64`` field in the mbuf to pass the timesync register index to the
> +  user. In DPDK 2.2 this will be moved to a new field in the mbuf.

We need more acknowledgements for this decision, as stated here:
http://dpdk.org/browse/dpdk/tree/doc/guides/guidelines/versioning.rst#n51
  

On Mon, Jul 06, 2015 at 03:16:01PM +0200, Thomas Monjalon wrote:
> 2015-07-02 16:16, John McNamara:
> > --- a/doc/guides/rel_notes/abi.rst
> > +++ b/doc/guides/rel_notes/abi.rst
> >  Deprecation Notices
> >  -------------------
> > +
> > +* In DPDK 2.1 the IEEE1588/802.1AS support in the i40e driver makes use of the
> > +  ``udata64`` field in the mbuf to pass the timesync register index to the
> > +  user. In DPDK 2.2 this will be moved to a new field in the mbuf.
> 
> We need more acknowledgements for this decision, as stated here:
> http://dpdk.org/browse/dpdk/tree/doc/guides/guidelines/versioning.rst#n51

Why can't this new field just be added at the end of cache line 1 (the second
cache line) of the mbuf? That would avoid any ABI breakage and would mean we
can just put the change in in this release, instead of waiting.

/Bruce
  

2015-07-08 14:10, Bruce Richardson:
> On Mon, Jul 06, 2015 at 03:16:01PM +0200, Thomas Monjalon wrote:
> > 2015-07-02 16:16, John McNamara:
> > > --- a/doc/guides/rel_notes/abi.rst
> > > +++ b/doc/guides/rel_notes/abi.rst
> > >  Deprecation Notices
> > >  -------------------
> > > +
> > > +* In DPDK 2.1 the IEEE1588/802.1AS support in the i40e driver makes use of the
> > > +  ``udata64`` field in the mbuf to pass the timesync register index to the
> > > +  user. In DPDK 2.2 this will be moved to a new field in the mbuf.
> > 
> > We need more acknowledgements for this decision, as stated here:
> > http://dpdk.org/browse/dpdk/tree/doc/guides/guidelines/versioning.rst#n51
> 
> Why can't this new field just be added at the end of cache line 1 (the second
> cache line) of the mbuf? That would avoid any ABI breakage and would mean we
> can just put the change in in this release, instead of waiting.

Are you sure that (because of __rte_cache_aligned) the size of the structure
is never increased with this new field?
Please confirm your opinion.

A comment to explain ABI compatibility in the commit message of the v4 is
also welcome.
  

On Thu, Jul 09, 2015 at 05:51:16PM +0200, Thomas Monjalon wrote:
> 2015-07-08 14:10, Bruce Richardson:
> > On Mon, Jul 06, 2015 at 03:16:01PM +0200, Thomas Monjalon wrote:
> > > 2015-07-02 16:16, John McNamara:
> > > > --- a/doc/guides/rel_notes/abi.rst
> > > > +++ b/doc/guides/rel_notes/abi.rst
> > > >  Deprecation Notices
> > > >  -------------------
> > > > +
> > > > +* In DPDK 2.1 the IEEE1588/802.1AS support in the i40e driver makes use of the
> > > > +  ``udata64`` field in the mbuf to pass the timesync register index to the
> > > > +  user. In DPDK 2.2 this will be moved to a new field in the mbuf.
> > > 
> > > We need more acknowledgements for this decision, as stated here:
> > > http://dpdk.org/browse/dpdk/tree/doc/guides/guidelines/versioning.rst#n51
> > 
> > Why can't this new field just be added at the end of cache line 1 (the second
> > cache line) of the mbuf? That would avoid any ABI breakage and would mean we
> > can just put the change in in this release, instead of waiting.
> 
> Are you sure that (because of __rte_cache_aligned) the size of the structure
> is never increased with this new field?
> Please confirm your opinion.

This is checked at compile time by the test app.

 930 static int
 931 test_mbuf(void)
 932 {
 933         RTE_BUILD_BUG_ON(sizeof(struct rte_mbuf) != RTE_CACHE_LINE_SIZE * 2);
 ....

So if a change does result in an increase the mbuf size, by causing overflow in
either the first or the second cache line, we will get compiler errors in the
build because of it. Therefore, such changes are pretty easy to test by compiling
up on our supported targets.

/Bruce