VirtualBox

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

Last change on this file since 96550 was 96407, checked in by vboxsync, 2 years ago

scm copyright and license note update

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.6 KB
Line 
1/** @file
2 * IPRT - Runtime Loader Generation.
3 */
4
5/*
6 * Copyright (C) 2008-2022 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 * ...
68 * @endcode
69 *
70 * where long_param_list is a parameter list for declaring the function of the
71 * form (type1 arg1, type2 arg2, ...) and short_param_list for calling it, of
72 * the form (arg1, arg2, ...).
73 *
74 * To generate the header file, you should define RT_RUNTIME_LOADER_FUNCTION
75 * and if you wish to generate declarations for the functions you should
76 * additionally define RT_RUNTIME_LOADER_INSERT_SYMBOLS as above and
77 * RT_RUNTIME_LOADER_GENERATE_DECLS (without a value) before including this
78 * file.
79 *
80 * @{
81 */
82/** @todo this is far too complicated. A script for generating the files would
83 * probably be preferable.
84 *
85 * bird> An alternative is to generate assembly jump wrappers, this only
86 * requires the symbol names and prefix. I've done this ages ago when we forked
87 * the EMX/GCC toolchain on OS/2... It's a wee bit more annoying in x86 PIC/PIE
88 * mode, but nothing that cannot be dealt with.
89 */
90/** @todo r=bird: The use of RTR3DECL here is an unresolved issue. */
91/** @todo r=bird: The lack of RT_C_DECLS_BEGIN/END is an unresolved issue. Here
92 * we'll get into trouble if we use the same symbol names as the
93 * original! */
94/** @todo r=bird: The prefix usage here is very confused: RT_RUNTIME_LOADER_XXX,
95 * RT_PROXY_STUB, etc. */
96
97#ifdef RT_RUNTIME_LOADER_GENERATE_BODY_STUBS
98
99/* The following are the symbols which we need from the library. */
100# define RT_PROXY_STUB(function, rettype, signature, shortsig) \
101 void (*function ## _fn)(void); \
102 RTR3DECL(rettype) function signature \
103 { return ( (rettype (*) signature) function ## _fn ) shortsig; }
104
105RT_RUNTIME_LOADER_INSERT_SYMBOLS
106
107# undef RT_PROXY_STUB
108
109/* Now comes a table of functions to be loaded from the library. */
110typedef struct
111{
112 const char *pszName;
113 void (**ppfn)(void);
114} RTLDRSHAREDFUNC;
115
116# define RT_PROXY_STUB(s, dummy1, dummy2, dummy3 ) { #s , & s ## _fn } ,
117static RTLDRSHAREDFUNC g_aSharedFuncs[] =
118{
119 RT_RUNTIME_LOADER_INSERT_SYMBOLS
120 { NULL, NULL }
121};
122# undef RT_PROXY_STUB
123
124/**
125 * The function which does the actual work for RT_RUNTIME_LOADER_FUNCTION,
126 * serialised for thread safety.
127 */
128static DECLCALLBACK(int) rtldrLoadOnce(void *)
129{
130 RTLDRMOD hLib;
131 int rc;
132
133 LogFlowFunc(("\n"));
134 rc = RTLdrLoadEx(RT_RUNTIME_LOADER_LIB_NAME, &hLib, RTLDRLOAD_FLAGS_LOCAL | RTLDRLOAD_FLAGS_NO_UNLOAD, NULL);
135 for (unsigned i = 0; RT_SUCCESS(rc) && g_aSharedFuncs[i].pszName != NULL; ++i)
136 rc = RTLdrGetSymbol(hLib, g_aSharedFuncs[i].pszName, (void **)g_aSharedFuncs[i].ppfn);
137 LogFlowFunc(("rc = %Rrc\n", rc));
138
139 return rc;
140}
141
142/**
143 * Load the shared library RT_RUNTIME_LOADER_LIB_NAME and resolve the symbols
144 * pointed to by RT_RUNTIME_LOADER_INSERT_SYMBOLS.
145 *
146 * May safely be called from multiple threads and will not return until the
147 * library is loaded or has failed to load.
148 *
149 * @returns IPRT status code.
150 */
151RTR3DECL(int) RT_RUNTIME_LOADER_FUNCTION(void)
152{
153 static RTONCE s_Once = RTONCE_INITIALIZER;
154 int rc;
155
156 LogFlowFunc(("\n"));
157 rc = RTOnce(&s_Once, rtldrLoadOnce, NULL);
158 LogFlowFunc(("rc = %Rrc\n", rc));
159
160 return rc;
161}
162
163#elif defined(RT_RUNTIME_LOADER_GENERATE_HEADER)
164# ifdef RT_RUNTIME_LOADER_GENERATE_DECLS
165/* Declarations of the functions that we need from
166 * RT_RUNTIME_LOADER_LIB_NAME */
167# define RT_PROXY_STUB(function, rettype, signature, shortsig) \
168 RTR3DECL(rettype) function signature ;
169
170RT_RUNTIME_LOADER_INSERT_SYMBOLS
171
172# undef RT_PROXY_STUB
173# endif /* RT_RUNTIME_LOADER_GENERATE_DECLS */
174
175/**
176 * Try to dynamically load the library. This function should be called before
177 * attempting to use any of the library functions. It is safe to call this
178 * function multiple times.
179 *
180 * @returns iprt status code
181 */
182RTR3DECL(int) RT_RUNTIME_LOADER_FUNCTION(void);
183
184#else
185# error "One of RT_RUNTIME_LOADER_GENERATE_HEADER or RT_RUNTIME_LOADER_GENERATE_BODY_STUBS must be defined when including this file"
186#endif
187
188/** @} */
189
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