VirtualBox

source: vbox/trunk/include/iprt/ldr.h@ 40387

Last change on this file since 40387 was 38581, checked in by vboxsync, 13 years ago

IPRT: More debug info & ldr stuff.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.9 KB
Line 
1/** @file
2 * IPRT - Loader.
3 */
4
5/*
6 * Copyright (C) 2006-2007 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
39RT_C_DECLS_BEGIN
40
41/** Loader address (unsigned integer). */
42typedef RTUINTPTR RTLDRADDR;
43/** Pointer to a loader address. */
44typedef RTLDRADDR *PRTLDRADDR;
45/** Pointer to a const loader address. */
46typedef 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 */
58RTDECL(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 */
68RTDECL(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 */
86RTDECL(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 */
106RTDECL(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 */
130RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
131
132/**
133 * Image architecuture specifier for RTLdrOpenEx.
134 */
135typedef 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. */
152typedef 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 */
163RTDECL(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 */
175RTDECL(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 */
180typedef 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 */
209RTDECL(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 */
220RTDECL(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 */
231RTDECL(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 */
250RTDECL(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 */
262RTDECL(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 */
275typedef 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. */
278typedef 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 */
293RTDECL(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 */
309RTDECL(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 */
322typedef DECLCALLBACK(int) RTLDRENUMSYMS(RTLDRMOD hLdrMod, const char *pszSymbol, unsigned uSymbol, RTLDRADDR Value, void *pvUser);
323/** Pointer to a RTLDRENUMSYMS() callback function. */
324typedef 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 */
339RTDECL(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 */
351typedef 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 */
400typedef 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. */
405typedef 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 */
419RTDECL(int) RTLdrEnumDbgInfo(RTLDRMOD hLdrMod, const void *pvBits, PFNRTLDRENUMDBG pfnCallback, void *pvUser);
420
421
422/**
423 * Loader segment.
424 */
425typedef 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. */
464typedef RTLDRSEG *PRTLDRSEG;
465/** Pointer to a read only loader segment. */
466typedef 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 */
492typedef DECLCALLBACK(int) FNRTLDRENUMSEGS(RTLDRMOD hLdrMod, PCRTLDRSEG pSeg, void *pvUser);
493/** Pointer to a segment enumerator callback. */
494typedef 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 */
505RTDECL(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 */
517RTDECL(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 */
528RTDECL(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 */
540RTDECL(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 */
552RTDECL(int) RTLdrRvaToSegOffset(RTLDRMOD hLdrMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg);
553
554RT_C_DECLS_END
555
556/** @} */
557
558#endif
559
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