lib/librte_compat/rte_compat.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2015 Neil Horman <nhorman@tuxdriver.com>.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *
  18  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 #ifndef _RTE_COMPAT_H_
  32 #define _RTE_COMPAT_H_
  33 #include <rte_common.h>
  34
  35 #ifdef RTE_BUILD_SHARED_LIB
  36
  37 /*
  38  * Provides backwards compatibility when updating exported functions.
  39  * When a symol is exported from a library to provide an API, it also provides a
  40  * calling convention (ABI) that is embodied in its name, return type,
  41  * arguments, etc.  On occasion that function may need to change to accommodate
  42  * new functionality, behavior, etc.  When that occurs, it is desireable to
  43  * allow for backwards compatibility for a time with older binaries that are
  44  * dynamically linked to the dpdk.  To support that, the __vsym and
  45  * VERSION_SYMBOL macros are created.  They, in conjunction with the
  46  * <library>_version.map file for a given library allow for multiple versions of
  47  * a symbol to exist in a shared library so that older binaries need not be
  48  * immediately recompiled. Their use is outlined in the following example:
  49  * Assumptions: DPDK 2.(X) contains a function int foo(char *string)
  50  *              DPDK 2.(X+1) needs to change foo to be int foo(int index)
  51  *
  52  * To accomplish this:
  53  * 1) Edit lib/<library>/library_version.map to add a DPDK_2.(X+1) node, in which
  54  * foo is exported as a global symbol.
  55  *
  56  * 2) rename the existing function int foo(char *string) to
  57  *      int __vsym foo_v20(char *string)
  58  *
  59  * 3) Add this macro immediately below the function
  60  *      VERSION_SYMBOL(foo, _v20, 2.0);
  61  *
  62  * 4) Implement a new version of foo.
  63  *      char foo(int value, int otherval) { ...}
  64  *
  65  * 5) Mark the newest version as the default version
  66  *      BIND_DEFAULT_SYMBOL(foo, 2.1);
  67  *
  68  */
  69
  70 /*
  71  * Macro Parameters:
  72  * b - function base name
  73  * e - function version extension, to be concatenated with base name
  74  * n - function symbol version string to be applied
  75  */
  76
  77 /*
  78  * VERSION_SYMBOL
  79  * Creates a symbol version table entry binding symbol <b>@DPDK_<n> to the internal
  80  * function name <b>_<e>
  81  */
  82 #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", "RTE_STR(b)"@DPDK_"RTE_STR(n))
  83
  84 /*
  85  * BASE_SYMBOL
  86  * Creates a symbol version table entry binding unversioned symbol <b>
  87  * to the internal function <b>_<e>
  88  */
  89 #define BASE_SYMBOL(b, e) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", "RTE_STR(b)"@")
  90
  91 /*
  92  * BNID_DEFAULT_SYMBOL
  93  * Creates a symbol version entry instructing the linker to bind references to
  94  * symbol <b> to the internal symbol <b>_<e>
  95  */
  96 #define BIND_DEFAULT_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", "RTE_STR(b)"@@DPDK_"RTE_STR(n))
  97 #define __vsym __attribute__((used))
  98
  99 #else
 100 /*
 101  * No symbol versioning in use
 102  */
 103 #define VERSION_SYMBOL(b, e, v)
 104 #define __vsym
 105 #define BASE_SYMBOL(b, n)
 106 #define BIND_DEFAULT_SYMBOL(b, v)
 107
 108 /*
 109  * RTE_BUILD_SHARED_LIB=n
 110  */
 111 #endif
 112
 113
 114 #endif /* _RTE_COMPAT_H_ */