ldr.h@ 47559

Last change on this file since 47559 was 46593, checked in by vboxsync, 12 years ago
updates
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 18.9 KB

Line
1	/* $Id: ldr.h 46593 2013-06-17 14:32:51Z vboxsync $ */
2	/** @file
3	* IPRT - Loader Internals.
4	*/
5
6	/*
7	* Copyright (C) 2006-2011 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 Rva The RVA to convert.
300	* @param piSeg Where to return the segment index.
301	* @param poffSeg Where to return the segment offset.
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	/**
307	* Reads a debug info part (section) from the image.
308	*
309	* This is primarily needed for getting DWARF sections in ELF image with fixups
310	* applied and won't be required by most other loader backends.
311	*
312	* @returns IPRT status code.
313	*
314	* @param pvBuf The buffer to read into.
315	* @param iDbgInfo The debug info ordinal number if the request
316	* corresponds exactly to a debug info part from
317	* pfnEnumDbgInfo. Otherwise, pass UINT32_MAX.
318	* @param off The offset into the image file.
319	* @param cb The number of bytes to read.
320	* @param pMod Pointer to the loader module structure.
321	*/
322	DECLCALLBACKMEMBER(int, pfnReadDbgInfo)(PRTLDRMODINTERNAL pMod, uint32_t iDbgInfo, RTFOFF off, size_t cb, void *pvBuf);
323
324	/** Dummy entry to make sure we've initialized it all. */
325	RTUINT uDummy;
326	} RTLDROPS;
327	typedef RTLDROPS *PRTLDROPS;
328	typedef const RTLDROPS *PCRTLDROPS;
329
330
331	/** Pointer to a loader reader instance. */
332	typedef struct RTLDRREADER *PRTLDRREADER;
333
334	/**
335	* Loader image reader instance.
336	* The reader will have extra data members following this structure.
337	*/
338	typedef struct RTLDRREADER
339	{
340	/** The name of the image provider. */
341	const char *pszName;
342
343	/**
344	* Reads bytes at a give place in the raw image.
345	*
346	* @returns iprt status code.
347	* @param pReader Pointer to the reader instance.
348	* @param pvBuf Where to store the bits.
349	* @param cb Number of bytes to read.
350	* @param off Where to start reading relative to the start of the raw image.
351	*/
352	DECLCALLBACKMEMBER(int, pfnRead)(PRTLDRREADER pReader, void *pvBuf, size_t cb, RTFOFF off);
353
354	/**
355	* Tells end position of last read.
356	*
357	* @returns position relative to start of the raw image.
358	* @param pReader Pointer to the reader instance.
359	*/
360	DECLCALLBACKMEMBER(RTFOFF, pfnTell)(PRTLDRREADER pReader);
361
362	/**
363	* Gets the size of the raw image bits.
364	*
365	* @returns size of raw image bits in bytes.
366	* @param pReader Pointer to the reader instance.
367	*/
368	DECLCALLBACKMEMBER(RTFOFF, pfnSize)(PRTLDRREADER pReader);
369
370	/**
371	* Map the bits into memory.
372	*
373	* The mapping will be freed upon calling pfnDestroy() if not pfnUnmap()
374	* is called before that. The mapping is read only.
375	*
376	* @returns iprt status code.
377	* @param pReader Pointer to the reader instance.
378	* @param ppvBits Where to store the address of the memory mapping on success.
379	* The size of the mapping can be obtained by calling pfnSize().
380	*/
381	DECLCALLBACKMEMBER(int, pfnMap)(PRTLDRREADER pReader, const void **ppvBits);
382
383	/**
384	* Unmap bits.
385	*
386	* @returns iprt status code.
387	* @param pReader Pointer to the reader instance.
388	* @param pvBits Memory pointer returned by pfnMap().
389	*/
390	DECLCALLBACKMEMBER(int, pfnUnmap)(PRTLDRREADER pReader, const void *pvBits);
391
392	/**
393	* Gets the most appropriate log name.
394	*
395	* @returns Pointer to readonly log name.
396	* @param pReader Pointer to the reader instance.
397	*/
398	DECLCALLBACKMEMBER(const char *, pfnLogName)(PRTLDRREADER pReader);
399
400	/**
401	* Releases all resources associated with the reader instance.
402	* The instance is invalid after this call returns.
403	*
404	* @returns iprt status code.
405	* @param pReader Pointer to the reader instance.
406	*/
407	DECLCALLBACKMEMBER(int, pfnDestroy)(PRTLDRREADER pReader);
408
409	} RTLDRREADER;
410
411
412	/**
413	* Loader module core.
414	*/
415	typedef struct RTLDRMODINTERNAL
416	{
417	/** The loader magic value (RTLDRMOD_MAGIC). */
418	uint32_t u32Magic;
419	/** State. */
420	RTLDRSTATE eState;
421	/** Loader ops. */
422	PCRTLDROPS pOps;
423	/** Pointer to the reader instance. This is NULL for native image. */
424	PRTLDRREADER pReader;
425	/** Image format. */
426	RTLDRFMT enmFormat;
427	/** Image type. */
428	RTLDRTYPE enmType;
429	/** Image endianness. */
430	RTLDRENDIAN enmEndian;
431	/** Image target architecture. */
432	RTLDRARCH enmArch;
433	} RTLDRMODINTERNAL;
434
435
436	/**
437	* Validates that a loader module handle is valid.
438	*
439	* @returns true if valid.
440	* @returns false if invalid.
441	* @param hLdrMod The loader module handle.
442	*/
443	DECLINLINE(bool) rtldrIsValid(RTLDRMOD hLdrMod)
444	{
445	return VALID_PTR(hLdrMod)
446	&& ((PRTLDRMODINTERNAL)hLdrMod)->u32Magic == RTLDRMOD_MAGIC;
447	}
448
449	int rtldrOpenWithReader(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phMod);
450
451
452	/**
453	* Native loader module.
454	*/
455	typedef struct RTLDRMODNATIVE
456	{
457	/** The core structure. */
458	RTLDRMODINTERNAL Core;
459	/** The native handle. */
460	uintptr_t hNative;
461	/** The load flags (RTLDRLOAD_FLAGS_XXX). */
462	uint32_t fFlags;
463	} RTLDRMODNATIVE;
464	/** Pointer to a native module. */
465	typedef RTLDRMODNATIVE *PRTLDRMODNATIVE;
466
467	/** @copydoc RTLDROPS::pfnGetSymbol */
468	DECLCALLBACK(int) rtldrNativeGetSymbol(PRTLDRMODINTERNAL pMod, const char pszSymbol, void *ppvValue);
469	/** @copydoc RTLDROPS::pfnClose */
470	DECLCALLBACK(int) rtldrNativeClose(PRTLDRMODINTERNAL pMod);
471
472	/**
473	* Load a native module using the native loader.
474	*
475	* @returns iprt status code.
476	* @param pszFilename The image filename.
477	* @param phHandle Where to store the module handle on success.
478	* @param fFlags RTLDRLOAD_FLAGS_XXX.
479	* @param pErrInfo Where to return extended error information. Optional.
480	*/
481	int rtldrNativeLoad(const char pszFilename, uintptr_t phHandle, uint32_t fFlags, PRTERRINFO pErrInfo);
482
483	/**
484	* Load a system library.
485	*
486	* @returns iprt status code.
487	* @param pszFilename The image filename.
488	* @param pszExt Extension to add. NULL if none.
489	* @param fFlags RTLDRLOAD_FLAGS_XXX.
490	* @param phLdrMod Where to return the module handle on success.
491	*/
492	int rtldrNativeLoadSystem(const char pszFilename, const char pszExt, uint32_t fFlags, PRTLDRMOD phLdrMod);
493
494	int rtldrPEOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offNtHdrs, PRTLDRMOD phLdrMod);
495	int rtldrELFOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
496	int rtldrkLdrOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
497	/*int rtldrLXOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offLX, PRTLDRMOD phLdrMod);
498	int rtldrMachoOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offSomething, PRTLDRMOD phLdrMod);*/
499
500
501	DECLHIDDEN(int) rtLdrReadAt(RTLDRMOD hLdrMod, void *pvBuf, uint32_t iDbgInfo, RTFOFF off, size_t cb);
502
503	RT_C_DECLS_END
504
505	#endif
506

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

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

Download in other formats: