2015-06-25 07:35, Neil Horman:
> On Wed, Jun 24, 2015 at 11:09:29PM +0200, Thomas Monjalon wrote:
> > 2015-06-24 14:34, Neil Horman:
> > > +Some ABI changes may be too significant to reasonably maintain multiple
> > > +versions. In those cases ABI's may be updated without backward
> > > compatibility
> > > +being provided. The requirements for doing so are:
> > > +
> > > +#. At least 3 acknowledgments of the need to do so must be made on the
> > > + dpdk.org mailing list.
> > > +
> > > +#. A full deprecation cycle, as explained above, must be made to offer
> > > + downstream consumers sufficient warning of the change.
> > > +
> > > +#. The ``LIBABIVER`` variable in the makefile(s) where the ABI changes
> > > are
> > > + incorporated must be incremented in parallel with the ABI changes
> > > + themselves.
> >
> > The proposal was to provide the old and the new ABI in the same source code
> > during the deprecation cycle. The old ABI would be the default and people
> > can build the new one by enabling the NEXT_ABI config option.
> > So the migration to the new ABI is smoother.
>
> Yes....I'm not sure what you're saying here. The ABI doesn't 'Change' until
> the
> old ABI is removed (i.e. old applications are forced to adopt a new ABI), and
> so
> LIBABIVER has to be updated in parallel with that removal
I'm referring to previous threads suggesting a NEXT_ABI build option to be able
to build the old (default) ABI or the next one.
So the LIBABIVER and .map file would depend of enabling NEXT_ABI or not:
http://dpdk.org/ml/archives/dev/2015-June/019147.html
http://dpdk.org/ml/archives/dev/2015-June/019784.html
http://dpdk.org/ml/archives/dev/2015-June/019810.html
> > [...]
> > > +The macros exported are:
> > > +
> > > +* ``VERSION_SYMBOL(b, e, n)``: Creates a symbol version table entry
> > > binding
> > > + unversioned symbol ``b`` to the internal function ``b_e``.
> >
> > The definition is the same as BASE_SYMBOL.
> >
> No, they're different. VERSION_SYMBOL is defined as:
> VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", "
> RTE_STR(b) "@DPDK_" RTE_STR(n))
>
> while BASE_SYMBOL is
> #define BASE_SYMBOL(b, e) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", "
> RTE_STR(b)"@")
Yes. I mean the comments are the same, so don't reflect the difference.
> > [...]
> > > + DPDK_2.0 {
> > > + global:
> > > +
> > > + rte_acl_add_rules;
> > > + rte_acl_build;
> > > + rte_acl_classify;
> > > + rte_acl_classify_alg;
> > > + rte_acl_classify_scalar;
> > > + rte_acl_create;
> >
> > So it's declared twice, right?
> > I think it should be explicit.
> >
> Yes, its listed once for each version node, so 2 delcarations. I thought that
> was made explicit by the use of the code block. What else would you like to
> see?
I think you should say it explicitly in the comment below the block.
> > > + rte_acl_dump;
> > > + rte_acl_find_existing;
> > > + rte_acl_free;
> > > + rte_acl_ipv4vlan_add_rules;
> > > + rte_acl_ipv4vlan_build;
> > > + rte_acl_list_dump;
> > > + rte_acl_reset;
> > > + rte_acl_reset_rules;
> > > + rte_acl_set_ctx_classify;
> > > +
> > > + local: *;
> > > + };
> > > +
> > > + DPDK_2.1 {
> > > + global:
> > > + rte_acl_create;
> > > +
> > > + } DPDK_2.0;
> > [...]
> > > +the macros used for versioning symbols. That is our next step, mapping
> > > this new
> > > +symbol name to the initial symbol name at version node 2.0. Immediately
> > > after
> > > +the function, we add this line of code
> > > +
> > > +.. code-block:: c
> > > +
> > > + VERSION_SYMBOL(rte_acl_create, _v20, 2.0);
> >
> > Can it be declared before the function?
> >
> Strictly speaking yes, though its a bit odd from a sylistic point to declare
> versioned aliases for a symbol prior to defining the symbol itself (its like a
> forward declaration)
It allows to declare it near the function header.
> > When do we need to use BASE_SYMBOL?
> >
> For our purposes you currently don't, because there are no unversioned symbols
> in DPDK (since we use a map file). I've just included it here for
> completeness
> in the header file should it ever be needed in the future.
If it can be useful, please integrate a note to explain when it should be used.
> > [...]
> > > +This code serves as our new API call. Its the same as our old call, but
> > > adds
> > > +the new parameter in place. Next we need to map this function to the
> > > symbol
> > > +``rte_acl_create at DPDK_2.1``. To do this, we modify the public
> > > prototype of the call
> > > +in the header file, adding the macro there to inform all including
> > > applications,
> > > +that on re-link, the default rte_acl_create symbol should point to this
> > > +function. Note that we could do this by simply naming the function above
> > > +rte_acl_create, and the linker would chose the most recent version tag
> > > to apply
> > > +in the version script, but we can also do this in the header file
> > > +
> > > +.. code-block:: c
> > > +
> > > + struct rte_acl_ctx *
> > > + -rte_acl_create(const struct rte_acl_param *param);
> > > + +rte_acl_create(const struct rte_acl_param *param, int debug);
> > > + +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 2.1);
> >
> > Will it work with static library?
> >
> hmm, this example in particular? No, I didn't think of that. To work with a
> static build, you still need to define the unversioned symbol. Thats easy
> enough to do though, by either defining rte_acl_create as a public api and
> calling the appropriate versioned function, or by creating a macro to point to
> the right version via an alias. I can fix that easily enough.
Yes please, static libraries are really important in DPDK.
