e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * IPRT - Runtime Loader Generation.
a438caaf732f7839dc66b4f8dad672527845a003vboxsync * Copyright (C) 2008-2012 Oracle Corporation
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * available from http://www.virtualbox.org. This file is free software;
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * you can redistribute it and/or modify it under the terms of the GNU
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * General Public License (GPL) as published by the Free Software
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * The contents of this file may alternatively be used under the terms
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * of the Common Development and Distribution License Version 1.0
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * VirtualBox OSE distribution, in which case the provisions of the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * CDDL are applicable instead of those of the GPL.
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * You may elect to license modified versions of this file under the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * terms and conditions of either the GPL or the CDDL or both.
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync/** @defgroup grp_rt_runtime_loader Runtime Loader Generation
8f2d4fea58e2d827a8269d0c96d307217b5ab14dvboxsync * @ingroup grp_rt
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * How to use this loader generator
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * This loader generator can be used to generate stub code for loading a shared
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * library and its functions at runtime, or for generating a header file with
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * the declaration of the loader function and optionally declarations for the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * functions loaded. It should be included in a header file or a C source
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * file, after defining certain macros which it makes use of.
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * To generate the C source code for function proxy stubs and the library
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * loader function, you should define the following macros in your source file
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * before including this header:
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * RT_RUNTIME_LOADER_LIB_NAME - the file name of the library to load
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * RT_RUNTIME_LOADER_FUNCTION - the name of the loader function
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * RT_RUNTIME_LOADER_INSERT_SYMBOLS - a macro containing the names of the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * functions to be loaded, defined in the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * following pattern:
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * #define RT_RUNTIME_LOADER_INSERT_SYMBOLS \
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * RT_PROXY_STUB(func_name, ret_type, (long_param_list), (short_param_list)) \
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * RT_PROXY_STUB(func_name2, ret_type2, (long_param_list2), (short_param_list2)) \
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * where long_param_list is a parameter list for declaring the function of the
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * form (type1 arg1, type2 arg2, ...) and short_param_list for calling it, of
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * the form (arg1, arg2, ...).
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * To generate the header file, you should define RT_RUNTIME_LOADER_FUNCTION
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * and if you wish to generate declarations for the functions you should
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * additionally define RT_RUNTIME_LOADER_INSERT_SYMBOLS as above and
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * RT_RUNTIME_LOADER_GENERATE_DECLS (without a value) before including this
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync/** @todo this is far too complicated. A script for generating the files would
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * probably be preferable.
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * bird> An alternative is to generate assembly jump wrappers, this only
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * requires the symbol names and prefix. I've done this ages ago when we forked
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * the EMX/GCC toolchain on OS/2... It's a wee bit more annoying in x86 PIC/PIE
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * mode, but nothing that cannot be dealt with.
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync/** @todo r=bird: The use of RTR3DECL here is an unresolved issue. */
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync/** @todo r=bird: The lack of RT_C_DECLS_BEGIN/END is an unresolved issue. Here
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * we'll get into trouble if we use the same symbol names as the
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * original! */
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync/** @todo r=bird: The prefix usage here is very confused: RT_RUNTIME_LOADER_XXX,
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * RT_PROXY_STUB, etc. */
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync/* The following are the symbols which we need from the library. */
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync# define RT_PROXY_STUB(function, rettype, signature, shortsig) \
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync { return ( (rettype (*) signature) function ## _fn ) shortsig; }
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync/* Now comes a table of functions to be loaded from the library. */
54c3620994786a33db473956c4e6c3c7d94ab695vboxsynctypedef struct
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync# define RT_PROXY_STUB(s, dummy1, dummy2, dummy3 ) { #s , & s ## _fn } ,
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * The function which does the actual work for RT_RUNTIME_LOADER_FUNCTION,
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * serialised for thread safety.
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync for (unsigned i = 0; RT_SUCCESS(rc) && g_aSharedFuncs[i].pszName != NULL; ++i)
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync rc = RTLdrGetSymbol(hLib, g_aSharedFuncs[i].pszName, (void **)g_aSharedFuncs[i].ppfn);
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * Load the shared library RT_RUNTIME_LOADER_LIB_NAME and resolve the symbols
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * pointed to by RT_RUNTIME_LOADER_INSERT_SYMBOLS.
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * May safely be called from multiple threads and will not return until the
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * library is loaded or has failed to load.
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync * @returns IPRT status code.
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync/* Declarations of the functions that we need from
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * RT_RUNTIME_LOADER_LIB_NAME */
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync# define RT_PROXY_STUB(function, rettype, signature, shortsig) \
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync# endif /* RT_RUNTIME_LOADER_GENERATE_DECLS */
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * Try to dynamically load the library. This function should be called before
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * attempting to use any of the library functions. It is safe to call this
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * function multiple times.
54c3620994786a33db473956c4e6c3c7d94ab695vboxsync * @returns iprt status code
e470d654059e0c976fe3ce83874ac6e8fd2338a6vboxsync# error "One of RT_RUNTIME_LOADER_GENERATE_HEADER or RT_RUNTIME_LOADER_GENERATE_BODY_STUBS must be defined when including this file"