ldr.h@ 38581

Last change on this file since 38581 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 `Id`
File size: 17.0 KB

Line
1	/* $Id: ldr.h 38581 2011-08-31 12:43:26Z 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
33	RT_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	*/
97	typedef 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. */
113	typedef struct RTLDRMODINTERNAL *PRTLDRMODINTERNAL;
114
115	/**
116	* Loader module operations.
117	*/
118	typedef 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	* Enumerates the segments in the module.
244	*
245	* @returns iprt status code, which might have been returned by pfnCallback.
246	* @param pMod Pointer to the loader module structure.
247	* @param pfnCallback The callback function which each debug info part is
248	* to be fed to.
249	* @param pvUser User argument to pass to the enumerator.
250	* @remark This is an optional entry point that can be NULL.
251	*/
252	DECLCALLBACKMEMBER(int, pfnEnumSegments)(PRTLDRMODINTERNAL pMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser);
253
254	/**
255	* Converts a link address to a segment:offset address.
256	*
257	* @returns IPRT status code.
258	*
259	* @param pMod Pointer to the loader module structure.
260	* @param LinkAddress The link address to convert.
261	* @param piSeg Where to return the segment index.
262	* @param poffSeg Where to return the segment offset.
263	* @remark This is an optional entry point that can be NULL.
264	*/
265	DECLCALLBACKMEMBER(int, pfnLinkAddressToSegOffset)(PRTLDRMODINTERNAL pMod, RTLDRADDR LinkAddress,
266	uint32_t *piSeg, PRTLDRADDR poffSeg);
267
268	/**
269	* Converts a link address to a RVA.
270	*
271	* @returns IPRT status code.
272	*
273	* @param pMod Pointer to the loader module structure.
274	* @param LinkAddress The link address to convert.
275	* @param pRva Where to return the RVA.
276	* @remark This is an optional entry point that can be NULL.
277	*/
278	DECLCALLBACKMEMBER(int, pfnLinkAddressToRva)(PRTLDRMODINTERNAL pMod, RTLDRADDR LinkAddress, PRTLDRADDR pRva);
279
280	/**
281	* Converts a segment:offset to a RVA.
282	*
283	* @returns IPRT status code.
284	*
285	* @param pMod Pointer to the loader module structure.
286	* @param iSeg The segment index.
287	* @param offSeg The segment offset.
288	* @param pRva Where to return the RVA.
289	* @remark This is an optional entry point that can be NULL.
290	*/
291	DECLCALLBACKMEMBER(int, pfnSegOffsetToRva)(PRTLDRMODINTERNAL pMod, uint32_t iSeg, RTLDRADDR offSeg, PRTLDRADDR pRva);
292
293	/**
294	* Converts a RVA to a segment:offset.
295	*
296	* @returns IPRT status code.
297	*
298	* @param pMod Pointer to the loader module structure.
299	* @param iSeg The segment index.
300	* @param offSeg The segment offset.
301	* @param pRva Where to return the RVA.
302	* @remark This is an optional entry point that can be NULL.
303	*/
304	DECLCALLBACKMEMBER(int, pfnRvaToSegOffset)(PRTLDRMODINTERNAL pMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg);
305
306	/** Dummy entry to make sure we've initialized it all. */
307	RTUINT uDummy;
308	} RTLDROPS;
309	typedef RTLDROPS *PRTLDROPS;
310	typedef const RTLDROPS *PCRTLDROPS;
311
312
313	/** Pointer to a loader reader instance. */
314	typedef struct RTLDRREADER *PRTLDRREADER;
315
316	/**
317	* Loader image reader instance.
318	* The reader will have extra data members following this structure.
319	*/
320	typedef struct RTLDRREADER
321	{
322	/** The name of the image provider. */
323	const char *pszName;
324
325	/**
326	* Reads bytes at a give place in the raw image.
327	*
328	* @returns iprt status code.
329	* @param pReader Pointer to the reader instance.
330	* @param pvBuf Where to store the bits.
331	* @param cb Number of bytes to read.
332	* @param off Where to start reading relative to the start of the raw image.
333	*/
334	DECLCALLBACKMEMBER(int, pfnRead)(PRTLDRREADER pReader, void *pvBuf, size_t cb, RTFOFF off);
335
336	/**
337	* Tells end position of last read.
338	*
339	* @returns position relative to start of the raw image.
340	* @param pReader Pointer to the reader instance.
341	*/
342	DECLCALLBACKMEMBER(RTFOFF, pfnTell)(PRTLDRREADER pReader);
343
344	/**
345	* Gets the size of the raw image bits.
346	*
347	* @returns size of raw image bits in bytes.
348	* @param pReader Pointer to the reader instance.
349	*/
350	DECLCALLBACKMEMBER(RTFOFF, pfnSize)(PRTLDRREADER pReader);
351
352	/**
353	* Map the bits into memory.
354	*
355	* The mapping will be freed upon calling pfnDestroy() if not pfnUnmap()
356	* is called before that. The mapping is read only.
357	*
358	* @returns iprt status code.
359	* @param pReader Pointer to the reader instance.
360	* @param ppvBits Where to store the address of the memory mapping on success.
361	* The size of the mapping can be obtained by calling pfnSize().
362	*/
363	DECLCALLBACKMEMBER(int, pfnMap)(PRTLDRREADER pReader, const void **ppvBits);
364
365	/**
366	* Unmap bits.
367	*
368	* @returns iprt status code.
369	* @param pReader Pointer to the reader instance.
370	* @param pvBits Memory pointer returned by pfnMap().
371	*/
372	DECLCALLBACKMEMBER(int, pfnUnmap)(PRTLDRREADER pReader, const void *pvBits);
373
374	/**
375	* Gets the most appropriate log name.
376	*
377	* @returns Pointer to readonly log name.
378	* @param pReader Pointer to the reader instance.
379	*/
380	DECLCALLBACKMEMBER(const char *, pfnLogName)(PRTLDRREADER pReader);
381
382	/**
383	* Releases all resources associated with the reader instance.
384	* The instance is invalid after this call returns.
385	*
386	* @returns iprt status code.
387	* @param pReader Pointer to the reader instance.
388	*/
389	DECLCALLBACKMEMBER(int, pfnDestroy)(PRTLDRREADER pReader);
390
391	} RTLDRREADER;
392
393
394	/**
395	* Loader module core.
396	*/
397	typedef struct RTLDRMODINTERNAL
398	{
399	/** The loader magic value (RTLDRMOD_MAGIC). */
400	uint32_t u32Magic;
401	/** State. */
402	RTLDRSTATE eState;
403	/** Loader ops. */
404	PCRTLDROPS pOps;
405	} RTLDRMODINTERNAL;
406
407
408	/**
409	* Validates that a loader module handle is valid.
410	*
411	* @returns true if valid.
412	* @returns false if invalid.
413	* @param hLdrMod The loader module handle.
414	*/
415	DECLINLINE(bool) rtldrIsValid(RTLDRMOD hLdrMod)
416	{
417	return VALID_PTR(hLdrMod)
418	&& ((PRTLDRMODINTERNAL)hLdrMod)->u32Magic == RTLDRMOD_MAGIC;
419	}
420
421	int rtldrOpenWithReader(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phMod);
422
423
424	/**
425	* Native loader module.
426	*/
427	typedef struct RTLDRMODNATIVE
428	{
429	/** The core structure. */
430	RTLDRMODINTERNAL Core;
431	/** The native handle. */
432	uintptr_t hNative;
433	} RTLDRMODNATIVE, *PRTLDRMODNATIVE;
434
435	/** @copydoc RTLDROPS::pfnGetSymbol */
436	DECLCALLBACK(int) rtldrNativeGetSymbol(PRTLDRMODINTERNAL pMod, const char pszSymbol, void *ppvValue);
437	/** @copydoc RTLDROPS::pfnClose */
438	DECLCALLBACK(int) rtldrNativeClose(PRTLDRMODINTERNAL pMod);
439
440	/**
441	* Load a native module using the native loader.
442	*
443	* @returns iprt status code.
444	* @param pszFilename The image filename.
445	* @param phHandle Where to store the module handle on success.
446	* @param fFlags See RTLDRFLAGS_.
447	* @param pErrInfo Where to return extended error information. Optional.
448	*/
449	int rtldrNativeLoad(const char pszFilename, uintptr_t phHandle, uint32_t fFlags, PRTERRINFO pErrInfo);
450
451	int rtldrPEOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offNtHdrs, PRTLDRMOD phLdrMod);
452	int rtldrELFOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
453	int rtldrkLdrOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
454	/*int rtldrLXOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offLX, PRTLDRMOD phLdrMod);
455	int rtldrMachoOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offSomething, PRTLDRMOD phLdrMod);*/
456
457
458	RT_C_DECLS_END
459
460	#endif
461

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: