VirtualBox

source: vbox/trunk/src/VBox/Runtime/include/internal/ldr.h@ 38515

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

IPRT: Working on debug info again.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 14.3 KB
Line 
1/* $Id: ldr.h 38515 2011-08-24 14:33:32Z vboxsync $ */
2/** @file
3 * IPRT - Loader Internals.
4 */
5
6/*
7 * Copyright (C) 2006-2007 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27#ifndef ___internal_ldr_h
28#define ___internal_ldr_h
29
30#include <iprt/types.h>
31#include "internal/magics.h"
32
33RT_C_DECLS_BEGIN
34
35
36/*******************************************************************************
37* Defined Constants And Macros *
38*******************************************************************************/
39#ifdef DOXYGEN_RUNNING
40/** @def LDR_WITH_NATIVE
41 * Define this to get native support. */
42# define LDR_WITH_NATIVE
43
44/** @def LDR_WITH_ELF32
45 * Define this to get 32-bit ELF support. */
46# define LDR_WITH_ELF32
47
48/** @def LDR_WITH_ELF64
49 * Define this to get 64-bit ELF support. */
50# define LDR_WITH_ELF64
51
52/** @def LDR_WITH_PE
53 * Define this to get 32-bit and 64-bit PE support. */
54# define LDR_WITH_PE
55
56/** @def LDR_WITH_LX
57 * Define this to get LX support. */
58# define LDR_WITH_LX
59
60/** @def LDR_WITH_MACHO
61 * Define this to get mach-o support (not implemented yet). */
62# define LDR_WITH_MACHO
63#endif /* DOXYGEN_RUNNING */
64
65#if defined(LDR_WITH_ELF32) || defined(LDR_WITH_ELF64)
66/** @def LDR_WITH_ELF
67 * This is defined if any of the ELF versions is requested.
68 */
69# define LDR_WITH_ELF
70#endif
71
72/* These two may clash with winnt.h. */
73#undef IMAGE_DOS_SIGNATURE
74#undef IMAGE_NT_SIGNATURE
75
76
77/** Little endian uint32_t ELF signature ("\x7fELF"). */
78#define IMAGE_ELF_SIGNATURE (0x7f | ('E' << 8) | ('L' << 16) | ('F' << 24))
79/** Little endian uint32_t PE signature ("PE\0\0"). */
80#define IMAGE_NT_SIGNATURE 0x00004550
81/** Little endian uint16_t LX signature ("LX") */
82#define IMAGE_LX_SIGNATURE ('L' | ('X' << 8))
83/** Little endian uint16_t LE signature ("LE") */
84#define IMAGE_LE_SIGNATURE ('L' | ('E' << 8))
85/** Little endian uint16_t NE signature ("NE") */
86#define IMAGE_NE_SIGNATURE ('N' | ('E' << 8))
87/** Little endian uint16_t MZ signature ("MZ"). */
88#define IMAGE_DOS_SIGNATURE ('M' | ('Z' << 8))
89
90
91/*******************************************************************************
92* Structures and Typedefs *
93*******************************************************************************/
94/**
95 * Loader state.
96 */
97typedef enum RTLDRSTATE
98{
99 /** Invalid. */
100 LDR_STATE_INVALID = 0,
101 /** Opened. */
102 LDR_STATE_OPENED,
103 /** The image can no longer be relocated. */
104 LDR_STATE_DONE,
105 /** The image was loaded, not opened. */
106 LDR_STATE_LOADED,
107 /** The usual 32-bit hack. */
108 LDR_STATE_32BIT_HACK = 0x7fffffff
109} RTLDRSTATE;
110
111
112/** Pointer to a loader item. */
113typedef struct RTLDRMODINTERNAL *PRTLDRMODINTERNAL;
114
115/**
116 * Loader module operations.
117 */
118typedef struct RTLDROPS
119{
120 /** The name of the executable format. */
121 const char *pszName;
122
123 /**
124 * Release any resources attached to the module.
125 * The caller will do RTMemFree on pMod on return.
126 *
127 * @returns iprt status code.
128 * @param pMod Pointer to the loader module structure.
129 * @remark Compulsory entry point.
130 */
131 DECLCALLBACKMEMBER(int, pfnClose)(PRTLDRMODINTERNAL pMod);
132
133 /**
134 * Gets a simple symbol.
135 * This entrypoint can be omitted if RTLDROPS::pfnGetSymbolEx() is provided.
136 *
137 * @returns iprt status code.
138 * @param pMod Pointer to the loader module structure.
139 * @param pszSymbol The symbol name.
140 * @param ppvValue Where to store the symbol value.
141 */
142 DECLCALLBACKMEMBER(int, pfnGetSymbol)(PRTLDRMODINTERNAL pMod, const char *pszSymbol, void **ppvValue);
143
144 /**
145 * Called when we're done with getting bits and relocating them.
146 * This is used to release resources used by the loader to support those actions.
147 *
148 * After this call none of the extended loader functions can be called.
149 *
150 * @returns iprt status code.
151 * @param pMod Pointer to the loader module structure.
152 * @remark This is an optional entry point.
153 */
154 DECLCALLBACKMEMBER(int, pfnDone)(PRTLDRMODINTERNAL pMod);
155
156 /**
157 * Enumerates the symbols exported by the module.
158 *
159 * @returns iprt status code, which might have been returned by pfnCallback.
160 * @param pMod Pointer to the loader module structure.
161 * @param fFlags Flags indicating what to return and such.
162 * @param pvBits Pointer to the bits returned by RTLDROPS::pfnGetBits(), optional.
163 * @param BaseAddress The image base addressto use when calculating the symbol values.
164 * @param pfnCallback The callback function which each symbol is to be
165 * fed to.
166 * @param pvUser User argument to pass to the enumerator.
167 * @remark This is an optional entry point.
168 */
169 DECLCALLBACKMEMBER(int, pfnEnumSymbols)(PRTLDRMODINTERNAL pMod, unsigned fFlags, const void *pvBits, RTUINTPTR BaseAddress,
170 PFNRTLDRENUMSYMS pfnCallback, void *pvUser);
171
172
173/* extended functions: */
174
175 /**
176 * Gets the size of the loaded image (i.e. in memory).
177 *
178 * @returns in memory size, in bytes.
179 * @returns ~(size_t)0 if it's not an extended image.
180 * @param pMod Pointer to the loader module structure.
181 * @remark Extended loader feature.
182 */
183 DECLCALLBACKMEMBER(size_t, pfnGetImageSize)(PRTLDRMODINTERNAL pMod);
184
185 /**
186 * Gets the image bits fixed up for a specified address.
187 *
188 * @returns iprt status code.
189 * @param pMod Pointer to the loader module structure.
190 * @param pvBits Where to store the bits. The size of this buffer is equal or
191 * larger to the value returned by pfnGetImageSize().
192 * @param BaseAddress The base address which the image should be fixed up to.
193 * @param pfnGetImport The callback function to use to resolve imports (aka unresolved externals).
194 * @param pvUser User argument to pass to the callback.
195 * @remark Extended loader feature.
196 */
197 DECLCALLBACKMEMBER(int, pfnGetBits)(PRTLDRMODINTERNAL pMod, void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
198
199 /**
200 * Relocate bits obtained using pfnGetBits to a new address.
201 *
202 * @returns iprt status code.
203 * @param pMod Pointer to the loader module structure.
204 * @param pvBits Where to store the bits. The size of this buffer is equal or
205 * larger to the value returned by pfnGetImageSize().
206 * @param NewBaseAddress The base address which the image should be fixed up to.
207 * @param OldBaseAddress The base address which the image is currently fixed up to.
208 * @param pfnGetImport The callback function to use to resolve imports (aka unresolved externals).
209 * @param pvUser User argument to pass to the callback.
210 * @remark Extended loader feature.
211 */
212 DECLCALLBACKMEMBER(int, pfnRelocate)(PRTLDRMODINTERNAL pMod, void *pvBits, RTUINTPTR NewBaseAddress, RTUINTPTR OldBaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
213
214 /**
215 * Gets a symbol with special base address and stuff.
216 * This entrypoint can be omitted if RTLDROPS::pfnGetSymbolEx() is provided and the special BaseAddress feature isn't supported.
217 *
218 * @returns iprt status code.
219 * @param pMod Pointer to the loader module structure.
220 * @param pvBits Pointer to bits returned by RTLDROPS::pfnGetBits(), optional.
221 * @param BaseAddress The image base address to use when calculating the symbol value.
222 * @param pszSymbol The symbol name.
223 * @param pValue Where to store the symbol value.
224 * @remark Extended loader feature.
225 */
226 DECLCALLBACKMEMBER(int, pfnGetSymbolEx)(PRTLDRMODINTERNAL pMod, const void *pvBits, RTUINTPTR BaseAddress, const char *pszSymbol, RTUINTPTR *pValue);
227
228 /**
229 * Enumerates the debug info contained in the module.
230 *
231 * @returns iprt status code, which might have been returned by pfnCallback.
232 * @param pMod Pointer to the loader module structure.
233 * @param pvBits Pointer to the bits returned by RTLDROPS::pfnGetBits(), optional.
234 * @param pfnCallback The callback function which each debug info part is
235 * to be fed to.
236 * @param pvUser User argument to pass to the enumerator.
237 * @remark This is an optional entry point that can be NULL.
238 */
239 DECLCALLBACKMEMBER(int, pfnEnumDbgInfo)(PRTLDRMODINTERNAL pMod, const void *pvBits,
240 PFNRTLDRENUMDBG pfnCallback, void *pvUser);
241
242
243 /** Dummy entry to make sure we've initialized it all. */
244 RTUINT uDummy;
245} RTLDROPS;
246typedef RTLDROPS *PRTLDROPS;
247typedef const RTLDROPS *PCRTLDROPS;
248
249
250/** Pointer to a loader reader instance. */
251typedef struct RTLDRREADER *PRTLDRREADER;
252
253/**
254 * Loader image reader instance.
255 * The reader will have extra data members following this structure.
256 */
257typedef struct RTLDRREADER
258{
259 /** The name of the image provider. */
260 const char *pszName;
261
262 /**
263 * Reads bytes at a give place in the raw image.
264 *
265 * @returns iprt status code.
266 * @param pReader Pointer to the reader instance.
267 * @param pvBuf Where to store the bits.
268 * @param cb Number of bytes to read.
269 * @param off Where to start reading relative to the start of the raw image.
270 */
271 DECLCALLBACKMEMBER(int, pfnRead)(PRTLDRREADER pReader, void *pvBuf, size_t cb, RTFOFF off);
272
273 /**
274 * Tells end position of last read.
275 *
276 * @returns position relative to start of the raw image.
277 * @param pReader Pointer to the reader instance.
278 */
279 DECLCALLBACKMEMBER(RTFOFF, pfnTell)(PRTLDRREADER pReader);
280
281 /**
282 * Gets the size of the raw image bits.
283 *
284 * @returns size of raw image bits in bytes.
285 * @param pReader Pointer to the reader instance.
286 */
287 DECLCALLBACKMEMBER(RTFOFF, pfnSize)(PRTLDRREADER pReader);
288
289 /**
290 * Map the bits into memory.
291 *
292 * The mapping will be freed upon calling pfnDestroy() if not pfnUnmap()
293 * is called before that. The mapping is read only.
294 *
295 * @returns iprt status code.
296 * @param pReader Pointer to the reader instance.
297 * @param ppvBits Where to store the address of the memory mapping on success.
298 * The size of the mapping can be obtained by calling pfnSize().
299 */
300 DECLCALLBACKMEMBER(int, pfnMap)(PRTLDRREADER pReader, const void **ppvBits);
301
302 /**
303 * Unmap bits.
304 *
305 * @returns iprt status code.
306 * @param pReader Pointer to the reader instance.
307 * @param pvBits Memory pointer returned by pfnMap().
308 */
309 DECLCALLBACKMEMBER(int, pfnUnmap)(PRTLDRREADER pReader, const void *pvBits);
310
311 /**
312 * Gets the most appropriate log name.
313 *
314 * @returns Pointer to readonly log name.
315 * @param pReader Pointer to the reader instance.
316 */
317 DECLCALLBACKMEMBER(const char *, pfnLogName)(PRTLDRREADER pReader);
318
319 /**
320 * Releases all resources associated with the reader instance.
321 * The instance is invalid after this call returns.
322 *
323 * @returns iprt status code.
324 * @param pReader Pointer to the reader instance.
325 */
326 DECLCALLBACKMEMBER(int, pfnDestroy)(PRTLDRREADER pReader);
327
328} RTLDRREADER;
329
330
331/**
332 * Loader module core.
333 */
334typedef struct RTLDRMODINTERNAL
335{
336 /** The loader magic value (RTLDRMOD_MAGIC). */
337 uint32_t u32Magic;
338 /** State. */
339 RTLDRSTATE eState;
340 /** Loader ops. */
341 PCRTLDROPS pOps;
342} RTLDRMODINTERNAL;
343
344
345/**
346 * Validates that a loader module handle is valid.
347 *
348 * @returns true if valid.
349 * @returns false if invalid.
350 * @param hLdrMod The loader module handle.
351 */
352DECLINLINE(bool) rtldrIsValid(RTLDRMOD hLdrMod)
353{
354 return VALID_PTR(hLdrMod)
355 && ((PRTLDRMODINTERNAL)hLdrMod)->u32Magic == RTLDRMOD_MAGIC;
356}
357
358int rtldrOpenWithReader(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phMod);
359
360
361/**
362 * Native loader module.
363 */
364typedef struct RTLDRMODNATIVE
365{
366 /** The core structure. */
367 RTLDRMODINTERNAL Core;
368 /** The native handle. */
369 uintptr_t hNative;
370} RTLDRMODNATIVE, *PRTLDRMODNATIVE;
371
372/** @copydoc RTLDROPS::pfnGetSymbol */
373DECLCALLBACK(int) rtldrNativeGetSymbol(PRTLDRMODINTERNAL pMod, const char *pszSymbol, void **ppvValue);
374/** @copydoc RTLDROPS::pfnClose */
375DECLCALLBACK(int) rtldrNativeClose(PRTLDRMODINTERNAL pMod);
376
377/**
378 * Load a native module using the native loader.
379 *
380 * @returns iprt status code.
381 * @param pszFilename The image filename.
382 * @param phHandle Where to store the module handle on success.
383 * @param fFlags See RTLDRFLAGS_.
384 * @param pErrInfo Where to return extended error information. Optional.
385 */
386int rtldrNativeLoad(const char *pszFilename, uintptr_t *phHandle, uint32_t fFlags, PRTERRINFO pErrInfo);
387
388int rtldrPEOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offNtHdrs, PRTLDRMOD phLdrMod);
389int rtldrELFOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
390int rtldrkLdrOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
391/*int rtldrLXOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offLX, PRTLDRMOD phLdrMod);
392int rtldrMachoOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offSomething, PRTLDRMOD phLdrMod);*/
393
394
395RT_C_DECLS_END
396
397#endif
398
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