1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
/** @file
* IPRT - Runtime Loader Generation.
*/
/*
* Copyright (C) 2008-2025 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
#include <iprt/types.h>
#ifdef RT_RUNTIME_LOADER_GENERATE_BODY_STUBS
# include <iprt/ldr.h>
# include <iprt/log.h>
# include <iprt/once.h>
#endif
/** @defgroup grp_rt_runtime_loader Runtime Loader Generation
* @ingroup grp_rt
*
* How to use this loader generator
*
* This loader generator can be used to generate stub code for loading a shared
* library and its functions at runtime, or for generating a header file with
* the declaration of the loader function and optionally declarations for the
* functions loaded. It should be included in a header file or a C source
* file, after defining certain macros which it makes use of.
*
* To generate the C source code for function proxy stubs and the library
* loader function, you should define the following macros in your source file
* before including this header:
*
* RT_RUNTIME_LOADER_LIB_NAME - the file name of the library to load
* RT_RUNTIME_LOADER_FUNCTION - the name of the loader function
* RT_RUNTIME_LOADER_INSERT_SYMBOLS - a macro containing the names of the
* functions to be loaded, defined in the
* following pattern:
* @code
* #define RT_RUNTIME_LOADER_INSERT_SYMBOLS \
* RT_PROXY_STUB(func_name, ret_type, (long_param_list), (short_param_list)) \
* RT_PROXY_STUB(func_name2, ret_type2, (long_param_list2), (short_param_list2)) \
* RT_PROXY_VARIADIC_STUB(func_name3, ret_type3, (long_param_list3, ...)) \
* ...
* #define func_name3(...) g_pfn_func_name3(__VA_ARGS__)
* @endcode
*
* where long_param_list is a parameter list for declaring the function of the
* form (type1 arg1, type2 arg2, ...) and short_param_list for calling it, of
* the form (arg1, arg2, ...).
*
* To generate the header file, you should define RT_RUNTIME_LOADER_FUNCTION
* and if you wish to generate declarations for the functions you should
* additionally define RT_RUNTIME_LOADER_INSERT_SYMBOLS as above and
* RT_RUNTIME_LOADER_GENERATE_DECLS (without a value) before including this
* file.
*
* @note For functions with a variable number of parameters, this approch is
* clumsy as it requires an additional \#define for each function that
* makes use of the g_pfn_XXX function pointer. See func_name3 in the
* snipped above. Instead, use the VBoxDef2LazyLoad approach.
*
* @deprecated This is deprecated. Use VBoxDef2LazyLoad instead where possible.
* See VBOX_DEF_2_LAZY_LOAD in /Config.kmk,
* src/bldprog/VBoxDef2LazyLoad.cpp and examples in
* src/VBox/Devices/Makefile.kmk and other places.
*
* @{
*/
/** @todo this is far too complicated. A script for generating the files would
* probably be preferable.
*
* bird> An alternative is to generate assembly jump wrappers, this only
* requires the symbol names and prefix. I've done this ages ago when we forked
* the EMX/GCC toolchain on OS/2... It's a wee bit more annoying in x86 PIC/PIE
* mode, but nothing that cannot be dealt with.
*
* Update: This was done years ago. See src/bldprogs/VBoxDef2LazyLoad.cpp and
* VBOX_DEF_2_LAZY_LOAD in /Config.kmk.
*/
/** @todo r=bird: The use of RTR3DECL here is an unresolved issue. */
/** @todo r=bird: The lack of RT_C_DECLS_BEGIN/END is an unresolved issue. Here
* we'll get into trouble if we use the same symbol names as the
* original! */
/** @todo r=bird: The prefix usage here is very confused: RT_RUNTIME_LOADER_XXX,
* RT_PROXY_STUB, etc. */
#ifdef RT_RUNTIME_LOADER_GENERATE_BODY_STUBS
/* The following are the symbols which we need from the library. */
# define RT_PROXY_STUB(function, rettype, signature, shortsig) \
rettype (*g_pfn_ ## function) signature; \
RTR3DECL(rettype) function signature \
{ return g_pfn_ ## function shortsig; }
/* The following are the symbols which correspond to variadic functions
* provided by the library. */
# define RT_PROXY_VARIADIC_STUB(function, rettype, signature) \
rettype (*g_pfn_ ## function) signature;
RT_RUNTIME_LOADER_INSERT_SYMBOLS
# undef RT_PROXY_STUB
# undef RT_PROXY_VARIADIC_STUB
/* Function pointer type for easy casting below. */
typedef void (*PFNRTLDRSHAREDGENERIC)(void);
/* Now comes a table of functions to be loaded from the library. */
typedef struct
{
const char *pszName;
PFNRTLDRSHAREDGENERIC *ppfn;
} RTLDRSHAREDFUNC;
# define RT_PROXY_STUB(function, rettype, signature, shortsig ) { #function , (PFNRTLDRSHAREDGENERIC *)&g_pfn_ ## function } ,
# define RT_PROXY_VARIADIC_STUB(function, rettype, signature) { #function , (PFNRTLDRSHAREDGENERIC *)&g_pfn_ ## function } ,
static RTLDRSHAREDFUNC const g_aSharedFuncs[] =
{
RT_RUNTIME_LOADER_INSERT_SYMBOLS
};
# undef RT_PROXY_VARIADIC_STUB
# undef RT_PROXY_STUB
/**
* The function which does the actual work for RT_RUNTIME_LOADER_FUNCTION,
* serialised for thread safety.
*/
static DECLCALLBACK(int) rtldrLoadOnce(void *)
{
LogFlowFunc(("\n"));
RTLDRMOD hLdrMod;
int rcRet = RTLdrLoadEx(RT_RUNTIME_LOADER_LIB_NAME, &hLdrMod, RTLDRLOAD_FLAGS_LOCAL | RTLDRLOAD_FLAGS_NO_UNLOAD, NULL);
if (RT_SUCCESS(rcRet))
{
for (unsigned i = 0; i < RT_ELEMENTS(g_aSharedFuncs); ++i)
{
int rc2 = RTLdrGetSymbol(hLdrMod, g_aSharedFuncs[i].pszName, (void **)g_aSharedFuncs[i].ppfn);
if (RT_FAILURE(rc2))
{
LogFunc(("RTLdrGetSymbol(%s, %s) failed: %Rrc\n", RT_RUNTIME_LOADER_LIB_NAME, g_aSharedFuncs[i].pszName, rc2));
rcRet = rc2;
}
}
LogFlowFunc(("rcRet = %Rrc\n", rcRet));
}
else
LogFunc(("RTLdrLoadEx(%s) failed: %Rrc\n", RT_RUNTIME_LOADER_LIB_NAME, rcRet));
return rcRet;
}
/**
* Load the shared library RT_RUNTIME_LOADER_LIB_NAME and resolve the symbols
* pointed to by RT_RUNTIME_LOADER_INSERT_SYMBOLS.
*
* May safely be called from multiple threads and will not return until the
* library is loaded or has failed to load.
*
* @returns IPRT status code.
*/
RTR3DECL(int) RT_RUNTIME_LOADER_FUNCTION(void)
{
static RTONCE s_Once = RTONCE_INITIALIZER;
LogFlowFunc(("\n"));
int rc = RTOnce(&s_Once, rtldrLoadOnce, NULL);
LogFlowFunc(("rc = %Rrc\n", rc));
return rc;
}
#elif defined(RT_RUNTIME_LOADER_GENERATE_HEADER)
# ifdef RT_RUNTIME_LOADER_GENERATE_DECLS
/* Declarations of the functions that we need from
* RT_RUNTIME_LOADER_LIB_NAME */
# define RT_PROXY_STUB(function, rettype, signature, shortsig) \
RTR3DECL(rettype) function signature ;
/* Variadict functions needs custom mappings via \#defines as we cannot forward
the arguments in an inline function, so only make the function pointer available here. */
# define RT_PROXY_VARIADIC_STUB(function, rettype, signature) \
rettype (*function) signature;
RT_RUNTIME_LOADER_INSERT_SYMBOLS
# undef RT_PROXY_STUB
# undef RT_PROXY_VARIADIC_STUB
# endif /* RT_RUNTIME_LOADER_GENERATE_DECLS */
/**
* Try to dynamically load the library. This function should be called before
* attempting to use any of the library functions. It is safe to call this
* function multiple times.
*
* @returns iprt status code
*/
RTR3DECL(int) RT_RUNTIME_LOADER_FUNCTION(void);
#else
# error "One of RT_RUNTIME_LOADER_GENERATE_HEADER or RT_RUNTIME_LOADER_GENERATE_BODY_STUBS must be defined when including this file"
#endif
/** @} */
|
