Changeset 28363 in vbox

Timestamp:

Apr 15, 2010 2:08:05 PM (15 years ago)

Author:

vboxsync

Message:

iprt/runtime-loader.h: doxygen, hunarian.

File:

• trunk/include/iprt/runtime-loader.h (modified) (6 diffs)

trunk/include/iprt/runtime-loader.h

@@ -1 +1 @@
 /** @file
- * IPRT - runtime loader generation
+ * IPRT - Runtime Loader Generation.
  */
 
 /*
- * Copyright (C) 2008 Sun Microsystems, Inc.
+ * Copyright (C) 2008-2010 Sun Microsystems, Inc.
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -28 +28 @@
  */
 
-/* How to use this loader generator
+#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
+ *
+ * How to use this loader generator
  *
  * This loader generator can be used to generate stub code for loading a shared
@@ -45 +54 @@
  *                                     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)) \
  *  ...
+ * @endcode
  *
  * where long_param_list is a paramter list for declaring the function of the
@@ -60 +70 @@
  * RT_RUNTIME_LOADER_GENERATE_DECLS (without a value) before including this
  * file.
+ *
+ * @{
  */
 /** @todo this is far too complicated.  A script for generating the files would
- * probably be preferable. */
-
-#include <iprt/ldr.h>
-#include <iprt/log.h>
-#include <iprt/once.h>
+ * 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.
+ */
+/** @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. */
+
+/* The following are the symbols which we need from the library. */
 # define RT_PROXY_STUB(function, rettype, signature, shortsig) \
- void (*function ## _fn)(void); \
- RTR3DECL(rettype) function signature \
- { return ( (rettype (*) signature) function ## _fn ) shortsig; }
+    void (*function ## _fn)(void); \
+    RTR3DECL(rettype) function signature \
+    { return ( (rettype (*) signature) function ## _fn ) shortsig; }
 
 RT_RUNTIME_LOADER_INSERT_SYMBOLS
@@ -79 +100 @@
 # undef RT_PROXY_STUB
 
-/* Now comes a table of functions to be loaded from the library */
+/* Now comes a table of functions to be loaded from the library. */
 typedef struct
 {
-    const char *name;
-    void (**fn)(void);
-} SHARED_FUNC;
+    const char *pszName;
+    void (**ppfn)(void);
+} RTLDRSHAREDFUNC;
 
 # define RT_PROXY_STUB(s, dummy1, dummy2, dummy3 ) { #s , & s ## _fn } ,
-static SHARED_FUNC SharedFuncs[] =
+static RTLDRSHAREDFUNC g_aSharedFuncs[] =
 {
-RT_RUNTIME_LOADER_INSERT_SYMBOLS
+    RT_RUNTIME_LOADER_INSERT_SYMBOLS
     { NULL, NULL }
 };
 # 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 *)
+/**
+ * The function which does the actual work for RT_RUNTIME_LOADER_FUNCTION,
+ * serialised for thread safety.
+ */
+static DECLCALLBACK(int) rtldrLoadOnce(void *, void *)
 {
-    RTLDRMOD hLib;
+    RTLDRMOD    hLib;
+    int         rc;
 
     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);
+    rc = RTLdrLoad(RT_RUNTIME_LOADER_LIB_NAME, &hLib);
+    for (unsigned i = 0; RT_SUCCESS(rc) && g_aSharedFuncs[i].pszName != NULL; ++i)
+        rc = RTLdrGetSymbol(hLib, g_aSharedFuncs[i].pszName, (void **)g_aSharedFuncs[i].ppfn);
     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. */
+/**
+ * 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 sOnce = RTONCE_INITIALIZER;
+    static RTONCE   s_Once = RTONCE_INITIALIZER;
+    int             rc;
 
     LogFlowFunc(("\n"));
-    int rc = RTOnce (&sOnce, rtldrLoadOnce, NULL, NULL);
+    rc = RTOnce(&s_Once, rtldrLoadOnce, NULL, NULL);
     LogFlowFunc(("rc = %Rrc\n", rc));
+
     return rc;
 }
@@ -142 +174 @@
  */
 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
+# error "One of RT_RUNTIME_LOADER_GENERATE_HEADER or RT_RUNTIME_LOADER_GENERATE_BODY_STUBS must be defined when including this file"
 #endif
+
+/** @} */
+