[dpdk-dev] [PATCHv3 3/3] ABI: Add some documentation

[Thomas Monjalon]

2015-06-26 10:54, Neil Horman:
> On Fri, Jun 26, 2015 at 03:00:17PM +0200, Thomas Monjalon wrote:
> > 2015-06-25 10:35, Neil Horman:
> > > +* ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry binding
> > > +  unversioned symbol ``b`` to the internal function ``b_e``.
> > 
> > Should a versioned symbol <b>@DPDK_<n>
> > 
> Sure.

When fixed, this series can be applied.

> > > +* ``BASE_SYMBOL(b, e)``: Creates a symbol version table entry binding
> > > +  unversioned symbol ``b`` to the internal function ``b_e``.
> > 
> > Please give a use case of BASE_SYMBOL.
> > 
> No, I'd rather remove it if you really insist.  As noted before the way we set
> up the version map files means we currently have no need for this particular
> directive.  I only included it for completeness.  I think an example use in
> light of that fact would only confuse people.  If you're going to draw a line in
> the sand around it, I'll just remove it.

No line in the sand, but it seems better to remove it to avoid confusing people.
ABI compat is already enough difficult to understand ;)

> > [...]
> > > +The addition of the new block tells the linker that a new version node is
> > > +available (DPDK_2.1), which contains the symbol rte_acl_create, and inherits the
> > > +symbols from the DPDK_2.0 node.
> > 
> > which contains the old version of the symbol rte_acl_create
> > 
> I don't understand, is it not obvious that the DPDK_2.0 node contains the 2.0
> version of the symbol and the DPDK_2.1 node contains the 2.1 version of the
> symbol?

Yes it is.
I thought it was needed to insist on the existence of a new symbol while the
old one still exists. Just trying to be didactic.

Hope this documentation will help to unlock the patch series currently
breaking the ABI.