| 1 | /** @file
|
|---|
| 2 | * IPRT - Loader.
|
|---|
| 3 | */
|
|---|
| 4 |
|
|---|
| 5 | /*
|
|---|
| 6 | * Copyright (C) 2006-2011 Oracle Corporation
|
|---|
| 7 | *
|
|---|
| 8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
|---|
| 9 | * available from http://www.virtualbox.org. This file is free software;
|
|---|
| 10 | * you can redistribute it and/or modify it under the terms of the GNU
|
|---|
| 11 | * General Public License (GPL) as published by the Free Software
|
|---|
| 12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
|---|
| 13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
|---|
| 14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
|---|
| 15 | *
|
|---|
| 16 | * The contents of this file may alternatively be used under the terms
|
|---|
| 17 | * of the Common Development and Distribution License Version 1.0
|
|---|
| 18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
|---|
| 19 | * VirtualBox OSE distribution, in which case the provisions of the
|
|---|
| 20 | * CDDL are applicable instead of those of the GPL.
|
|---|
| 21 | *
|
|---|
| 22 | * You may elect to license modified versions of this file under the
|
|---|
| 23 | * terms and conditions of either the GPL or the CDDL or both.
|
|---|
| 24 | */
|
|---|
| 25 |
|
|---|
| 26 | #ifndef ___iprt_ldr_h
|
|---|
| 27 | #define ___iprt_ldr_h
|
|---|
| 28 |
|
|---|
| 29 | #include <iprt/cdefs.h>
|
|---|
| 30 | #include <iprt/types.h>
|
|---|
| 31 |
|
|---|
| 32 |
|
|---|
| 33 | /** @defgroup grp_ldr RTLdr - Loader
|
|---|
| 34 | * @ingroup grp_rt
|
|---|
| 35 | * @{
|
|---|
| 36 | */
|
|---|
| 37 |
|
|---|
| 38 |
|
|---|
| 39 | RT_C_DECLS_BEGIN
|
|---|
| 40 |
|
|---|
| 41 | /** Loader address (unsigned integer). */
|
|---|
| 42 | typedef RTUINTPTR RTLDRADDR;
|
|---|
| 43 | /** Pointer to a loader address. */
|
|---|
| 44 | typedef RTLDRADDR *PRTLDRADDR;
|
|---|
| 45 | /** Pointer to a const loader address. */
|
|---|
| 46 | typedef RTLDRADDR const *PCRTLDRADDR;
|
|---|
| 47 | /** The max loader address value. */
|
|---|
| 48 | #define RTLDRADDR_MAX RTUINTPTR_MAX
|
|---|
| 49 | /** NIL loader address value. */
|
|---|
| 50 | #define NIL_RTLDRADDR RTLDRADDR_MAX
|
|---|
| 51 |
|
|---|
| 52 |
|
|---|
| 53 | /**
|
|---|
| 54 | * Gets the default file suffix for DLL/SO/DYLIB/whatever.
|
|---|
| 55 | *
|
|---|
| 56 | * @returns The stuff (readonly).
|
|---|
| 57 | */
|
|---|
| 58 | RTDECL(const char *) RTLdrGetSuff(void);
|
|---|
| 59 |
|
|---|
| 60 | /**
|
|---|
| 61 | * Checks if a library is loadable or not.
|
|---|
| 62 | *
|
|---|
| 63 | * This may attempt load and unload the library.
|
|---|
| 64 | *
|
|---|
| 65 | * @returns true/false accordingly.
|
|---|
| 66 | * @param pszFilename Image filename.
|
|---|
| 67 | */
|
|---|
| 68 | RTDECL(bool) RTLdrIsLoadable(const char *pszFilename);
|
|---|
| 69 |
|
|---|
| 70 | /**
|
|---|
| 71 | * Loads a dynamic load library (/shared object) image file using native
|
|---|
| 72 | * OS facilities.
|
|---|
| 73 | *
|
|---|
| 74 | * The filename will be appended the default DLL/SO extension of
|
|---|
| 75 | * the platform if it have been omitted. This means that it's not
|
|---|
| 76 | * possible to load DLLs/SOs with no extension using this interface,
|
|---|
| 77 | * but that's not a bad tradeoff.
|
|---|
| 78 | *
|
|---|
| 79 | * If no path is specified in the filename, the OS will usually search it's library
|
|---|
| 80 | * path to find the image file.
|
|---|
| 81 | *
|
|---|
| 82 | * @returns iprt status code.
|
|---|
| 83 | * @param pszFilename Image filename.
|
|---|
| 84 | * @param phLdrMod Where to store the handle to the loader module.
|
|---|
| 85 | */
|
|---|
| 86 | RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod);
|
|---|
| 87 |
|
|---|
| 88 | /**
|
|---|
| 89 | * Loads a dynamic load library (/shared object) image file using native
|
|---|
| 90 | * OS facilities.
|
|---|
| 91 | *
|
|---|
| 92 | * The filename will be appended the default DLL/SO extension of
|
|---|
| 93 | * the platform if it have been omitted. This means that it's not
|
|---|
| 94 | * possible to load DLLs/SOs with no extension using this interface,
|
|---|
| 95 | * but that's not a bad tradeoff.
|
|---|
| 96 | *
|
|---|
| 97 | * If no path is specified in the filename, the OS will usually search it's library
|
|---|
| 98 | * path to find the image file.
|
|---|
| 99 | *
|
|---|
| 100 | * @returns iprt status code.
|
|---|
| 101 | * @param pszFilename Image filename.
|
|---|
| 102 | * @param phLdrMod Where to store the handle to the loader module.
|
|---|
| 103 | * @param fFlags See RTLDRLOAD_FLAGS_XXX.
|
|---|
| 104 | * @param pErrInfo Where to return extended error information. Optional.
|
|---|
| 105 | */
|
|---|
| 106 | RTDECL(int) RTLdrLoadEx(const char *pszFilename, PRTLDRMOD phLdrMod, uint32_t fFlags, PRTERRINFO pErrInfo);
|
|---|
| 107 |
|
|---|
| 108 | /** @defgroup RTLDRLOAD_FLAGS_XXX RTLdrLoadEx flags.
|
|---|
| 109 | * @{ */
|
|---|
| 110 | /** Symbols defined in this library are not made available to resolve
|
|---|
| 111 | * references in subsequently loaded libraries (default). */
|
|---|
| 112 | #define RTLDRLOAD_FLAGS_LOCAL UINT32_C(0)
|
|---|
| 113 | /** Symbols defined in this library will be made available for symbol
|
|---|
| 114 | * resolution of subsequently loaded libraries. */
|
|---|
| 115 | #define RTLDRLOAD_FLAGS_GLOBAL RT_BIT_32(0)
|
|---|
| 116 | /** The mask of valid flag bits. */
|
|---|
| 117 | #define RTLDRLOAD_FLAGS_VALID_MASK UINT32_C(0x00000001)
|
|---|
| 118 | /** @} */
|
|---|
| 119 |
|
|---|
| 120 | /**
|
|---|
| 121 | * Loads a dynamic load library (/shared object) image file residing in the
|
|---|
| 122 | * RTPathAppPrivateArch() directory.
|
|---|
| 123 | *
|
|---|
| 124 | * Suffix is not required.
|
|---|
| 125 | *
|
|---|
| 126 | * @returns iprt status code.
|
|---|
| 127 | * @param pszFilename Image filename. No path.
|
|---|
| 128 | * @param phLdrMod Where to store the handle to the loaded module.
|
|---|
| 129 | */
|
|---|
| 130 | RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
|
|---|
| 131 |
|
|---|
| 132 | /**
|
|---|
| 133 | * Image architecuture specifier for RTLdrOpenEx.
|
|---|
| 134 | */
|
|---|
| 135 | typedef enum RTLDRARCH
|
|---|
| 136 | {
|
|---|
| 137 | RTLDRARCH_INVALID = 0,
|
|---|
| 138 | /** Whatever. */
|
|---|
| 139 | RTLDRARCH_WHATEVER,
|
|---|
| 140 | /** The host architecture. */
|
|---|
| 141 | RTLDRARCH_HOST,
|
|---|
| 142 | /** 32-bit x86. */
|
|---|
| 143 | RTLDRARCH_X86_32,
|
|---|
| 144 | /** AMD64 (64-bit x86 if you like). */
|
|---|
| 145 | RTLDRARCH_AMD64,
|
|---|
| 146 | /** End of the valid values. */
|
|---|
| 147 | RTLDRARCH_END,
|
|---|
| 148 | /** Make sure the type is a full 32-bit. */
|
|---|
| 149 | RTLDRARCH_32BIT_HACK = 0x7fffffff
|
|---|
| 150 | } RTLDRARCH;
|
|---|
| 151 | /** Pointer to a RTLDRARCH. */
|
|---|
| 152 | typedef RTLDRARCH *PRTLDRARCH;
|
|---|
| 153 |
|
|---|
| 154 | /**
|
|---|
| 155 | * Open a binary image file, extended version.
|
|---|
| 156 | *
|
|---|
| 157 | * @returns iprt status code.
|
|---|
| 158 | * @param pszFilename Image filename.
|
|---|
| 159 | * @param fFlags Reserved, MBZ.
|
|---|
| 160 | * @param enmArch CPU architecture specifier for the image to be loaded.
|
|---|
| 161 | * @param phLdrMod Where to store the handle to the loader module.
|
|---|
| 162 | */
|
|---|
| 163 | RTDECL(int) RTLdrOpen(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
|
|---|
| 164 |
|
|---|
| 165 | /**
|
|---|
| 166 | * Opens a binary image file using kLdr.
|
|---|
| 167 | *
|
|---|
| 168 | * @returns iprt status code.
|
|---|
| 169 | * @param pszFilename Image filename.
|
|---|
| 170 | * @param phLdrMod Where to store the handle to the loaded module.
|
|---|
| 171 | * @param fFlags Reserved, MBZ.
|
|---|
| 172 | * @param enmArch CPU architecture specifier for the image to be loaded.
|
|---|
| 173 | * @remark Primarily for testing the loader.
|
|---|
| 174 | */
|
|---|
| 175 | RTDECL(int) RTLdrOpenkLdr(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
|
|---|
| 176 |
|
|---|
| 177 | /**
|
|---|
| 178 | * What to expect and do with the bits passed to RTLdrOpenBits().
|
|---|
| 179 | */
|
|---|
| 180 | typedef enum RTLDROPENBITS
|
|---|
| 181 | {
|
|---|
| 182 | /** The usual invalid 0 entry. */
|
|---|
| 183 | RTLDROPENBITS_INVALID = 0,
|
|---|
| 184 | /** The bits are readonly and will never be changed. */
|
|---|
| 185 | RTLDROPENBITS_READONLY,
|
|---|
| 186 | /** The bits are going to be changed and the loader will have to duplicate them
|
|---|
| 187 | * when opening the image. */
|
|---|
| 188 | RTLDROPENBITS_WRITABLE,
|
|---|
| 189 | /** The bits are both the source and destination for the loader operation.
|
|---|
| 190 | * This means that the loader may have to duplicate them prior to changing them. */
|
|---|
| 191 | RTLDROPENBITS_SRC_AND_DST,
|
|---|
| 192 | /** The end of the valid enums. This entry marks the
|
|---|
| 193 | * first invalid entry.. */
|
|---|
| 194 | RTLDROPENBITS_END,
|
|---|
| 195 | RTLDROPENBITS_32BIT_HACK = 0x7fffffff
|
|---|
| 196 | } RTLDROPENBITS;
|
|---|
| 197 |
|
|---|
| 198 | /**
|
|---|
| 199 | * Open a binary image from in-memory bits.
|
|---|
| 200 | *
|
|---|
| 201 | * @returns iprt status code.
|
|---|
| 202 | * @param pvBits The start of the raw-image.
|
|---|
| 203 | * @param cbBits The size of the raw-image.
|
|---|
| 204 | * @param enmBits What to expect from the pvBits.
|
|---|
| 205 | * @param pszLogName What to call the raw-image when logging.
|
|---|
| 206 | * For RTLdrLoad and RTLdrOpen the filename is used for this.
|
|---|
| 207 | * @param phLdrMod Where to store the handle to the loader module.
|
|---|
| 208 | */
|
|---|
| 209 | RTDECL(int) RTLdrOpenBits(const void *pvBits, size_t cbBits, RTLDROPENBITS enmBits, const char *pszLogName, PRTLDRMOD phLdrMod);
|
|---|
| 210 |
|
|---|
| 211 | /**
|
|---|
| 212 | * Closes a loader module handle.
|
|---|
| 213 | *
|
|---|
| 214 | * The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
|
|---|
| 215 | * and RTLdrOpenBits() functions.
|
|---|
| 216 | *
|
|---|
| 217 | * @returns iprt status code.
|
|---|
| 218 | * @param hLdrMod The loader module handle.
|
|---|
| 219 | */
|
|---|
| 220 | RTDECL(int) RTLdrClose(RTLDRMOD hLdrMod);
|
|---|
| 221 |
|
|---|
| 222 | /**
|
|---|
| 223 | * Gets the address of a named exported symbol.
|
|---|
| 224 | *
|
|---|
| 225 | * @returns iprt status code.
|
|---|
| 226 | * @param hLdrMod The loader module handle.
|
|---|
| 227 | * @param pszSymbol Symbol name.
|
|---|
| 228 | * @param ppvValue Where to store the symbol value. Note that this is restricted to the
|
|---|
| 229 | * pointer size used on the host!
|
|---|
| 230 | */
|
|---|
| 231 | RTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char *pszSymbol, void **ppvValue);
|
|---|
| 232 |
|
|---|
| 233 | /**
|
|---|
| 234 | * Gets the address of a named exported symbol.
|
|---|
| 235 | *
|
|---|
| 236 | * This function differs from the plain one in that it can deal with
|
|---|
| 237 | * both GC and HC address sizes, and that it can calculate the symbol
|
|---|
| 238 | * value relative to any given base address.
|
|---|
| 239 | *
|
|---|
| 240 | * @returns iprt status code.
|
|---|
| 241 | * @param hLdrMod The loader module handle.
|
|---|
| 242 | * @param pvBits Optional pointer to the loaded image.
|
|---|
| 243 | * Set this to NULL if no RTLdrGetBits() processed image bits are available.
|
|---|
| 244 | * Not supported for RTLdrLoad() images.
|
|---|
| 245 | * @param BaseAddress Image load address.
|
|---|
| 246 | * Not supported for RTLdrLoad() images.
|
|---|
| 247 | * @param pszSymbol Symbol name.
|
|---|
| 248 | * @param pValue Where to store the symbol value.
|
|---|
| 249 | */
|
|---|
| 250 | RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void *pvBits, RTLDRADDR BaseAddress, const char *pszSymbol,
|
|---|
| 251 | PRTLDRADDR pValue);
|
|---|
| 252 |
|
|---|
| 253 | /**
|
|---|
| 254 | * Gets the size of the loaded image.
|
|---|
| 255 | * This is only supported for modules which has been opened using RTLdrOpen() and RTLdrOpenBits().
|
|---|
| 256 | *
|
|---|
| 257 | * @returns image size (in bytes).
|
|---|
| 258 | * @returns ~(size_t)0 on if not opened by RTLdrOpen().
|
|---|
| 259 | * @param hLdrMod Handle to the loader module.
|
|---|
| 260 | * @remark Not supported for RTLdrLoad() images.
|
|---|
| 261 | */
|
|---|
| 262 | RTDECL(size_t) RTLdrSize(RTLDRMOD hLdrMod);
|
|---|
| 263 |
|
|---|
| 264 | /**
|
|---|
| 265 | * Resolve an external symbol during RTLdrGetBits().
|
|---|
| 266 | *
|
|---|
| 267 | * @returns iprt status code.
|
|---|
| 268 | * @param hLdrMod The loader module handle.
|
|---|
| 269 | * @param pszModule Module name.
|
|---|
| 270 | * @param pszSymbol Symbol name, NULL if uSymbol should be used.
|
|---|
| 271 | * @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used.
|
|---|
| 272 | * @param pValue Where to store the symbol value (address).
|
|---|
| 273 | * @param pvUser User argument.
|
|---|
| 274 | */
|
|---|
| 275 | typedef DECLCALLBACK(int) RTLDRIMPORT(RTLDRMOD hLdrMod, const char *pszModule, const char *pszSymbol, unsigned uSymbol,
|
|---|
| 276 | PRTLDRADDR pValue, void *pvUser);
|
|---|
| 277 | /** Pointer to a FNRTLDRIMPORT() callback function. */
|
|---|
| 278 | typedef RTLDRIMPORT *PFNRTLDRIMPORT;
|
|---|
| 279 |
|
|---|
| 280 | /**
|
|---|
| 281 | * Loads the image into a buffer provided by the user and applies fixups
|
|---|
| 282 | * for the given base address.
|
|---|
| 283 | *
|
|---|
| 284 | * @returns iprt status code.
|
|---|
| 285 | * @param hLdrMod The load module handle.
|
|---|
| 286 | * @param pvBits Where to put the bits.
|
|---|
| 287 | * Must be as large as RTLdrSize() suggests.
|
|---|
| 288 | * @param BaseAddress The base address.
|
|---|
| 289 | * @param pfnGetImport Callback function for resolving imports one by one.
|
|---|
| 290 | * @param pvUser User argument for the callback.
|
|---|
| 291 | * @remark Not supported for RTLdrLoad() images.
|
|---|
| 292 | */
|
|---|
| 293 | RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
|
|---|
| 294 |
|
|---|
| 295 | /**
|
|---|
| 296 | * Relocates bits after getting them.
|
|---|
| 297 | * Useful for code which moves around a bit.
|
|---|
| 298 | *
|
|---|
| 299 | * @returns iprt status code.
|
|---|
| 300 | * @param hLdrMod The loader module handle.
|
|---|
| 301 | * @param pvBits Where the image bits are.
|
|---|
| 302 | * Must have been passed to RTLdrGetBits().
|
|---|
| 303 | * @param NewBaseAddress The new base address.
|
|---|
| 304 | * @param OldBaseAddress The old base address.
|
|---|
| 305 | * @param pfnGetImport Callback function for resolving imports one by one.
|
|---|
| 306 | * @param pvUser User argument for the callback.
|
|---|
| 307 | * @remark Not supported for RTLdrLoad() images.
|
|---|
| 308 | */
|
|---|
| 309 | RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR NewBaseAddress, RTLDRADDR OldBaseAddress,
|
|---|
| 310 | PFNRTLDRIMPORT pfnGetImport, void *pvUser);
|
|---|
| 311 |
|
|---|
| 312 | /**
|
|---|
| 313 | * Enumeration callback function used by RTLdrEnumSymbols().
|
|---|
| 314 | *
|
|---|
| 315 | * @returns iprt status code. Failure will stop the enumeration.
|
|---|
| 316 | * @param hLdrMod The loader module handle.
|
|---|
| 317 | * @param pszSymbol Symbol name. NULL if ordinal only.
|
|---|
| 318 | * @param uSymbol Symbol ordinal, ~0 if not used.
|
|---|
| 319 | * @param Value Symbol value.
|
|---|
| 320 | * @param pvUser The user argument specified to RTLdrEnumSymbols().
|
|---|
| 321 | */
|
|---|
| 322 | typedef DECLCALLBACK(int) RTLDRENUMSYMS(RTLDRMOD hLdrMod, const char *pszSymbol, unsigned uSymbol, RTLDRADDR Value, void *pvUser);
|
|---|
| 323 | /** Pointer to a RTLDRENUMSYMS() callback function. */
|
|---|
| 324 | typedef RTLDRENUMSYMS *PFNRTLDRENUMSYMS;
|
|---|
| 325 |
|
|---|
| 326 | /**
|
|---|
| 327 | * Enumerates all symbols in a module.
|
|---|
| 328 | *
|
|---|
| 329 | * @returns iprt status code.
|
|---|
| 330 | * @param hLdrMod The loader module handle.
|
|---|
| 331 | * @param fFlags Flags indicating what to return and such.
|
|---|
| 332 | * @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
|
|---|
| 333 | * Set this to NULL if no RTLdrGetBits() processed image bits are available.
|
|---|
| 334 | * @param BaseAddress Image load address.
|
|---|
| 335 | * @param pfnCallback Callback function.
|
|---|
| 336 | * @param pvUser User argument for the callback.
|
|---|
| 337 | * @remark Not supported for RTLdrLoad() images.
|
|---|
| 338 | */
|
|---|
| 339 | RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTLDRADDR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void *pvUser);
|
|---|
| 340 |
|
|---|
| 341 | /** @name RTLdrEnumSymbols flags.
|
|---|
| 342 | * @{ */
|
|---|
| 343 | /** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
|
|---|
| 344 | #define RTLDR_ENUM_SYMBOL_FLAGS_ALL RT_BIT(1)
|
|---|
| 345 | /** @} */
|
|---|
| 346 |
|
|---|
| 347 |
|
|---|
| 348 | /**
|
|---|
| 349 | * Debug info type (as far the loader can tell).
|
|---|
| 350 | */
|
|---|
| 351 | typedef enum RTLDRDBGINFOTYPE
|
|---|
| 352 | {
|
|---|
| 353 | /** The invalid 0 value. */
|
|---|
| 354 | RTLDRDBGINFOTYPE_INVALID = 0,
|
|---|
| 355 | /** Unknown debug info format. */
|
|---|
| 356 | RTLDRDBGINFOTYPE_UNKNOWN,
|
|---|
| 357 | /** Stabs. */
|
|---|
| 358 | RTLDRDBGINFOTYPE_STABS,
|
|---|
| 359 | /** Debug With Arbitrary Record Format (DWARF). */
|
|---|
| 360 | RTLDRDBGINFOTYPE_DWARF,
|
|---|
| 361 | /** Microsoft Codeview debug info. */
|
|---|
| 362 | RTLDRDBGINFOTYPE_CODEVIEW,
|
|---|
| 363 | /** Watcom debug info. */
|
|---|
| 364 | RTLDRDBGINFOTYPE_WATCOM,
|
|---|
| 365 | /** IBM High Level Language debug info.. */
|
|---|
| 366 | RTLDRDBGINFOTYPE_HLL,
|
|---|
| 367 | /** The end of the valid debug info values (exclusive). */
|
|---|
| 368 | RTLDRDBGINFOTYPE_END,
|
|---|
| 369 | /** Blow the type up to 32-bits. */
|
|---|
| 370 | RTLDRDBGINFOTYPE_32BIT_HACK = 0x7fffffff
|
|---|
| 371 | } RTLDRDBGINFOTYPE;
|
|---|
| 372 |
|
|---|
| 373 | /**
|
|---|
| 374 | * Debug info enumerator callback.
|
|---|
| 375 | *
|
|---|
| 376 | * @returns VINF_SUCCESS to continue the enumeration. Any other status code
|
|---|
| 377 | * will cause RTLdrEnumDbgInfo to immediately return with that status.
|
|---|
| 378 | *
|
|---|
| 379 | * @param hLdrMod The module handle.
|
|---|
| 380 | * @param iDbgInfo The debug info ordinal number / id.
|
|---|
| 381 | * @param enmType The debug info type.
|
|---|
| 382 | * @param iMajorVer The major version number of the debug info format.
|
|---|
| 383 | * -1 if unknow - implies invalid iMinorVer.
|
|---|
| 384 | * @param iMinorVer The minor version number of the debug info format.
|
|---|
| 385 | * -1 when iMajorVer is -1.
|
|---|
| 386 | * @param pszPartNm The name of the debug info part, NULL if not
|
|---|
| 387 | * applicable.
|
|---|
| 388 | * @param offFile The file offset *if* this type has one specific
|
|---|
| 389 | * location in the executable image file. This is -1
|
|---|
| 390 | * if there isn't any specific file location.
|
|---|
| 391 | * @param LinkAddress The link address of the debug info if it's
|
|---|
| 392 | * loadable. NIL_RTLDRADDR if not loadable.
|
|---|
| 393 | * @param cb The size of the debug information. -1 is used if
|
|---|
| 394 | * this isn't applicable.
|
|---|
| 395 | * @param pszExtFile This points to the name of an external file
|
|---|
| 396 | * containing the debug info. This is NULL if there
|
|---|
| 397 | * isn't any external file.
|
|---|
| 398 | * @param pvUser The user parameter specified to RTLdrEnumDbgInfo.
|
|---|
| 399 | */
|
|---|
| 400 | typedef DECLCALLBACK(int) FNRTLDRENUMDBG(RTLDRMOD hLdrMod, uint32_t iDbgInfo, RTLDRDBGINFOTYPE enmType,
|
|---|
| 401 | uint16_t iMajorVer, uint16_t iMinorVer, const char *pszPartNm,
|
|---|
| 402 | RTFOFF offFile, RTLDRADDR LinkAddress, RTLDRADDR cb,
|
|---|
| 403 | const char *pszExtFile, void *pvUser);
|
|---|
| 404 | /** Pointer to a debug info enumerator callback. */
|
|---|
| 405 | typedef FNRTLDRENUMDBG *PFNRTLDRENUMDBG;
|
|---|
| 406 |
|
|---|
| 407 | /**
|
|---|
| 408 | * Enumerate the debug info contained in the executable image.
|
|---|
| 409 | *
|
|---|
| 410 | * @returns IPRT status code or whatever pfnCallback returns.
|
|---|
| 411 | *
|
|---|
| 412 | * @param hLdrMod The module handle.
|
|---|
| 413 | * @param pvBits Optional pointer to bits returned by
|
|---|
| 414 | * RTLdrGetBits(). This can be used by some module
|
|---|
| 415 | * interpreters to reduce memory consumption.
|
|---|
| 416 | * @param pfnCallback The callback function.
|
|---|
| 417 | * @param pvUser The user argument.
|
|---|
| 418 | */
|
|---|
| 419 | RTDECL(int) RTLdrEnumDbgInfo(RTLDRMOD hLdrMod, const void *pvBits, PFNRTLDRENUMDBG pfnCallback, void *pvUser);
|
|---|
| 420 |
|
|---|
| 421 |
|
|---|
| 422 | /**
|
|---|
| 423 | * Loader segment.
|
|---|
| 424 | */
|
|---|
| 425 | typedef struct RTLDRSEG
|
|---|
| 426 | {
|
|---|
| 427 | /** The segment name. (Might not be zero terminated!) */
|
|---|
| 428 | const char *pchName;
|
|---|
| 429 | /** The length of the segment name. */
|
|---|
| 430 | uint32_t cchName;
|
|---|
| 431 | /** The flat selector to use for the segment (i.e. data/code).
|
|---|
| 432 | * Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
|
|---|
| 433 | uint16_t SelFlat;
|
|---|
| 434 | /** The 16-bit selector to use for the segment.
|
|---|
| 435 | * Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
|
|---|
| 436 | uint16_t Sel16bit;
|
|---|
| 437 | /** Segment flags. */
|
|---|
| 438 | uint32_t fFlags;
|
|---|
| 439 | /** The segment protection (RTMEM_PROT_XXX). */
|
|---|
| 440 | uint32_t fProt;
|
|---|
| 441 | /** The size of the segment. */
|
|---|
| 442 | RTLDRADDR cb;
|
|---|
| 443 | /** The required segment alignment.
|
|---|
| 444 | * The to 0 if the segment isn't supposed to be mapped. */
|
|---|
| 445 | RTLDRADDR Alignment;
|
|---|
| 446 | /** The link address.
|
|---|
| 447 | * Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped or if
|
|---|
| 448 | * the image doesn't have link addresses. */
|
|---|
| 449 | RTLDRADDR LinkAddress;
|
|---|
| 450 | /** File offset of the segment.
|
|---|
| 451 | * Set to -1 if no file backing (like BSS). */
|
|---|
| 452 | RTFOFF offFile;
|
|---|
| 453 | /** Size of the file bits of the segment.
|
|---|
| 454 | * Set to -1 if no file backing (like BSS). */
|
|---|
| 455 | RTFOFF cbFile;
|
|---|
| 456 | /** The relative virtual address when mapped.
|
|---|
| 457 | * Set to NIL_RTLDRADDR if the segment isn't supposed to be mapped. */
|
|---|
| 458 | RTLDRADDR RVA;
|
|---|
| 459 | /** The size of the segment including the alignment gap up to the next segment when mapped.
|
|---|
| 460 | * This is set to NIL_RTLDRADDR if not implemented. */
|
|---|
| 461 | RTLDRADDR cbMapped;
|
|---|
| 462 | } RTLDRSEG;
|
|---|
| 463 | /** Pointer to a loader segment. */
|
|---|
| 464 | typedef RTLDRSEG *PRTLDRSEG;
|
|---|
| 465 | /** Pointer to a read only loader segment. */
|
|---|
| 466 | typedef RTLDRSEG const *PCRTLDRSEG;
|
|---|
| 467 |
|
|---|
| 468 |
|
|---|
| 469 | /** @name Segment flags
|
|---|
| 470 | * @{ */
|
|---|
| 471 | /** The segment is 16-bit. When not set the default of the target architecture is assumed. */
|
|---|
| 472 | #define RTLDRSEG_FLAG_16BIT UINT32_C(1)
|
|---|
| 473 | /** The segment requires a 16-bit selector alias. (OS/2) */
|
|---|
| 474 | #define RTLDRSEG_FLAG_OS2_ALIAS16 UINT32_C(2)
|
|---|
| 475 | /** Conforming segment (x86 weirdness). (OS/2) */
|
|---|
| 476 | #define RTLDRSEG_FLAG_OS2_CONFORM UINT32_C(4)
|
|---|
| 477 | /** IOPL (ring-2) segment. (OS/2) */
|
|---|
| 478 | #define RTLDRSEG_FLAG_OS2_IOPL UINT32_C(8)
|
|---|
| 479 | /** @} */
|
|---|
| 480 |
|
|---|
| 481 | /**
|
|---|
| 482 | * Segment enumerator callback.
|
|---|
| 483 | *
|
|---|
| 484 | * @returns VINF_SUCCESS to continue the enumeration. Any other status code
|
|---|
| 485 | * will cause RTLdrEnumSegments to immediately return with that
|
|---|
| 486 | * status.
|
|---|
| 487 | *
|
|---|
| 488 | * @param hLdrMod The module handle.
|
|---|
| 489 | * @param pSeg The segment information.
|
|---|
| 490 | * @param pvUser The user parameter specified to RTLdrEnumSegments.
|
|---|
| 491 | */
|
|---|
| 492 | typedef DECLCALLBACK(int) FNRTLDRENUMSEGS(RTLDRMOD hLdrMod, PCRTLDRSEG pSeg, void *pvUser);
|
|---|
| 493 | /** Pointer to a segment enumerator callback. */
|
|---|
| 494 | typedef FNRTLDRENUMSEGS *PFNRTLDRENUMSEGS;
|
|---|
| 495 |
|
|---|
| 496 | /**
|
|---|
| 497 | * Enumerate the debug info contained in the executable image.
|
|---|
| 498 | *
|
|---|
| 499 | * @returns IPRT status code or whatever pfnCallback returns.
|
|---|
| 500 | *
|
|---|
| 501 | * @param hLdrMod The module handle.
|
|---|
| 502 | * @param pfnCallback The callback function.
|
|---|
| 503 | * @param pvUser The user argument.
|
|---|
| 504 | */
|
|---|
| 505 | RTDECL(int) RTLdrEnumSegments(RTLDRMOD hLdrMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser);
|
|---|
| 506 |
|
|---|
| 507 | /**
|
|---|
| 508 | * Converts a link address to a segment:offset address.
|
|---|
| 509 | *
|
|---|
| 510 | * @returns IPRT status code.
|
|---|
| 511 | *
|
|---|
| 512 | * @param hLdrMod The module handle.
|
|---|
| 513 | * @param LinkAddress The link address to convert.
|
|---|
| 514 | * @param piSeg Where to return the segment index.
|
|---|
| 515 | * @param poffSeg Where to return the segment offset.
|
|---|
| 516 | */
|
|---|
| 517 | RTDECL(int) RTLdrLinkAddressToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, uint32_t *piSeg, PRTLDRADDR poffSeg);
|
|---|
| 518 |
|
|---|
| 519 | /**
|
|---|
| 520 | * Converts a link address to an image relative virtual address (RVA).
|
|---|
| 521 | *
|
|---|
| 522 | * @returns IPRT status code.
|
|---|
| 523 | *
|
|---|
| 524 | * @param hLdrMod The module handle.
|
|---|
| 525 | * @param LinkAddress The link address to convert.
|
|---|
| 526 | * @param pRva Where to return the RVA.
|
|---|
| 527 | */
|
|---|
| 528 | RTDECL(int) RTLdrLinkAddressToRva(RTLDRMOD hLdrMod, RTLDRADDR LinkAddress, PRTLDRADDR pRva);
|
|---|
| 529 |
|
|---|
| 530 | /**
|
|---|
| 531 | * Converts an image relative virtual address (RVA) to a segment:offset.
|
|---|
| 532 | *
|
|---|
| 533 | * @returns IPRT status code.
|
|---|
| 534 | *
|
|---|
| 535 | * @param hLdrMod The module handle.
|
|---|
| 536 | * @param Rva The link address to convert.
|
|---|
| 537 | * @param piSeg Where to return the segment index.
|
|---|
| 538 | * @param poffSeg Where to return the segment offset.
|
|---|
| 539 | */
|
|---|
| 540 | RTDECL(int) RTLdrSegOffsetToRva(RTLDRMOD hLdrMod, uint32_t iSeg, RTLDRADDR offSeg, PRTLDRADDR pRva);
|
|---|
| 541 |
|
|---|
| 542 | /**
|
|---|
| 543 | * Converts a segment:offset into an image relative virtual address (RVA).
|
|---|
| 544 | *
|
|---|
| 545 | * @returns IPRT status code.
|
|---|
| 546 | *
|
|---|
| 547 | * @param hLdrMod The module handle.
|
|---|
| 548 | * @param iSeg The segment index.
|
|---|
| 549 | * @param offSeg The segment offset.
|
|---|
| 550 | * @param pRva Where to return the RVA.
|
|---|
| 551 | */
|
|---|
| 552 | RTDECL(int) RTLdrRvaToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg);
|
|---|
| 553 |
|
|---|
| 554 | RT_C_DECLS_END
|
|---|
| 555 |
|
|---|
| 556 | /** @} */
|
|---|
| 557 |
|
|---|
| 558 | #endif
|
|---|
| 559 |
|
|---|
