kLdrMod.c@ 49

Last change on this file since 49 was 41, checked in by bird, 13 years ago
Debug info enumration adjustments. Working on MH_DSYM support.
Property svn:keywords set to `Id Revision`
File size: 33.3 KB

Line
1	/* $Id: kLdrMod.c 41 2011-08-24 14:35:57Z bird $ */
2	/** @file
3	* kLdr - The Module Interpreter.
4	*/
5
6	/*
7	* Copyright (c) 2006-2007 Knut St. Osmundsen <[email protected]>
8	*
9	* Permission is hereby granted, free of charge, to any person
10	* obtaining a copy of this software and associated documentation
11	* files (the "Software"), to deal in the Software without
12	* restriction, including without limitation the rights to use,
13	* copy, modify, merge, publish, distribute, sublicense, and/or sell
14	* copies of the Software, and to permit persons to whom the
15	* Software is furnished to do so, subject to the following
16	* conditions:
17	*
18	* The above copyright notice and this permission notice shall be
19	* included in all copies or substantial portions of the Software.
20	*
21	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22	* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
23	* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
24	* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
25	* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
26	* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27	* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
28	* OTHER DEALINGS IN THE SOFTWARE.
29	*/
30
31	/*******************************************************************************
32	* Header Files *
33	*******************************************************************************/
34	#include <k/kLdr.h>
35	#include "kLdrInternal.h"
36	#include <k/kCpu.h>
37	#include <k/kLdrFmts/mz.h>
38	#if 1 /* testing headers */
39	# include <k/kLdrFmts/pe.h>
40	# include <k/kLdrFmts/lx.h>
41	# include <k/kLdrFmts/mach-o.h>
42	#endif
43
44
45	/*******************************************************************************
46	* Defined Constants And Macros *
47	*******************************************************************************/
48	/** @def KLDRMOD_STRICT
49	* Define KLDRMOD_STRICT to enabled strict checks in KLDRMOD. */
50	#define KLDRMOD_STRICT 1
51
52	/** @def KLDRMOD_ASSERT
53	* Assert that an expression is true when KLDR_STRICT is defined.
54	*/
55	#ifdef KLDRMOD_STRICT
56	# define KLDRMOD_ASSERT(expr) kHlpAssert(expr)
57	#else
58	# define KLDRMOD_ASSERT(expr) do {} while (0)
59	#endif
60
61	/** Return / crash validation of a module argument. */
62	#define KLDRMOD_VALIDATE_EX(pMod, rc) \
63	do { \
64	if ( (pMod)->u32Magic != KLDRMOD_MAGIC \
65	\|\| (pMod)->pOps == NULL \
66	)\
67	{ \
68	return (rc); \
69	} \
70	} while (0)
71
72	/** Return / crash validation of a module argument. */
73	#define KLDRMOD_VALIDATE(pMod) \
74	KLDRMOD_VALIDATE_EX(pMod, KERR_INVALID_PARAMETER)
75
76	/** Return / crash validation of a module argument. */
77	#define KLDRMOD_VALIDATE_VOID(pMod) \
78	do { \
79	if ( (pMod)->u32Magic != KLDRMOD_MAGIC \
80	\|\| (pMod)->pOps == NULL \
81	)\
82	{ \
83	return; \
84	} \
85	} while (0)
86
87
88	/*******************************************************************************
89	* Global Variables *
90	*******************************************************************************/
91	/** The list of module interpreters. */
92	static PCKLDRMODOPS g_pModInterpreterHead = NULL;
93
94
95
96	/*******************************************************************************
97	* Internal Functions *
98	*******************************************************************************/
99
100
101
102	/**
103	* Open a executable image by file name.
104	*
105	* @returns 0 on success and *ppMod pointing to a module instance.
106	* On failure, a non-zero OS specific error code is returned.
107	* @param pszFilename The filename to open.
108	* @param fFlags Flags, MBZ.
109	* @param enmCpuArch The desired CPU architecture. KCPUARCH_UNKNOWN means
110	* anything goes, but with a preference for the current
111	* host architecture.
112	* @param ppMod Where to store the module handle.
113	*/
114	int kLdrModOpen(const char *pszFilename, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod)
115	{
116	/*
117	* Open the file using a bit provider.
118	*/
119	PKRDR pRdr;
120	int rc = kRdrOpen(&pRdr, pszFilename);
121	if (!rc)
122	{
123	rc = kLdrModOpenFromRdr(pRdr, fFlags, enmCpuArch, ppMod);
124	if (!rc)
125	return 0;
126	kRdrClose(pRdr);
127	}
128	return rc;
129	}
130
131
132	/**
133	* Select image from the FAT according to the enmCpuArch and fFlag.
134	*
135	* @returns 0 on success and *poffHdr set to the image header.
136	* On failure, a non-zero error code is returned.
137	*
138	* @param pRdr The file provider instance to use.
139	* @param fFlags Flags, MBZ.
140	* @param enmCpuArch The desired CPU architecture. KCPUARCH_UNKNOWN means
141	* anything goes, but with a preference for the current
142	* host architecture.
143	* @param u32Magic The FAT magic.
144	* @param poffHdr Where to store the offset of the selected image.
145	*/
146	static int kldrModOpenFromRdrSelectImageFromFAT(PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, KU32 u32Magic, KLDRFOFF *poffHdr)
147	{
148	int rcRet = KLDR_ERR_CPU_ARCH_MISMATCH;
149	KLDRFOFF off = *poffHdr + sizeof(KU32);
150	KLDRFOFF offEndFAT;
151	KBOOL fCpuArchWhatever;
152	KU32 cArchs;
153	KU32 iArch;
154	int rc;
155
156	/* Read fat_header_t::nfat_arch. */
157	rc = kRdrRead(pRdr, &cArchs, sizeof(cArchs), off);
158	if (rc)
159	return rc;
160	off += sizeof(KU32);
161	if (u32Magic == IMAGE_FAT_SIGNATURE_OE)
162	cArchs = K_E2E_U32(cArchs);
163	if (cArchs == 0)
164	return KLDR_ERR_FAT_INVALID;
165
166	/* Deal with KCPUARCH_UNKNOWN. */
167	fCpuArchWhatever = enmCpuArch == KCPUARCH_UNKNOWN;
168	if (fCpuArchWhatever)
169	{
170	KCPU enmCpuIgnored;
171	kCpuGetArchAndCpu(&enmCpuArch, &enmCpuIgnored);
172	}
173
174	/*
175	* Iterate the architecture list.
176	*/
177	offEndFAT = off + cArchs * sizeof(fat_arch_t);
178	for (iArch = 0; iArch < cArchs; iArch++)
179	{
180	KCPUARCH enmEntryArch;
181	fat_arch_t Arch;
182	rc = kRdrRead(pRdr, &Arch, sizeof(Arch), off);
183	if (rc)
184	return rc;
185	off += sizeof(Arch);
186
187	if (u32Magic == IMAGE_FAT_SIGNATURE_OE)
188	{
189	Arch.cputype = K_E2E_U32(Arch.cputype);
190	Arch.cpusubtype = K_E2E_U32(Arch.cpusubtype);
191	Arch.offset = K_E2E_U32(Arch.offset);
192	Arch.size = K_E2E_U32(Arch.size);
193	Arch.align = K_E2E_U32(Arch.align);
194	}
195
196	/* Simple validation. */
197	if ( (KLDRFOFF)Arch.offset < offEndFAT
198	\|\| (KLDRFOFF)Arch.offset >= kRdrSize(pRdr)
199	\|\| Arch.align >= 32
200	\|\| Arch.offset & ((KU32_C(1) << Arch.align) - KU32_C(1)))
201	return KLDR_ERR_FAT_INVALID;
202
203	/* deal with the cputype and cpusubtype. (See similar code in kLdrModMachO.c.) */
204	switch (Arch.cputype)
205	{
206	case CPU_TYPE_X86:
207	enmEntryArch = KCPUARCH_X86_32;
208	switch (Arch.cpusubtype)
209	{
210	case CPU_SUBTYPE_I386_ALL:
211	/case CPU_SUBTYPE_386: ^^ ;/
212	case CPU_SUBTYPE_486:
213	case CPU_SUBTYPE_486SX:
214	/case CPU_SUBTYPE_586: vv /
215	case CPU_SUBTYPE_PENT:
216	case CPU_SUBTYPE_PENTPRO:
217	case CPU_SUBTYPE_PENTII_M3:
218	case CPU_SUBTYPE_PENTII_M5:
219	case CPU_SUBTYPE_CELERON:
220	case CPU_SUBTYPE_CELERON_MOBILE:
221	case CPU_SUBTYPE_PENTIUM_3:
222	case CPU_SUBTYPE_PENTIUM_3_M:
223	case CPU_SUBTYPE_PENTIUM_3_XEON:
224	case CPU_SUBTYPE_PENTIUM_M:
225	case CPU_SUBTYPE_PENTIUM_4:
226	case CPU_SUBTYPE_PENTIUM_4_M:
227	case CPU_SUBTYPE_XEON:
228	case CPU_SUBTYPE_XEON_MP:
229	break;
230	default:
231	return KLDR_ERR_FAT_UNSUPPORTED_CPU_SUBTYPE;
232	}
233	break;
234
235	case CPU_TYPE_X86_64:
236	enmEntryArch = KCPUARCH_AMD64;
237	switch (Arch.cpusubtype & ~CPU_SUBTYPE_MASK)
238	{
239	case CPU_SUBTYPE_X86_64_ALL:
240	break;
241	default:
242	return KLDR_ERR_FAT_UNSUPPORTED_CPU_SUBTYPE;
243	}
244	break;
245
246	default:
247	enmEntryArch = KCPUARCH_UNKNOWN;
248	break;
249	}
250
251	/*
252	* Finally the actual image selecting.
253	*
254	* Return immediately on a perfect match. Otherwise continue looking,
255	* if we're none too picky, remember the first image in case we don't
256	* get lucky.
257	*/
258	if (enmEntryArch == enmCpuArch)
259	{
260	*poffHdr = Arch.offset;
261	return 0;
262	}
263
264	if ( fCpuArchWhatever
265	&& rcRet == KLDR_ERR_CPU_ARCH_MISMATCH)
266	{
267	*poffHdr = Arch.offset;
268	rcRet = 0;
269	}
270	}
271
272	return rcRet;
273	}
274
275
276	/**
277	* Open a executable image from a file provider instance.
278	*
279	* @returns 0 on success and *ppMod pointing to a module instance.
280	* On failure, a non-zero OS specific error code is returned.
281	* @param pRdr The file provider instance to use.
282	* On success, the ownership of the instance is taken by the
283	* module and the caller must not ever touch it again.
284	* (The instance is not closed on failure, the call has to do that.)
285	* @param fFlags Flags, MBZ.
286	* @param enmCpuArch The desired CPU architecture. KCPUARCH_UNKNOWN means
287	* anything goes, but with a preference for the current
288	* host architecture.
289	* @param ppMod Where to store the module handle.
290	*/
291	int kLdrModOpenFromRdr(PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod)
292	{
293	union
294	{
295	KU32 u32;
296	KU16 u16;
297	KU16 au16[2];
298	KU8 au8[4];
299	} u;
300	KLDRFOFF offHdr = 0;
301	int rc;
302
303	for (;;)
304	{
305	/*
306	* Try figure out what kind of image this is.
307	* Always read the 'new header' if we encounter MZ.
308	*/
309	rc = kRdrRead(pRdr, &u, sizeof(u), offHdr);
310	if (rc)
311	return rc;
312	if ( u.u16 == IMAGE_DOS_SIGNATURE
313	&& kRdrSize(pRdr) > (KFOFF)sizeof(IMAGE_DOS_HEADER))
314	{
315	rc = kRdrRead(pRdr, &u, sizeof(u.u32), K_OFFSETOF(IMAGE_DOS_HEADER, e_lfanew));
316	if (rc)
317	return rc;
318	if ((KLDRFOFF)u.u32 < kRdrSize(pRdr))
319	{
320	offHdr = u.u32;
321	rc = kRdrRead(pRdr, &u, sizeof(u.u32), offHdr);
322	if (rc)
323	return rc;
324	}
325	else
326	u.u16 = IMAGE_DOS_SIGNATURE;
327	}
328
329	/*
330	* Handle FAT images too here (one only).
331	*/
332	if ( ( u.u32 == IMAGE_FAT_SIGNATURE
333	\|\| u.u32 == IMAGE_FAT_SIGNATURE_OE)
334	&& offHdr == 0)
335	{
336	rc = kldrModOpenFromRdrSelectImageFromFAT(pRdr, fFlags, enmCpuArch, u.u32, &offHdr);
337	if (rc)
338	return rc;
339	if (offHdr)
340	continue;
341	}
342	break;
343	}
344
345
346	/*
347	* Use the magic to select the appropriate image interpreter head on.
348	*/
349	if (u.u16 == IMAGE_DOS_SIGNATURE)
350	rc = KLDR_ERR_MZ_NOT_SUPPORTED;
351	else if (u.u16 == IMAGE_NE_SIGNATURE)
352	rc = KLDR_ERR_NE_NOT_SUPPORTED;
353	else if (u.u16 == IMAGE_LX_SIGNATURE)
354	rc = g_kLdrModLXOps.pfnCreate(&g_kLdrModLXOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
355	else if (u.u16 == IMAGE_LE_SIGNATURE)
356	rc = KLDR_ERR_LE_NOT_SUPPORTED;
357	else if (u.u32 == IMAGE_NT_SIGNATURE)
358	rc = g_kLdrModPEOps.pfnCreate(&g_kLdrModPEOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
359	else if ( u.u32 == IMAGE_MACHO32_SIGNATURE
360	\|\| u.u32 == IMAGE_MACHO32_SIGNATURE_OE
361	\|\| u.u32 == IMAGE_MACHO64_SIGNATURE
362	\|\| u.u32 == IMAGE_MACHO64_SIGNATURE_OE)
363	rc = g_kLdrModMachOOps.pfnCreate(&g_kLdrModMachOOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
364	else if (u.u32 == IMAGE_ELF_SIGNATURE)
365	rc = KLDR_ERR_ELF_NOT_SUPPORTED;
366	else
367	rc = KLDR_ERR_UNKNOWN_FORMAT;
368
369	/*
370	* If no head on hit, let each interpreter have a go.
371	*/
372	if (rc)
373	{
374	PCKLDRMODOPS pOps;
375	for (pOps = g_pModInterpreterHead; pOps; pOps = pOps->pNext)
376	{
377	int rc2 = pOps->pfnCreate(pOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
378	if (!rc2)
379	return rc;
380	}
381	*ppMod = NULL;
382	}
383	return rc;
384	}
385
386
387	/**
388	* Closes an open module.
389	*
390	* The caller is responsible for calling kLdrModUnmap() and kLdrFreeTLS()
391	* before closing the module.
392	*
393	* @returns 0 on success, non-zero on failure. The module instance state
394	* is unknown on failure, it's best not to touch it.
395	* @param pMod The module.
396	*/
397	int kLdrModClose(PKLDRMOD pMod)
398	{
399	KLDRMOD_VALIDATE(pMod);
400	return pMod->pOps->pfnDestroy(pMod);
401	}
402
403
404	/**
405	* Queries a symbol by name or ordinal number.
406	*
407	* @returns 0 and puValue and pfKind on success.
408	* KLDR_ERR_SYMBOL_NOT_FOUND is returned if the symbol wasn't found.
409	* Other failures could stem from bad executable format failures,
410	* read failure in case pvBits isn't specified and no mapping should be used.
411	* @param pMod The module.
412	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
413	* This can be used by some module interpreters to reduce memory consumption.
414	* @param BaseAddress The module base address to use when calculating the symbol value.
415	* There are two special values that can be used:
416	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
417	* @param iSymbol The symbol ordinal. (optional)
418	* @param pchSymbol The symbol name. (optional)
419	* Important, this doesn't have to be a null-terminated string.
420	* @param cchSymbol The length of the symbol name.
421	* @param pszVersion The symbol version. NULL if not versioned.
422	* @param pfnGetForwarder The callback to use when resolving a forwarder symbol. This is optional
423	* and if not specified KLDR_ERR_FORWARDER is returned instead.
424	* @param pvUser The user argument for the pfnGetForwarder callback.
425	* @param puValue Where to store the symbol value. (optional)
426	* @param pfKind On input one of the KLDRSYMKIND_REQ_* #defines.
427	* On output the symbol kind. (optional)
428	*/
429	int kLdrModQuerySymbol(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
430	const char pchSymbol, KSIZE cchSymbol, const char pszVersion,
431	PFNKLDRMODGETIMPORT pfnGetForwarder, void pvUser, PKLDRADDR puValue, KU32 pfKind)
432	{
433	KLDRMOD_VALIDATE(pMod);
434	if (!puValue && !pfKind)
435	return KERR_INVALID_PARAMETER;
436	if (puValue)
437	*puValue = 0;
438	if (pfKind)
439	K_VALIDATE_FLAGS(*pfKind, KLDRSYMKIND_REQ_SEGMENTED);
440	return pMod->pOps->pfnQuerySymbol(pMod, pvBits, BaseAddress, iSymbol, pchSymbol, cchSymbol, pszVersion,
441	pfnGetForwarder, pvUser, puValue, pfKind);
442	}
443
444
445	/**
446	* Enumerate the symbols in the module.
447	*
448	* @returns 0 on success and non-zero a status code on failure.
449	* @param pMod The module which symbols should be enumerated.
450	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
451	* This can be used by some module interpreters to reduce memory consumption.
452	* @param BaseAddress The module base address to use when calculating the symbol values.
453	* There are two special values that could be can:
454	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
455	* @param fFlags The enumeration flags. A combination of the KLDRMOD_ENUM_SYMS_FLAGS_* \#defines.
456	* @param pfnCallback The enumeration callback function.
457	* @param pvUser The user argument to the callback function.
458	*/
459	int kLdrModEnumSymbols(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 fFlags,
460	PFNKLDRMODENUMSYMS pfnCallback, void *pvUser)
461	{
462	KLDRMOD_VALIDATE(pMod);
463	K_VALIDATE_FLAGS(fFlags, KLDRMOD_ENUM_SYMS_FLAGS_ALL);
464	return pMod->pOps->pfnEnumSymbols(pMod, pvBits, BaseAddress, fFlags, pfnCallback, pvUser);
465	}
466
467
468	/**
469	* Get the name of an import module by ordinal number.
470	*
471	* @returns 0 and name in pszName on success.
472	* On buffer overruns KERR_BUFFER_OVERFLOW will be returned.
473	* On other failures and appropriate error code is returned.
474	* @param pMod The module.
475	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
476	* This can be used by some module interpreters to reduce memory consumption.
477	* @param iImport The import module ordinal number.
478	* @param pszName Where to store the name.
479	* @param cchName The size of the name buffer.
480	*/
481	int kLdrModGetImport(PKLDRMOD pMod, const void pvBits, KU32 iImport, char pszName, KSIZE cchName)
482	{
483	KLDRMOD_VALIDATE(pMod);
484	return pMod->pOps->pfnGetImport(pMod, pvBits, iImport, pszName, cchName);
485	}
486
487
488	/**
489	* Get the number of import modules.
490	*
491	* @returns The number of import modules. -1 if something really bad happens.
492	* @param pMod The module.
493	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
494	* This can be used by some module interpreters to reduce memory consumption.
495	*/
496	KI32 kLdrModNumberOfImports(PKLDRMOD pMod, const void *pvBits)
497	{
498	KLDRMOD_VALIDATE(pMod);
499	return pMod->pOps->pfnNumberOfImports(pMod, pvBits);
500	}
501
502
503	/**
504	* Checks if this module can be executed by the specified arch+cpu.
505	*
506	* @returns 0 if it can, KCPU_ERR_ARCH_CPU_NOT_COMPATIBLE if it can't.
507	* Other failures may occur and cause other return values.
508	* @param pMod The module.
509	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
510	* This can be used by some module interpreters to reduce memory consumption.
511	*/
512	int kLdrModCanExecuteOn(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu)
513	{
514	KLDRMOD_VALIDATE(pMod);
515	if (pMod->pOps->pfnCanExecuteOn)
516	return pMod->pOps->pfnCanExecuteOn(pMod, pvBits, enmArch, enmCpu);
517	return kCpuCompare(pMod->enmArch, pMod->enmCpu, enmArch, enmCpu);
518	}
519
520
521	/**
522	* Gets the image stack info.
523	*
524	* @returns 0 on success, non-zero on failure.
525	* @param pMod
526	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
527	* This can be used by some module interpreters to reduce memory consumption.
528	* @param BaseAddress The module base address to use when calculating the stack address.
529	* There are two special values that can be used:
530	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
531	* @param pStackInfo The stack information.
532	*/
533	int kLdrModGetStackInfo(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo)
534	{
535	KLDRMOD_VALIDATE(pMod);
536	return pMod->pOps->pfnGetStackInfo(pMod, pvBits, BaseAddress, pStackInfo);
537	}
538
539
540	/**
541	* Queries the main entrypoint of the module.
542	*
543	* Only executable are supposed to have an main entrypoint, though some object and DLL
544	* formats will also allow this.
545	*
546	* @returns 0 and *pMainEPAddress on success. Non-zero status code on failure.
547	* @param pMod The module.
548	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
549	* This can be used by some module interpreters to reduce memory consumption.
550	* @param BaseAddress The module base address to use when calculating the entrypoint address.
551	* There are two special values that can be used:
552	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
553	* @param pMainEPAddress Where to store the entry point address.
554	*/
555	int kLdrModQueryMainEntrypoint(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress)
556	{
557	KLDRMOD_VALIDATE(pMod);
558	*pMainEPAddress = 0;
559	return pMod->pOps->pfnQueryMainEntrypoint(pMod, pvBits, BaseAddress, pMainEPAddress);
560	}
561
562
563	/**
564	* Queries info about a resource.
565	*
566	* If there are multiple resources matching the criteria, the best or
567	* first match will be return.
568	*
569	*
570	* @returns 0 on success.
571	* @returns Whatever non-zero status returned by pfnCallback (enumeration was stopped).
572	* @returns non-zero kLdr or native status code on failure.
573	*
574	* @param pMod The module.
575	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
576	* This can be used by some module interpreters to reduce memory consumption.
577	* @param BaseAddress The module base address to use when calculating the resource addresses.
578	* There are two special values that can be used:
579	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
580	* @param idType The resource type id to match if not NIL_KLDRMOD_RSRC_TYPE_ID.
581	* @param pszType The resource type name to match if no NULL.
582	* @param idName The resource name id to match if not NIL_KLDRMOD_RSRC_NAME_ID.
583	* @param pszName The resource name to match if not NULL.
584	* @param idLang The language id to match.
585	* @param pfnCallback The callback function.
586	* @param pvUser The user argument for the callback.
587	*/
588	int kLdrModQueryResource(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
589	KU32 idName, const char pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE pcbRsrc)
590	{
591	KLDRMOD_VALIDATE(pMod);
592	if (!pAddrRsrc && !pcbRsrc)
593	return KERR_INVALID_PARAMETER;
594	if (pAddrRsrc)
595	*pAddrRsrc = NIL_KLDRADDR;
596	if (pcbRsrc)
597	*pcbRsrc = 0;
598	return pMod->pOps->pfnQueryResource(pMod, pvBits, BaseAddress, idType, pszType, idName, pszName, idLang, pAddrRsrc, pcbRsrc);
599	}
600
601
602	/**
603	* Enumerates the resources matching the specfied criteria.
604	*
605	*
606	* @returns 0 on success.
607	* @returns Whatever non-zero status returned by pfnCallback (enumeration was stopped).
608	* @returns non-zero kLdr or native status code on failure.
609	*
610	* @param pMod The module.
611	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
612	* This can be used by some module interpreters to reduce memory consumption.
613	* @param BaseAddress The module base address to use when calculating the resource addresses.
614	* There are two special values that can be used:
615	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
616	* @param idType The resource type id to match if not NIL_KLDRMOD_RSRC_TYPE_ID.
617	* @param pszType The resource type name to match if no NULL.
618	* @param idName The resource name id to match if not NIL_KLDRMOD_RSRC_NAME_ID.
619	* @param pszName The resource name to match if not NULL.
620	* @param idLang The language id to match.
621	* @param pfnCallback The callback function.
622	* @param pvUser The user argument for the callback.
623	*/
624	int kLdrModEnumResources(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
625	KU32 idName, const char pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void pvUser)
626	{
627	KLDRMOD_VALIDATE(pMod);
628	return pMod->pOps->pfnEnumResources(pMod, pvBits, BaseAddress, idType, pszType, idName, pszName, idLang, pfnCallback, pvUser);
629	}
630
631
632	/**
633	* Enumerate the debug info formats contained in the executable image.
634	*
635	* @returns 0 on success, non-zero OS or kLdr status code on failure, or non-zero callback status.
636	* @param pMod The module.
637	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
638	* This can be used by some module interpreters to reduce memory consumption.
639	* @param pfnCallback The callback function.
640	* @param pvUser The user argument.
641	* @see pg_kDbg for the debug info reader.
642	*/
643	int kLdrModEnumDbgInfo(PKLDRMOD pMod, const void pvBits, PFNKLDRENUMDBG pfnCallback, void pvUser)
644	{
645	KLDRMOD_VALIDATE(pMod);
646	return pMod->pOps->pfnEnumDbgInfo(pMod, pvBits, pfnCallback, pvUser);
647	}
648
649
650	/**
651	* Checks if the module has debug info embedded or otherwise associated with it.
652	*
653	* @returns 0 if it has debug info, KLDR_ERR_NO_DEBUG_INFO if no debug info,
654	* and non-zero OS or kLdr status code on failure.
655	* @param pMod The module.
656	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
657	* This can be used by some module interpreters to reduce memory consumption.
658	*/
659	int kLdrModHasDbgInfo(PKLDRMOD pMod, const void *pvBits)
660	{
661	KLDRMOD_VALIDATE(pMod);
662	return pMod->pOps->pfnHasDbgInfo(pMod, pvBits);
663	}
664
665
666	/**
667	* May free up some resources held by the module.
668	*
669	* @todo define exactly what it possible to do after this call.
670	*
671	* @returns 0 on success, KLDR_ERR_* on failure.
672	* @param pMod The module.
673	*/
674	int kLdrModMostlyDone(PKLDRMOD pMod)
675	{
676	KLDRMOD_VALIDATE(pMod);
677	return pMod->pOps->pfnMostlyDone(pMod);
678	}
679
680
681	/**
682	* Maps the module into the memory of the caller.
683	*
684	* On success the actual addresses for the segments can be found in MapAddress
685	* member of each segment in the segment array.
686	*
687	* @returns 0 on success, non-zero OS or kLdr status code on failure.
688	* @param pMod The module to be mapped.
689	* @remark kLdr only supports one mapping at a time of a module.
690	*/
691	int kLdrModMap(PKLDRMOD pMod)
692	{
693	KLDRMOD_VALIDATE(pMod);
694	return pMod->pOps->pfnMap(pMod);
695	}
696
697
698	/**
699	* Unmaps a module previously mapped by kLdrModMap().
700	*
701	* @returns 0 on success, non-zero OS or kLdr status code on failure.
702	* @param pMod The module to unmap.
703	*/
704	int kLdrModUnmap(PKLDRMOD pMod)
705	{
706	KLDRMOD_VALIDATE(pMod);
707	return pMod->pOps->pfnUnmap(pMod);
708	}
709
710
711	/**
712	* Allocates Thread Local Storage for module mapped by kLdrModMap().
713	*
714	* Calling kLdrModAllocTLS() more than once without calling kLdrModFreeTLS()
715	* between each invocation is not supported.
716	*
717	* @returns 0 on success, non-zero OS or kLdr status code on failure.
718	* @param pMod The module.
719	*/
720	int kLdrModAllocTLS(PKLDRMOD pMod)
721	{
722	KLDRMOD_VALIDATE(pMod);
723	return pMod->pOps->pfnAllocTLS(pMod);
724	}
725
726
727	/**
728	* Frees Thread Local Storage previously allocated by kLdrModAllocTLS().
729	*
730	* The caller is responsible for only calling kLdrModFreeTLS() once
731	* after calling kLdrModAllocTLS().
732	*
733	* @returns 0 on success, non-zero OS or kLdr status code on failure.
734	* @param pMod The module.
735	*/
736	void kLdrModFreeTLS(PKLDRMOD pMod)
737	{
738	KLDRMOD_VALIDATE_VOID(pMod);
739	pMod->pOps->pfnFreeTLS(pMod);
740	}
741
742
743	/**
744	* Reloads all dirty pages in a module previously mapped by kLdrModMap().
745	*
746	* The module interpreter may omit code pages if it can safely apply code
747	* fixups again in a subsequent kLdrModFixupMapping() call.
748	*
749	* The caller is responsible for freeing TLS before calling this function.
750	*
751	* @returns 0 on success, non-zero OS or kLdr status code on failure.
752	* @param pMod The module.
753	*/
754	int kLdrModReload(PKLDRMOD pMod)
755	{
756	KLDRMOD_VALIDATE(pMod);
757	return pMod->pOps->pfnReload(pMod);
758	}
759
760
761	/**
762	* Fixup the mapping made by kLdrModMap().
763	*
764	* The caller is only responsible for not calling this function more than
765	* once without doing kLDrModReload() inbetween.
766	*
767	* @returns 0 on success, non-zero OS or kLdr status code on failure.
768	* @param pMod The module.
769	* @param pfnGetImport The callback for resolving external (imported) symbols.
770	* @param pvUser The callback user argument.
771	*/
772	int kLdrModFixupMapping(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser)
773	{
774	KLDRMOD_VALIDATE(pMod);
775	return pMod->pOps->pfnFixupMapping(pMod, pfnGetImport, pvUser);
776	}
777
778
779	/**
780	* Call the module initializiation function of a mapped module (if any).
781	*
782	* @returns 0 on success or no init function, non-zero on init function failure or invalid pMod.
783	* @param pMod The module.
784	* @param uHandle The module handle to use if any of the init functions requires the module handle.
785	*/
786	int kLdrModCallInit(PKLDRMOD pMod, KUPTR uHandle)
787	{
788	KLDRMOD_VALIDATE(pMod);
789	return pMod->pOps->pfnCallInit(pMod, uHandle);
790	}
791
792
793	/**
794	* Call the module termination function of a mapped module (if any).
795	*
796	* @returns 0 on success or no term function, non-zero on invalid pMod.
797	* @param pMod The module.
798	* @param uHandle The module handle to use if any of the term functions requires the module handle.
799	*
800	* @remark Termination function failure will be ignored by the module interpreter.
801	*/
802	int kLdrModCallTerm(PKLDRMOD pMod, KUPTR uHandle)
803	{
804	KLDRMOD_VALIDATE(pMod);
805	return pMod->pOps->pfnCallTerm(pMod, uHandle);
806	}
807
808
809	/**
810	* Call the thread attach or detach function of a mapped module (if any).
811	*
812	* Any per-thread TLS initialization/termination will have to be done at this time too.
813	*
814	* @returns 0 on success or no attach/detach function, non-zero on attach failure or invalid pMod.
815	* @param pMod The module.
816	* @param uHandle The module handle to use if any of the thread attach/detach functions
817	* requires the module handle.
818	*
819	* @remark Detach function failure will be ignored by the module interpreter.
820	*/
821	int kLdrModCallThread(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching)
822	{
823	KLDRMOD_VALIDATE(pMod);
824	K_VALIDATE_FLAGS(fAttachingOrDetaching, 1);
825	return pMod->pOps->pfnCallThread(pMod, uHandle, fAttachingOrDetaching);
826	}
827
828
829	/**
830	* Get the size of the mapped module.
831	*
832	* @returns The size of the mapped module (in bytes).
833	* @param pMod The module.
834	*/
835	KLDRADDR kLdrModSize(PKLDRMOD pMod)
836	{
837	KLDRMOD_VALIDATE_EX(pMod, 0);
838	return pMod->pOps->pfnSize(pMod);
839	}
840
841
842	/**
843	* Gets the module bits.
844	*
845	* The module interpreter will fill a mapping allocated by the caller with the
846	* module bits reallocated to the specified address.
847	*
848	* @returns 0 on succes, non-zero OS or kLdr status code on failure.
849	* @param pMod The module.
850	* @param pvBits Where to put the bits.
851	* @param BaseAddress The base address that should correspond to the first byte in pvBits
852	* upon return.
853	* @param pfnGetImport The callback ufor resolving external (imported) symbols.
854	* @param pvUser The callback user argument.
855	*/
856	int kLdrModGetBits(PKLDRMOD pMod, void pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void pvUser)
857	{
858	KLDRMOD_VALIDATE(pMod);
859	return pMod->pOps->pfnGetBits(pMod, pvBits, BaseAddress, pfnGetImport, pvUser);
860	}
861
862
863	/**
864	* Relocates the module bits previously obtained by kLdrModGetBits().
865	*
866	* @returns 0 on succes, non-zero OS or kLdr status code on failure.
867	* @param pMod The module.
868	* @param pvBits Where to put the bits.
869	* @param NewBaseAddress The new base address.
870	* @param OldBaseAddress The old base address (i.e. the one specified to kLdrModGetBits() or as
871	* NewBaseAddressto the previous kLdrModRelocateBits() call).
872	* @param pfnGetImport The callback ufor resolving external (imported) symbols.
873	* @param pvUser The callback user argument.
874	*/
875	int kLdrModRelocateBits(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
876	PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser)
877	{
878	KLDRMOD_VALIDATE(pMod);
879	return pMod->pOps->pfnRelocateBits(pMod, pvBits, NewBaseAddress, OldBaseAddress, pfnGetImport, pvUser);
880	}
881

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

source: kStuff/trunk/kLdr/kLdrMod.c@ 49

Download in other formats: