kLdrMod.c@ 52

Last change on this file since 52 was 52, checked in by bird, 12 years ago
Added KLDRMOD_OPEN_FLAGS_FOR_INFO and fixed more mach-o issues.
Property svn:keywords set to `Id Revision`
File size: 33.4 KB

Line
1	/* $Id: kLdrMod.c 52 2013-07-09 17:03:37Z bird $ */
2	/** @file
3	* kLdr - The Module Interpreter.
4	*/
5
6	/*
7	* Copyright (c) 2006-2007 Knut St. Osmundsen <bird-kStuff-spamix@anduin.net>
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	kHlpAssertReturn(!(fFlags & ~KLDRMOD_OPEN_FLAGS_VALID_MASK), KERR_INVALID_PARAMETER);
304
305	for (;;)
306	{
307	/*
308	* Try figure out what kind of image this is.
309	* Always read the 'new header' if we encounter MZ.
310	*/
311	rc = kRdrRead(pRdr, &u, sizeof(u), offHdr);
312	if (rc)
313	return rc;
314	if ( u.u16 == IMAGE_DOS_SIGNATURE
315	&& kRdrSize(pRdr) > (KFOFF)sizeof(IMAGE_DOS_HEADER))
316	{
317	rc = kRdrRead(pRdr, &u, sizeof(u.u32), K_OFFSETOF(IMAGE_DOS_HEADER, e_lfanew));
318	if (rc)
319	return rc;
320	if ((KLDRFOFF)u.u32 < kRdrSize(pRdr))
321	{
322	offHdr = u.u32;
323	rc = kRdrRead(pRdr, &u, sizeof(u.u32), offHdr);
324	if (rc)
325	return rc;
326	}
327	else
328	u.u16 = IMAGE_DOS_SIGNATURE;
329	}
330
331	/*
332	* Handle FAT images too here (one only).
333	*/
334	if ( ( u.u32 == IMAGE_FAT_SIGNATURE
335	\|\| u.u32 == IMAGE_FAT_SIGNATURE_OE)
336	&& offHdr == 0)
337	{
338	rc = kldrModOpenFromRdrSelectImageFromFAT(pRdr, fFlags, enmCpuArch, u.u32, &offHdr);
339	if (rc)
340	return rc;
341	if (offHdr)
342	continue;
343	}
344	break;
345	}
346
347
348	/*
349	* Use the magic to select the appropriate image interpreter head on.
350	*/
351	if (u.u16 == IMAGE_DOS_SIGNATURE)
352	rc = KLDR_ERR_MZ_NOT_SUPPORTED;
353	else if (u.u16 == IMAGE_NE_SIGNATURE)
354	rc = KLDR_ERR_NE_NOT_SUPPORTED;
355	else if (u.u16 == IMAGE_LX_SIGNATURE)
356	rc = g_kLdrModLXOps.pfnCreate(&g_kLdrModLXOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
357	else if (u.u16 == IMAGE_LE_SIGNATURE)
358	rc = KLDR_ERR_LE_NOT_SUPPORTED;
359	else if (u.u32 == IMAGE_NT_SIGNATURE)
360	rc = g_kLdrModPEOps.pfnCreate(&g_kLdrModPEOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
361	else if ( u.u32 == IMAGE_MACHO32_SIGNATURE
362	\|\| u.u32 == IMAGE_MACHO32_SIGNATURE_OE
363	\|\| u.u32 == IMAGE_MACHO64_SIGNATURE
364	\|\| u.u32 == IMAGE_MACHO64_SIGNATURE_OE)
365	rc = g_kLdrModMachOOps.pfnCreate(&g_kLdrModMachOOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
366	else if (u.u32 == IMAGE_ELF_SIGNATURE)
367	rc = KLDR_ERR_ELF_NOT_SUPPORTED;
368	else
369	rc = KLDR_ERR_UNKNOWN_FORMAT;
370
371	/*
372	* If no head on hit, let each interpreter have a go.
373	*/
374	if (rc)
375	{
376	PCKLDRMODOPS pOps;
377	for (pOps = g_pModInterpreterHead; pOps; pOps = pOps->pNext)
378	{
379	int rc2 = pOps->pfnCreate(pOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
380	if (!rc2)
381	return rc;
382	}
383	*ppMod = NULL;
384	}
385	return rc;
386	}
387
388
389	/**
390	* Closes an open module.
391	*
392	* The caller is responsible for calling kLdrModUnmap() and kLdrFreeTLS()
393	* before closing the module.
394	*
395	* @returns 0 on success, non-zero on failure. The module instance state
396	* is unknown on failure, it's best not to touch it.
397	* @param pMod The module.
398	*/
399	int kLdrModClose(PKLDRMOD pMod)
400	{
401	KLDRMOD_VALIDATE(pMod);
402	return pMod->pOps->pfnDestroy(pMod);
403	}
404
405
406	/**
407	* Queries a symbol by name or ordinal number.
408	*
409	* @returns 0 and puValue and pfKind on success.
410	* KLDR_ERR_SYMBOL_NOT_FOUND is returned if the symbol wasn't found.
411	* Other failures could stem from bad executable format failures,
412	* read failure in case pvBits isn't specified and no mapping should be used.
413	* @param pMod The module.
414	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
415	* This can be used by some module interpreters to reduce memory consumption.
416	* @param BaseAddress The module base address to use when calculating the symbol value.
417	* There are two special values that can be used:
418	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
419	* @param iSymbol The symbol ordinal. (optional)
420	* @param pchSymbol The symbol name. (optional)
421	* Important, this doesn't have to be a null-terminated string.
422	* @param cchSymbol The length of the symbol name.
423	* @param pszVersion The symbol version. NULL if not versioned.
424	* @param pfnGetForwarder The callback to use when resolving a forwarder symbol. This is optional
425	* and if not specified KLDR_ERR_FORWARDER is returned instead.
426	* @param pvUser The user argument for the pfnGetForwarder callback.
427	* @param puValue Where to store the symbol value. (optional)
428	* @param pfKind On input one of the KLDRSYMKIND_REQ_* #defines.
429	* On output the symbol kind. (optional)
430	*/
431	int kLdrModQuerySymbol(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
432	const char pchSymbol, KSIZE cchSymbol, const char pszVersion,
433	PFNKLDRMODGETIMPORT pfnGetForwarder, void pvUser, PKLDRADDR puValue, KU32 pfKind)
434	{
435	KLDRMOD_VALIDATE(pMod);
436	if (!puValue && !pfKind)
437	return KERR_INVALID_PARAMETER;
438	if (puValue)
439	*puValue = 0;
440	if (pfKind)
441	K_VALIDATE_FLAGS(*pfKind, KLDRSYMKIND_REQ_SEGMENTED);
442	return pMod->pOps->pfnQuerySymbol(pMod, pvBits, BaseAddress, iSymbol, pchSymbol, cchSymbol, pszVersion,
443	pfnGetForwarder, pvUser, puValue, pfKind);
444	}
445
446
447	/**
448	* Enumerate the symbols in the module.
449	*
450	* @returns 0 on success and non-zero a status code on failure.
451	* @param pMod The module which symbols should be enumerated.
452	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
453	* This can be used by some module interpreters to reduce memory consumption.
454	* @param BaseAddress The module base address to use when calculating the symbol values.
455	* There are two special values that could be can:
456	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
457	* @param fFlags The enumeration flags. A combination of the KLDRMOD_ENUM_SYMS_FLAGS_* \#defines.
458	* @param pfnCallback The enumeration callback function.
459	* @param pvUser The user argument to the callback function.
460	*/
461	int kLdrModEnumSymbols(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 fFlags,
462	PFNKLDRMODENUMSYMS pfnCallback, void *pvUser)
463	{
464	KLDRMOD_VALIDATE(pMod);
465	K_VALIDATE_FLAGS(fFlags, KLDRMOD_ENUM_SYMS_FLAGS_ALL);
466	return pMod->pOps->pfnEnumSymbols(pMod, pvBits, BaseAddress, fFlags, pfnCallback, pvUser);
467	}
468
469
470	/**
471	* Get the name of an import module by ordinal number.
472	*
473	* @returns 0 and name in pszName on success.
474	* On buffer overruns KERR_BUFFER_OVERFLOW will be returned.
475	* On other failures and appropriate error code is returned.
476	* @param pMod The module.
477	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
478	* This can be used by some module interpreters to reduce memory consumption.
479	* @param iImport The import module ordinal number.
480	* @param pszName Where to store the name.
481	* @param cchName The size of the name buffer.
482	*/
483	int kLdrModGetImport(PKLDRMOD pMod, const void pvBits, KU32 iImport, char pszName, KSIZE cchName)
484	{
485	KLDRMOD_VALIDATE(pMod);
486	return pMod->pOps->pfnGetImport(pMod, pvBits, iImport, pszName, cchName);
487	}
488
489
490	/**
491	* Get the number of import modules.
492	*
493	* @returns The number of import modules. -1 if something really bad happens.
494	* @param pMod The module.
495	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
496	* This can be used by some module interpreters to reduce memory consumption.
497	*/
498	KI32 kLdrModNumberOfImports(PKLDRMOD pMod, const void *pvBits)
499	{
500	KLDRMOD_VALIDATE(pMod);
501	return pMod->pOps->pfnNumberOfImports(pMod, pvBits);
502	}
503
504
505	/**
506	* Checks if this module can be executed by the specified arch+cpu.
507	*
508	* @returns 0 if it can, KCPU_ERR_ARCH_CPU_NOT_COMPATIBLE if it can't.
509	* Other failures may occur and cause other return values.
510	* @param pMod The module.
511	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
512	* This can be used by some module interpreters to reduce memory consumption.
513	*/
514	int kLdrModCanExecuteOn(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu)
515	{
516	KLDRMOD_VALIDATE(pMod);
517	if (pMod->pOps->pfnCanExecuteOn)
518	return pMod->pOps->pfnCanExecuteOn(pMod, pvBits, enmArch, enmCpu);
519	return kCpuCompare(pMod->enmArch, pMod->enmCpu, enmArch, enmCpu);
520	}
521
522
523	/**
524	* Gets the image stack info.
525	*
526	* @returns 0 on success, non-zero on failure.
527	* @param pMod
528	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
529	* This can be used by some module interpreters to reduce memory consumption.
530	* @param BaseAddress The module base address to use when calculating the stack address.
531	* There are two special values that can be used:
532	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
533	* @param pStackInfo The stack information.
534	*/
535	int kLdrModGetStackInfo(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo)
536	{
537	KLDRMOD_VALIDATE(pMod);
538	return pMod->pOps->pfnGetStackInfo(pMod, pvBits, BaseAddress, pStackInfo);
539	}
540
541
542	/**
543	* Queries the main entrypoint of the module.
544	*
545	* Only executable are supposed to have an main entrypoint, though some object and DLL
546	* formats will also allow this.
547	*
548	* @returns 0 and *pMainEPAddress on success. Non-zero status code on failure.
549	* @param pMod The module.
550	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
551	* This can be used by some module interpreters to reduce memory consumption.
552	* @param BaseAddress The module base address to use when calculating the entrypoint address.
553	* There are two special values that can be used:
554	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
555	* @param pMainEPAddress Where to store the entry point address.
556	*/
557	int kLdrModQueryMainEntrypoint(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress)
558	{
559	KLDRMOD_VALIDATE(pMod);
560	*pMainEPAddress = 0;
561	return pMod->pOps->pfnQueryMainEntrypoint(pMod, pvBits, BaseAddress, pMainEPAddress);
562	}
563
564
565	/**
566	* Queries info about a resource.
567	*
568	* If there are multiple resources matching the criteria, the best or
569	* first match will be return.
570	*
571	*
572	* @returns 0 on success.
573	* @returns Whatever non-zero status returned by pfnCallback (enumeration was stopped).
574	* @returns non-zero kLdr or native status code on failure.
575	*
576	* @param pMod The module.
577	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
578	* This can be used by some module interpreters to reduce memory consumption.
579	* @param BaseAddress The module base address to use when calculating the resource addresses.
580	* There are two special values that can be used:
581	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
582	* @param idType The resource type id to match if not NIL_KLDRMOD_RSRC_TYPE_ID.
583	* @param pszType The resource type name to match if no NULL.
584	* @param idName The resource name id to match if not NIL_KLDRMOD_RSRC_NAME_ID.
585	* @param pszName The resource name to match if not NULL.
586	* @param idLang The language id to match.
587	* @param pfnCallback The callback function.
588	* @param pvUser The user argument for the callback.
589	*/
590	int kLdrModQueryResource(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
591	KU32 idName, const char pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE pcbRsrc)
592	{
593	KLDRMOD_VALIDATE(pMod);
594	if (!pAddrRsrc && !pcbRsrc)
595	return KERR_INVALID_PARAMETER;
596	if (pAddrRsrc)
597	*pAddrRsrc = NIL_KLDRADDR;
598	if (pcbRsrc)
599	*pcbRsrc = 0;
600	return pMod->pOps->pfnQueryResource(pMod, pvBits, BaseAddress, idType, pszType, idName, pszName, idLang, pAddrRsrc, pcbRsrc);
601	}
602
603
604	/**
605	* Enumerates the resources matching the specfied criteria.
606	*
607	*
608	* @returns 0 on success.
609	* @returns Whatever non-zero status returned by pfnCallback (enumeration was stopped).
610	* @returns non-zero kLdr or native status code on failure.
611	*
612	* @param pMod The module.
613	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
614	* This can be used by some module interpreters to reduce memory consumption.
615	* @param BaseAddress The module base address to use when calculating the resource addresses.
616	* There are two special values that can be used:
617	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
618	* @param idType The resource type id to match if not NIL_KLDRMOD_RSRC_TYPE_ID.
619	* @param pszType The resource type name to match if no NULL.
620	* @param idName The resource name id to match if not NIL_KLDRMOD_RSRC_NAME_ID.
621	* @param pszName The resource name to match if not NULL.
622	* @param idLang The language id to match.
623	* @param pfnCallback The callback function.
624	* @param pvUser The user argument for the callback.
625	*/
626	int kLdrModEnumResources(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
627	KU32 idName, const char pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void pvUser)
628	{
629	KLDRMOD_VALIDATE(pMod);
630	return pMod->pOps->pfnEnumResources(pMod, pvBits, BaseAddress, idType, pszType, idName, pszName, idLang, pfnCallback, pvUser);
631	}
632
633
634	/**
635	* Enumerate the debug info formats contained in the executable image.
636	*
637	* @returns 0 on success, non-zero OS or kLdr status code on failure, or non-zero callback status.
638	* @param pMod The module.
639	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
640	* This can be used by some module interpreters to reduce memory consumption.
641	* @param pfnCallback The callback function.
642	* @param pvUser The user argument.
643	* @see pg_kDbg for the debug info reader.
644	*/
645	int kLdrModEnumDbgInfo(PKLDRMOD pMod, const void pvBits, PFNKLDRENUMDBG pfnCallback, void pvUser)
646	{
647	KLDRMOD_VALIDATE(pMod);
648	return pMod->pOps->pfnEnumDbgInfo(pMod, pvBits, pfnCallback, pvUser);
649	}
650
651
652	/**
653	* Checks if the module has debug info embedded or otherwise associated with it.
654	*
655	* @returns 0 if it has debug info, KLDR_ERR_NO_DEBUG_INFO if no debug info,
656	* and non-zero OS or kLdr status code on failure.
657	* @param pMod The module.
658	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
659	* This can be used by some module interpreters to reduce memory consumption.
660	*/
661	int kLdrModHasDbgInfo(PKLDRMOD pMod, const void *pvBits)
662	{
663	KLDRMOD_VALIDATE(pMod);
664	return pMod->pOps->pfnHasDbgInfo(pMod, pvBits);
665	}
666
667
668	/**
669	* May free up some resources held by the module.
670	*
671	* @todo define exactly what it possible to do after this call.
672	*
673	* @returns 0 on success, KLDR_ERR_* on failure.
674	* @param pMod The module.
675	*/
676	int kLdrModMostlyDone(PKLDRMOD pMod)
677	{
678	KLDRMOD_VALIDATE(pMod);
679	return pMod->pOps->pfnMostlyDone(pMod);
680	}
681
682
683	/**
684	* Maps the module into the memory of the caller.
685	*
686	* On success the actual addresses for the segments can be found in MapAddress
687	* member of each segment in the segment array.
688	*
689	* @returns 0 on success, non-zero OS or kLdr status code on failure.
690	* @param pMod The module to be mapped.
691	* @remark kLdr only supports one mapping at a time of a module.
692	*/
693	int kLdrModMap(PKLDRMOD pMod)
694	{
695	KLDRMOD_VALIDATE(pMod);
696	return pMod->pOps->pfnMap(pMod);
697	}
698
699
700	/**
701	* Unmaps a module previously mapped by kLdrModMap().
702	*
703	* @returns 0 on success, non-zero OS or kLdr status code on failure.
704	* @param pMod The module to unmap.
705	*/
706	int kLdrModUnmap(PKLDRMOD pMod)
707	{
708	KLDRMOD_VALIDATE(pMod);
709	return pMod->pOps->pfnUnmap(pMod);
710	}
711
712
713	/**
714	* Allocates Thread Local Storage for module mapped by kLdrModMap().
715	*
716	* Calling kLdrModAllocTLS() more than once without calling kLdrModFreeTLS()
717	* between each invocation is not supported.
718	*
719	* @returns 0 on success, non-zero OS or kLdr status code on failure.
720	* @param pMod The module.
721	*/
722	int kLdrModAllocTLS(PKLDRMOD pMod)
723	{
724	KLDRMOD_VALIDATE(pMod);
725	return pMod->pOps->pfnAllocTLS(pMod);
726	}
727
728
729	/**
730	* Frees Thread Local Storage previously allocated by kLdrModAllocTLS().
731	*
732	* The caller is responsible for only calling kLdrModFreeTLS() once
733	* after calling kLdrModAllocTLS().
734	*
735	* @returns 0 on success, non-zero OS or kLdr status code on failure.
736	* @param pMod The module.
737	*/
738	void kLdrModFreeTLS(PKLDRMOD pMod)
739	{
740	KLDRMOD_VALIDATE_VOID(pMod);
741	pMod->pOps->pfnFreeTLS(pMod);
742	}
743
744
745	/**
746	* Reloads all dirty pages in a module previously mapped by kLdrModMap().
747	*
748	* The module interpreter may omit code pages if it can safely apply code
749	* fixups again in a subsequent kLdrModFixupMapping() call.
750	*
751	* The caller is responsible for freeing TLS before calling this function.
752	*
753	* @returns 0 on success, non-zero OS or kLdr status code on failure.
754	* @param pMod The module.
755	*/
756	int kLdrModReload(PKLDRMOD pMod)
757	{
758	KLDRMOD_VALIDATE(pMod);
759	return pMod->pOps->pfnReload(pMod);
760	}
761
762
763	/**
764	* Fixup the mapping made by kLdrModMap().
765	*
766	* The caller is only responsible for not calling this function more than
767	* once without doing kLDrModReload() inbetween.
768	*
769	* @returns 0 on success, non-zero OS or kLdr status code on failure.
770	* @param pMod The module.
771	* @param pfnGetImport The callback for resolving external (imported) symbols.
772	* @param pvUser The callback user argument.
773	*/
774	int kLdrModFixupMapping(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser)
775	{
776	KLDRMOD_VALIDATE(pMod);
777	return pMod->pOps->pfnFixupMapping(pMod, pfnGetImport, pvUser);
778	}
779
780
781	/**
782	* Call the module initializiation function of a mapped module (if any).
783	*
784	* @returns 0 on success or no init function, non-zero on init function failure or invalid pMod.
785	* @param pMod The module.
786	* @param uHandle The module handle to use if any of the init functions requires the module handle.
787	*/
788	int kLdrModCallInit(PKLDRMOD pMod, KUPTR uHandle)
789	{
790	KLDRMOD_VALIDATE(pMod);
791	return pMod->pOps->pfnCallInit(pMod, uHandle);
792	}
793
794
795	/**
796	* Call the module termination function of a mapped module (if any).
797	*
798	* @returns 0 on success or no term function, non-zero on invalid pMod.
799	* @param pMod The module.
800	* @param uHandle The module handle to use if any of the term functions requires the module handle.
801	*
802	* @remark Termination function failure will be ignored by the module interpreter.
803	*/
804	int kLdrModCallTerm(PKLDRMOD pMod, KUPTR uHandle)
805	{
806	KLDRMOD_VALIDATE(pMod);
807	return pMod->pOps->pfnCallTerm(pMod, uHandle);
808	}
809
810
811	/**
812	* Call the thread attach or detach function of a mapped module (if any).
813	*
814	* Any per-thread TLS initialization/termination will have to be done at this time too.
815	*
816	* @returns 0 on success or no attach/detach function, non-zero on attach failure or invalid pMod.
817	* @param pMod The module.
818	* @param uHandle The module handle to use if any of the thread attach/detach functions
819	* requires the module handle.
820	*
821	* @remark Detach function failure will be ignored by the module interpreter.
822	*/
823	int kLdrModCallThread(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching)
824	{
825	KLDRMOD_VALIDATE(pMod);
826	K_VALIDATE_FLAGS(fAttachingOrDetaching, 1);
827	return pMod->pOps->pfnCallThread(pMod, uHandle, fAttachingOrDetaching);
828	}
829
830
831	/**
832	* Get the size of the mapped module.
833	*
834	* @returns The size of the mapped module (in bytes).
835	* @param pMod The module.
836	*/
837	KLDRADDR kLdrModSize(PKLDRMOD pMod)
838	{
839	KLDRMOD_VALIDATE_EX(pMod, 0);
840	return pMod->pOps->pfnSize(pMod);
841	}
842
843
844	/**
845	* Gets the module bits.
846	*
847	* The module interpreter will fill a mapping allocated by the caller with the
848	* module bits reallocated to the specified address.
849	*
850	* @returns 0 on succes, non-zero OS or kLdr status code on failure.
851	* @param pMod The module.
852	* @param pvBits Where to put the bits.
853	* @param BaseAddress The base address that should correspond to the first byte in pvBits
854	* upon return.
855	* @param pfnGetImport The callback ufor resolving external (imported) symbols.
856	* @param pvUser The callback user argument.
857	*/
858	int kLdrModGetBits(PKLDRMOD pMod, void pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void pvUser)
859	{
860	KLDRMOD_VALIDATE(pMod);
861	return pMod->pOps->pfnGetBits(pMod, pvBits, BaseAddress, pfnGetImport, pvUser);
862	}
863
864
865	/**
866	* Relocates the module bits previously obtained by kLdrModGetBits().
867	*
868	* @returns 0 on succes, non-zero OS or kLdr status code on failure.
869	* @param pMod The module.
870	* @param pvBits Where to put the bits.
871	* @param NewBaseAddress The new base address.
872	* @param OldBaseAddress The old base address (i.e. the one specified to kLdrModGetBits() or as
873	* NewBaseAddressto the previous kLdrModRelocateBits() call).
874	* @param pfnGetImport The callback ufor resolving external (imported) symbols.
875	* @param pvUser The callback user argument.
876	*/
877	int kLdrModRelocateBits(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
878	PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser)
879	{
880	KLDRMOD_VALIDATE(pMod);
881	return pMod->pOps->pfnRelocateBits(pMod, pvBits, NewBaseAddress, OldBaseAddress, pfnGetImport, pvUser);
882	}
883

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

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

Download in other formats: