From: Neil Horman <nhorman@tuxdriver.com>
To: Thomas Monjalon <thomas.monjalon@6wind.com>
Cc: dev@dpdk.org
Subject: Re: [dpdk-dev] [PATCHv2 2/2] ABI: Add some documentation
Date: Thu, 25 Jun 2015 07:35:33 -0400 [thread overview]
Message-ID: <20150625113533.GA17026@hmsreliant.think-freely.org> (raw)
In-Reply-To: <4632196.zdulcdXT2t@xps13>
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
>
> [...]
> > +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)"@")
> > +* ``BASE_SYMBOL(b, e)``: Creates a symbol version table entry binding
> > + unversioned symbol ``b`` to the internal function ``b_e``.
>
>
> [...]
> > + 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?
> > + 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;
>
> [...]
> > +Note that the base name of the symbol was kept in tact, as this is condusive to
>
> s/in tact/intact/?
>
Hmm, thats odd, aspell explicitly changed that. Though your right, it should be
intact. I'll fix it.
> [...]
> > +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)
> [...]
> > +Remembering to also add the rte_compat.h header to the requisite c file where
> > +these changes are being made. The above macro instructs the linker to create a
> > +new symbol ``rte_acl_create@DPDK_2.0``, which matches the symbol created in older
> > +builds, but now points to the above newly named function. We have now mapped
> > +the original rte_acl_create symbol to the original function (but with a new
> > +name)
>
> Could we use VERSION_SYMBOL(rte_acl_create, , 2.0);
> when introducing the function in DPDK 2.0 (before any ABI breakage)?
> It could help to generate the .map file.
>
I've honestly not tried. I think its possible, but the example you give above I
don't think will work, because it will result in an error indicating
rte_acl_create is declared twice. You would have to rename rte_acl_create to
something uniqe prior to versioning it.
> 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.
> [...]
> > +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@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.
> > +Next remove the corresponding versioned export
> > +.. code-block:: c
> > +
> > + -VERSION_SYMBOL(rte_acl_create, _v20, 2.0);
> > +
> > +
> > +Note that the internal function definition could also be removed, but its used
> > +in our example by the newer version _v21, so we leave it in place. This is a
> > +coding style choice.
> > +
> > +Lastly, we need to bump the LIBABIVER number for this library in the Makefile to
> > +indicate to applications doing dynamic linking that this is a later, and
> > +possibly incompatible library version:
> > +
> > +.. code-block:: c
> > +
> > + -LIBABIVER := 1
> > + +LIBABIVER := 2
>
> Very well explained, thanks.
>
> [...]
> > + rte_acl_add_rules;
> > + rte_acl_build;
> > + rte_acl_classify;
> > + rte_acl_classify_alg;
> > + rte_acl_classify_scalar;
> > + rte_acl_dump;
> > + rte_acl_create
>
> Not in alphabetical order.
>
No, none of them are, but that can be adjusted, though I'd like to do that
separately from this documentation.
>
> As you copy a part of abi.rst, it should be removed from the original doc.
>
Sure
> Thanks Neil
>
next prev parent reply other threads:[~2015-06-25 11:35 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-06-23 19:33 [dpdk-dev] [PATCH 1/2] rte_compat.h : Clean up some typos Neil Horman
2015-06-23 19:33 ` [dpdk-dev] [PATCH 2/2] ABI: Add some documentation Neil Horman
2015-06-24 11:21 ` Mcnamara, John
2015-06-24 11:23 ` [dpdk-dev] [PATCH 1/2] rte_compat.h : Clean up some typos Mcnamara, John
2015-06-24 18:06 ` Neil Horman
2015-06-24 18:34 ` [dpdk-dev] [PATCHv2 " Neil Horman
2015-06-24 18:34 ` [dpdk-dev] [PATCHv2 2/2] ABI: Add some documentation Neil Horman
2015-06-24 21:09 ` Thomas Monjalon
2015-06-25 11:35 ` Neil Horman [this message]
2015-06-25 13:22 ` Thomas Monjalon
2015-06-25 7:19 ` Zhang, Helin
2015-06-25 7:42 ` Gonzalez Monroy, Sergio
2015-06-25 8:00 ` Gonzalez Monroy, Sergio
2015-06-25 12:25 ` Neil Horman
2015-06-29 16:35 ` [dpdk-dev] [PATCH] lib: remove redundant definition of local symbols Thomas Monjalon
2015-06-30 15:50 ` Thomas Monjalon
2015-06-24 19:41 ` [dpdk-dev] [PATCHv2 1/2] rte_compat.h : Clean up some typos Thomas Monjalon
2015-06-24 20:15 ` Neil Horman
2015-06-24 20:49 ` Thomas Monjalon
2015-06-25 7:37 ` [dpdk-dev] [PATCH " Gajdzica, MaciejX T
2015-06-25 12:28 ` Neil Horman
2015-06-25 14:35 ` [dpdk-dev] [PATCHv3 1/3] " Neil Horman
2015-06-25 14:35 ` [dpdk-dev] [PATCHv3 2/3] rte_compat: Add MAP_STATIC_SYMBOL macro Neil Horman
2015-06-26 10:13 ` Gajdzica, MaciejX T
2015-06-26 12:52 ` Thomas Monjalon
2015-06-26 14:30 ` Neil Horman
2015-06-28 20:13 ` Thomas Monjalon
2015-06-29 13:44 ` Neil Horman
2015-06-25 14:35 ` [dpdk-dev] [PATCHv3 3/3] ABI: Add some documentation Neil Horman
2015-06-26 13:00 ` Thomas Monjalon
2015-06-26 14:54 ` Neil Horman
2015-06-28 20:24 ` Thomas Monjalon
2015-06-29 13:53 ` Neil Horman
2015-06-26 12:45 ` [dpdk-dev] [PATCHv3 1/3] rte_compat.h : Clean up some typos Thomas Monjalon
2015-06-29 13:59 ` [dpdk-dev] [PATCHv4 1/4] " Neil Horman
2015-06-29 13:59 ` [dpdk-dev] [PATCHv4 2/4] rte_compat: Add MAP_STATIC_SYMBOL macro Neil Horman
2015-06-29 13:59 ` [dpdk-dev] [PATCHv4 3/4] rte_compat: remove BASE_SYMBOL Neil Horman
2015-06-29 13:59 ` [dpdk-dev] [PATCHv4 4/4] ABI: Add some documentation Neil Horman
2015-06-29 15:07 ` Thomas Monjalon
2015-07-08 9:52 ` [dpdk-dev] [PATCHv4 1/4] rte_compat.h : Clean up some typos Thomas Monjalon
2015-07-08 11:04 ` Neil Horman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20150625113533.GA17026@hmsreliant.think-freely.org \
--to=nhorman@tuxdriver.com \
--cc=dev@dpdk.org \
--cc=thomas.monjalon@6wind.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).