4 * Copyright(c) 2015 Neil Horman <nhorman@tuxdriver.com>.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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
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.
31 #ifndef _RTE_COMPAT_H_
32 #define _RTE_COMPAT_H_
33 #include <rte_common.h>
35 #ifdef RTE_BUILD_SHARED_LIB
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)
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.
56 * 2) rename the existing function int foo(char *string) to
57 * int __vsym foo_v20(char *string)
59 * 3) Add this macro immediately below the function
60 * VERSION_SYMBOL(foo, _v20, 2.0);
62 * 4) Implement a new version of foo.
63 * char foo(int value, int otherval) { ...}
65 * 5) Mark the newest version as the default version
66 * BIND_DEFAULT_SYMBOL(foo, 2.1);
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
79 * Creates a symbol version table entry binding symbol <b>@DPDK_<n> to the internal
80 * function name <b>_<e>
82 #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", "RTE_STR(b)"@DPDK_"RTE_STR(n))
86 * Creates a symbol version table entry binding unversioned symbol <b>
87 * to the internal function <b>_<e>
89 #define BASE_SYMBOL(b, e) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", "RTE_STR(b)"@")
93 * Creates a symbol version entry instructing the linker to bind references to
94 * symbol <b> to the internal symbol <b>_<e>
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))
101 * No symbol versioning in use
103 #define VERSION_SYMBOL(b, e, v)
105 #define BASE_SYMBOL(b, n)
106 #define BIND_DEFAULT_SYMBOL(b, v)
109 * RTE_BUILD_SHARED_LIB=n
114 #endif /* _RTE_COMPAT_H_ */