From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wg0-f52.google.com (mail-wg0-f52.google.com [74.125.82.52]) by dpdk.org (Postfix) with ESMTP id CFAFFC628 for ; Thu, 25 Jun 2015 15:25:32 +0200 (CEST) Received: by wgck11 with SMTP id k11so62691480wgc.0 for ; Thu, 25 Jun 2015 06:25:32 -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=j4pBFcIGTkieuZwzO6ZhQDafLHdB9MzZcsAMcQ+GgP4=; b=Mk7tFkqZ4NdyPR7Kb1WKsT+SM2JcpJrRAk2XP/nUPTACNtImZaQWJHW64IgS3AaD26 k9t2dWc7pPhTjgDXD6p6Vz9syhT8BQYi5flc402MnOuqIaeF0MIJZVKaEzMw78PGg42E 76ih7pNML5VFNd6/n86NTE/vS4kmUhrc6XBx3sCVhdvn39NxY+0OjIit6cDiiCIedjyU fJ1rlIos98pc6cLPv4+Fh0oieXQWWX5+JpugnMw2X02MQjMmKiBS/in2JKMYrC2NRGsm wXaX05Vtj5dEJrU0lyLX1O6F4ZeiLoePIUYfMZ6TJQmzgoLwwVzGBIlGh0cV8oLxFo1l egKw== X-Gm-Message-State: ALoCoQk/jAVfX4ueJkIg6q5+TzLV+DFGYMacBuSBrX9JxdekhWTbj9l/8bpjS5zZ23DXN8K8tB7o X-Received: by 10.180.84.170 with SMTP id a10mr5939877wiz.52.1435238732664; Thu, 25 Jun 2015 06:25:32 -0700 (PDT) Received: from xps13.localnet (vis210d.sophia.inria.fr. [193.48.223.210]) by mx.google.com with ESMTPSA id c3sm45673951wja.3.2015.06.25.06.25.30 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 25 Jun 2015 06:25:31 -0700 (PDT) From: Thomas Monjalon To: Neil Horman Date: Thu, 25 Jun 2015 15:22:41 +0200 Message-ID: <2292015.PuzxyQTVl3@xps13> Organization: 6WIND User-Agent: KMail/4.14.8 (Linux/4.0.4-2-ARCH; KDE/4.14.8; x86_64; ; ) In-Reply-To: <20150625113533.GA17026@hmsreliant.think-freely.org> References: <1435088014-18973-1-git-send-email-nhorman@tuxdriver.com> <4632196.zdulcdXT2t@xps13> <20150625113533.GA17026@hmsreliant.think-freely.org> 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: Thu, 25 Jun 2015 13:25:33 -0000 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@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.