runtime-loader.h revision 8fa59d6e8a7241b88e10a611d883318d157317cf
e1e8390280254f7f0580d701e583f670643d4f3fnilgun/** @file
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * IPRT - runtime loader generation
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd */
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd/*
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * Copyright (C) 2008 Sun Microsystems, Inc.
e1e8390280254f7f0580d701e583f670643d4f3fnilgun *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * This file is part of VirtualBox Open Source Edition (OSE), as
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * available from http://www.virtualbox.org. This file is free software;
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc * you can redistribute it and/or modify it under the terms of the GNU
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * General Public License (GPL) as published by the Free Software
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * Foundation, in version 2 as it comes in the "COPYING" file of the
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
2e545ce2450a9953665f701bb05350f0d3f26275nd * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen *
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen * The contents of this file may alternatively be used under the terms
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * of the Common Development and Distribution License Version 1.0
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen * VirtualBox OSE distribution, in which case the provisions of the
3f08db06526d6901aa08c110b5bc7dde6bc39905nd * CDDL are applicable instead of those of the GPL.
e1e8390280254f7f0580d701e583f670643d4f3fnilgun *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * You may elect to license modified versions of this file under the
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * terms and conditions of either the GPL or the CDDL or both.
3f08db06526d6901aa08c110b5bc7dde6bc39905nd *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * Clara, CA 95054 USA or visit http://www.sun.com if you need
befb6758d5618c60f29b19f9a7eb75ab993511dcjim * additional information or have any questions.
e1e8390280254f7f0580d701e583f670643d4f3fnilgun */
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen/* How to use this loader generator
e1e8390280254f7f0580d701e583f670643d4f3fnilgun *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * This loader generator can be used to generate stub code for loading a shared
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * library and its functions at runtime, or for generating a header file with
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * the declaration of the loader function and optionally declarations for the
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * functions loaded. It should be included in a header file or a C source
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * file, after defining certain macros which it makes use of.
e1e8390280254f7f0580d701e583f670643d4f3fnilgun *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * To generate the C source code for function proxy stubs and the library
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * loader function, you should define the following macros in your source file
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * before including this header:
e1e8390280254f7f0580d701e583f670643d4f3fnilgun *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * RT_RUNTIME_LOADER_LIB_NAME - the file name of the library to load
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * RT_RUNTIME_LOADER_FUNCTION - the name of the loader function
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * RT_RUNTIME_LOADER_INSERT_SYMBOLS - a macro containing the names of the
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * functions to be loaded, defined in the
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * following pattern:
e1e8390280254f7f0580d701e583f670643d4f3fnilgun *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * #define RT_RUNTIME_LOADER_INSERT_SYMBOLS \
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * RT_PROXY_STUB(func_name, ret_type, (long_param_list), (short_param_list)) \
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * RT_PROXY_STUB(func_name2, ret_type2, (long_param_list2), (short_param_list2)) \
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * ...
e1e8390280254f7f0580d701e583f670643d4f3fnilgun *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * where long_param_list is a paramter list for declaring the function of the
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * form (type1 arg1, type2 arg2, ...) and short_param_list for calling it, of
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * the form (arg1, arg2, ...).
e1e8390280254f7f0580d701e583f670643d4f3fnilgun *
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * To generate the header file, you should define RT_RUNTIME_LOADER_FUNCTION
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * and if you wish to generate declarations for the functions you should
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * additionally define RT_RUNTIME_LOADER_INSERT_SYMBOLS as above and
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * RT_RUNTIME_LOADER_GENERATE_DECLS (without a value) before including this
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * file.
e1e8390280254f7f0580d701e583f670643d4f3fnilgun */
e1e8390280254f7f0580d701e583f670643d4f3fnilgun/** @todo this is far too complicated. A script for generating the files would
e1e8390280254f7f0580d701e583f670643d4f3fnilgun * probably be preferable. */
e1e8390280254f7f0580d701e583f670643d4f3fnilgun
e1e8390280254f7f0580d701e583f670643d4f3fnilgun#include <iprt/ldr.h>
e1e8390280254f7f0580d701e583f670643d4f3fnilgun#include <iprt/log.h>
e1e8390280254f7f0580d701e583f670643d4f3fnilgun#include <iprt/once.h>
e1e8390280254f7f0580d701e583f670643d4f3fnilgun
e1e8390280254f7f0580d701e583f670643d4f3fnilgun#ifdef RT_RUNTIME_LOADER_GENERATE_BODY_STUBS
e1e8390280254f7f0580d701e583f670643d4f3fnilgun/** The following are the symbols which we need from the library. */
e1e8390280254f7f0580d701e583f670643d4f3fnilgun# define RT_PROXY_STUB(function, rettype, signature, shortsig) \
e1e8390280254f7f0580d701e583f670643d4f3fnilgun void (*function ## _fn)(void); \
e1e8390280254f7f0580d701e583f670643d4f3fnilgun RTR3DECL(rettype) function signature \
e1e8390280254f7f0580d701e583f670643d4f3fnilgun { return ( (rettype (*) signature) function ## _fn ) shortsig; }
e1e8390280254f7f0580d701e583f670643d4f3fnilgun
e1e8390280254f7f0580d701e583f670643d4f3fnilgunRT_RUNTIME_LOADER_INSERT_SYMBOLS
e1e8390280254f7f0580d701e583f670643d4f3fnilgun
e1e8390280254f7f0580d701e583f670643d4f3fnilgun# undef RT_PROXY_STUB
e1e8390280254f7f0580d701e583f670643d4f3fnilgun
e1e8390280254f7f0580d701e583f670643d4f3fnilgun/* Now comes a table of functions to be loaded from the library */
e1e8390280254f7f0580d701e583f670643d4f3fnilguntypedef struct
befb6758d5618c60f29b19f9a7eb75ab993511dcjim{
e1e8390280254f7f0580d701e583f670643d4f3fnilgun const char *name;
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen void (**fn)(void);
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen} SHARED_FUNC;
e1e8390280254f7f0580d701e583f670643d4f3fnilgun
205f749042ed530040a4f0080dbcb47ceae8a374rjung# define RT_PROXY_STUB(s, dummy1, dummy2, dummy3 ) { #s , & s ## _fn } ,
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowenstatic SHARED_FUNC SharedFuncs[] =
0d0ba3a410038e179b695446bb149cce6264e0abnd{
7fec19672a491661b2fe4b29f685bc7f4efa64d4ndRT_RUNTIME_LOADER_INSERT_SYMBOLS
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd { NULL, NULL }
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd};
e1e8390280254f7f0580d701e583f670643d4f3fnilgun# undef RT_PROXY_STUB
/* The function which does the actual work for RT_RUNTIME_LOADER_FUNCTION,
* serialised for thread safety. */
static int rtldrLoadOnce(void *, void *)
{
RTLDRMOD hLib;
LogFlowFunc(("\n"));
int rc = RTLdrLoad(RT_RUNTIME_LOADER_LIB_NAME, &hLib);
for (unsigned i = 0; RT_SUCCESS(rc) && SharedFuncs[i].name != NULL; ++i)
rc = RTLdrGetSymbol(hLib, SharedFuncs[i].name, (void**)SharedFuncs[i].fn);
LogFlowFunc(("rc = %Rrc\n", rc));
return rc;
}
/** 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. */
RTR3DECL(int) RT_RUNTIME_LOADER_FUNCTION(void)
{
static RTONCE sOnce = RTONCE_INITIALIZER;
LogFlowFunc(("\n"));
int rc = RTOnce (&sOnce, rtldrLoadOnce, NULL, 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 ;
RT_RUNTIME_LOADER_INSERT_SYMBOLS
# undef RT_PROXY_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