From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wg0-f53.google.com (mail-wg0-f53.google.com [74.125.82.53]) by dpdk.org (Postfix) with ESMTP id C6473C49C for ; Wed, 24 Jun 2015 23:10:35 +0200 (CEST) Received: by wgqq4 with SMTP id q4so46498398wgq.1 for ; Wed, 24 Jun 2015 14:10:35 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:organization :user-agent:in-reply-to:references:mime-version :content-transfer-encoding:content-type; bh=dYbsahxZdCPDyawFAWaqq/VGQ0GUS0jir9do0Tz7qCU=; b=IfbQMuaYN+GzNKR8CM+4SjLHZjA/3jiI5dcl8pTswlClqIFLNcjEimYhvsMAYEzYNN DcDO9ub4bAxiSlCS2rkarpGtmXV8sh+CAgWV9g/FzJlBLk+8uMgt7PmMD03PHBUI9zH/ XygqcN7gt+3Lt4sn5vJ5mB+NvfNIVg8R7BMKS/0HcpxktK5w5RnMwTi2245qTmyL4dj5 wO9T9E6meuYiS8cj1ozObZeSf44a9rdS6hbJHo6SvovV3qztORn1nYQ3hL8BVrU8I4O7 scrbgx2WSJySHDLouFIdqgXePg5xD9835AGWWKx1MMxVzjUeI1HW4gHwKrCAhv74YUHv J0hw== X-Gm-Message-State: ALoCoQnCVCCE6gcZOb3ZBLaHxwGgabmMjBQnZAiLZ8wNSV2oT/lca/cy1rzMwlqGBH2juLEjBueI X-Received: by 10.194.184.79 with SMTP id es15mr71221462wjc.112.1435180235651; Wed, 24 Jun 2015 14:10:35 -0700 (PDT) Received: from xps13.localnet (136-92-190-109.dsl.ovh.fr. [109.190.92.136]) by mx.google.com with ESMTPSA id ei8sm42514412wjd.32.2015.06.24.14.10.34 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 24 Jun 2015 14:10:34 -0700 (PDT) From: Thomas Monjalon To: Neil Horman Date: Wed, 24 Jun 2015 23:09:29 +0200 Message-ID: <4632196.zdulcdXT2t@xps13> Organization: 6WIND User-Agent: KMail/4.14.8 (Linux/4.0.4-2-ARCH; KDE/4.14.8; x86_64; ; ) In-Reply-To: <1435170885-17643-2-git-send-email-nhorman@tuxdriver.com> 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> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" 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: Wed, 24 Jun 2015 21:10:36 -0000 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. [...] > +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. > +* ``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. > + 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/? [...] > +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? [...] > +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. When do we need to use BASE_SYMBOL? [...] > +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? > +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. As you copy a part of abi.rst, it should be removed from the original doc. Thanks Neil