From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 27885C4FA for ; Thu, 25 Jun 2015 13:35:49 +0200 (CEST) Received: from hmsreliant.think-freely.org ([2001:470:8:a08:7aac:c0ff:fec2:933b] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1Z85RU-0000FZ-S0; Thu, 25 Jun 2015 07:35:47 -0400 Date: Thu, 25 Jun 2015 07:35:33 -0400 From: Neil Horman To: Thomas Monjalon Message-ID: <20150625113533.GA17026@hmsreliant.think-freely.org> References: <1435088014-18973-1-git-send-email-nhorman@tuxdriver.com> <1435170885-17643-1-git-send-email-nhorman@tuxdriver.com> <1435170885-17643-2-git-send-email-nhorman@tuxdriver.com> <4632196.zdulcdXT2t@xps13> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4632196.zdulcdXT2t@xps13> User-Agent: Mutt/1.5.23 (2014-03-12) X-Spam-Score: -2.9 (--) X-Spam-Status: No Cc: dev@dpdk.org Subject: Re: [dpdk-dev] [PATCHv2 2/2] ABI: Add some documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 25 Jun 2015 11:35:49 -0000 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 >