DPDK  16.11.11
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.
49  *
50  * Refer to the guidelines document in the docs subdirectory for details on the
51  * use of these macros
52  */
53 
54 /*
55  * Macro Parameters:
56  * b - function base name
57  * e - function version extension, to be concatenated with base name
58  * n - function symbol version string to be applied
59  * f - function prototype
60  * p - full function symbol name
61  */
62 
63 /*
64  * VERSION_SYMBOL
65  * Creates a symbol version table entry binding symbol <b>@DPDK_<n> to the internal
66  * function name <b>_<e>
67  */
68 #define VERSION_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@DPDK_" RTE_STR(n))
69 
70 /*
71  * BIND_DEFAULT_SYMBOL
72  * Creates a symbol version entry instructing the linker to bind references to
73  * symbol <b> to the internal symbol <b>_<e>
74  */
75 #define BIND_DEFAULT_SYMBOL(b, e, n) __asm__(".symver " RTE_STR(b) RTE_STR(e) ", " RTE_STR(b) "@@DPDK_" RTE_STR(n))
76 #define __vsym __attribute__((used))
77 
78 /*
79  * MAP_STATIC_SYMBOL
80  * If a function has been bifurcated into multiple versions, none of which
81  * are defined as the exported symbol name in the map file, this macro can be
82  * used to alias a specific version of the symbol to its exported name. For
83  * example, if you have 2 versions of a function foo_v1 and foo_v2, where the
84  * former is mapped to foo@DPDK_1 and the latter is mapped to foo@DPDK_2 when
85  * building a shared library, this macro can be used to map either foo_v1 or
86  * foo_v2 to the symbol foo when building a static library, e.g.:
87  * MAP_STATIC_SYMBOL(void foo(), foo_v2);
88  */
89 #define MAP_STATIC_SYMBOL(f, p)
90 
91 #else
92 /*
93  * No symbol versioning in use
94  */
95 #define VERSION_SYMBOL(b, e, n)
96 #define __vsym
97 #define BIND_DEFAULT_SYMBOL(b, e, n)
98 #define MAP_STATIC_SYMBOL(f, p) f __attribute__((alias(RTE_STR(p))))
99 /*
100  * RTE_BUILD_SHARED_LIB=n
101  */
102 #endif
103 
104 
105 #endif /* _RTE_COMPAT_H_ */