ldr.h@ 51770

Last change on this file since 51770 was 51770, checked in by vboxsync, 10 years ago
Merged in iprt++ dev branch.
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 18.6 KB

Line
1	/* $Id: ldr.h 51770 2014-07-01 18:14:02Z 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 pMod Pointer to the loader module structure.
315	* @param pvBuf The buffer to read into.
316	* @param iDbgInfo The debug info ordinal number if the request
317	* corresponds exactly to a debug info part from
318	* pfnEnumDbgInfo. Otherwise, pass UINT32_MAX.
319	* @param off The offset into the image file.
320	* @param cb The number of bytes to read.
321	* @param pMod Pointer to the loader module structure.
322	*/
323	DECLCALLBACKMEMBER(int, pfnReadDbgInfo)(PRTLDRMODINTERNAL pMod, uint32_t iDbgInfo, RTFOFF off, size_t cb, void *pvBuf);
324
325	/**
326	* Generic method for querying image properties.
327	*
328	* @returns IPRT status code.
329	* @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
330	* or that specific property).
331	* @retval VERR_NOT_FOUND the property was not found in the module.
332	*
333	* @param pMod Pointer to the loader module structure.
334	* @param enmLdrProp The property to query (valid).
335	* @param pvBuf Pointer to the return buffer (valid).
336	* @param cbBuf The size of the return buffer (valid as per
337	* property).
338	* @param pcbRet The number of bytes actually returned. If
339	* VERR_BUFFER_OVERFLOW is returned, this is set to the
340	* required buffer size.
341	*/
342	DECLCALLBACKMEMBER(int, pfnQueryProp)(PRTLDRMODINTERNAL pMod, RTLDRPROP enmProp, void pvBuf, size_t cbBuf, size_t pcbRet);
343
344	/**
345	* Verify the image signature.
346	*
347	* This may permform additional integrity checks on the image structures that
348	* was not done when opening the image.
349	*
350	* @returns IPRT status code.
351	* @retval VERR_LDRVI_NOT_SIGNED if not signed.
352	*
353	* @param pMod Pointer to the loader module structure.
354	* @param pfnCallback Callback that does the signature and certificate
355	* verficiation.
356	* @param pvUser User argument for the callback.
357	* @param pErrInfo Pointer to an error info buffer. Optional.
358	*/
359	DECLCALLBACKMEMBER(int, pfnVerifySignature)(PRTLDRMODINTERNAL pMod, PFNRTLDRVALIDATESIGNEDDATA pfnCallback, void *pvUser,
360	PRTERRINFO pErrInfo);
361
362	/**
363	* Calculate the image hash according the image signing rules.
364	*
365	* @returns IPRT status code.
366	* @param hLdrMod The module handle.
367	* @param enmDigest Which kind of digest.
368	* @param pszDigest Where to store the image digest.
369	* @param cbDigest Size of the buffer @a pszDigest points at.
370	*/
371	DECLCALLBACKMEMBER(int, pfnHashImage)(PRTLDRMODINTERNAL pMod, RTDIGESTTYPE enmDigest, char *pszDigest, size_t cbDigest);
372
373	/** Dummy entry to make sure we've initialized it all. */
374	RTUINT uDummy;
375	} RTLDROPS;
376	typedef RTLDROPS *PRTLDROPS;
377	typedef const RTLDROPS *PCRTLDROPS;
378
379
380	/**
381	* Loader module core.
382	*/
383	typedef struct RTLDRMODINTERNAL
384	{
385	/** The loader magic value (RTLDRMOD_MAGIC). */
386	uint32_t u32Magic;
387	/** State. */
388	RTLDRSTATE eState;
389	/** Loader ops. */
390	PCRTLDROPS pOps;
391	/** Pointer to the reader instance. This is NULL for native image. */
392	PRTLDRREADER pReader;
393	/** Image format. */
394	RTLDRFMT enmFormat;
395	/** Image type. */
396	RTLDRTYPE enmType;
397	/** Image endianness. */
398	RTLDRENDIAN enmEndian;
399	/** Image target architecture. */
400	RTLDRARCH enmArch;
401	} RTLDRMODINTERNAL;
402
403
404	/**
405	* Validates that a loader module handle is valid.
406	*
407	* @returns true if valid.
408	* @returns false if invalid.
409	* @param hLdrMod The loader module handle.
410	*/
411	DECLINLINE(bool) rtldrIsValid(RTLDRMOD hLdrMod)
412	{
413	return VALID_PTR(hLdrMod)
414	&& ((PRTLDRMODINTERNAL)hLdrMod)->u32Magic == RTLDRMOD_MAGIC;
415	}
416
417
418	/**
419	* Native loader module.
420	*/
421	typedef struct RTLDRMODNATIVE
422	{
423	/** The core structure. */
424	RTLDRMODINTERNAL Core;
425	/** The native handle. */
426	uintptr_t hNative;
427	/** The load flags (RTLDRLOAD_FLAGS_XXX). */
428	uint32_t fFlags;
429	} RTLDRMODNATIVE;
430	/** Pointer to a native module. */
431	typedef RTLDRMODNATIVE *PRTLDRMODNATIVE;
432
433	/** @copydoc RTLDROPS::pfnGetSymbol */
434	DECLCALLBACK(int) rtldrNativeGetSymbol(PRTLDRMODINTERNAL pMod, const char pszSymbol, void *ppvValue);
435	/** @copydoc RTLDROPS::pfnClose */
436	DECLCALLBACK(int) rtldrNativeClose(PRTLDRMODINTERNAL pMod);
437
438	/**
439	* Load a native module using the native loader.
440	*
441	* @returns iprt status code.
442	* @param pszFilename The image filename.
443	* @param phHandle Where to store the module handle on success.
444	* @param fFlags RTLDRLOAD_FLAGS_XXX.
445	* @param pErrInfo Where to return extended error information. Optional.
446	*/
447	int rtldrNativeLoad(const char pszFilename, uintptr_t phHandle, uint32_t fFlags, PRTERRINFO pErrInfo);
448
449	/**
450	* Load a system library.
451	*
452	* @returns iprt status code.
453	* @param pszFilename The image filename.
454	* @param pszExt Extension to add. NULL if none.
455	* @param fFlags RTLDRLOAD_FLAGS_XXX.
456	* @param phLdrMod Where to return the module handle on success.
457	*/
458	int rtldrNativeLoadSystem(const char pszFilename, const char pszExt, uint32_t fFlags, PRTLDRMOD phLdrMod);
459
460	int rtldrPEOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offNtHdrs, PRTLDRMOD phLdrMod, PRTERRINFO pErrInfo);
461	int rtldrELFOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod, PRTERRINFO pErrInfo);
462	int rtldrkLdrOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod, PRTERRINFO pErrInfo);
463	/*int rtldrLXOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offLX, PRTLDRMOD phLdrMod);
464	int rtldrMachoOpen(PRTLDRREADER pReader, uint32_t fFlags, RTLDRARCH enmArch, RTFOFF offSomething, PRTLDRMOD phLdrMod);*/
465
466
467	DECLHIDDEN(int) rtLdrReadAt(RTLDRMOD hLdrMod, void *pvBuf, uint32_t iDbgInfo, RTFOFF off, size_t cb);
468
469	RT_C_DECLS_END
470
471	#endif
472

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

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

Download in other formats: