VirtualBox

source: vbox/trunk/include/iprt/runtime-loader.h@ 103224

Last change on this file since 103224 was 99555, checked in by vboxsync, 18 months ago

iprt/runtime-loader.h: RT_PROXY_VARIADICT_STUB: fixed header part generation, introduced in r157047, bugref:10194.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette