kLdrMod.c@ 75

Last change on this file since 75 was 54, checked in by bird, 11 years ago
Added kLdrModQueryImageUuid for Mach-O.
Property svn:keywords set to `Id Revision`
File size: 34.3 KB

Line
1	/* $Id: kLdrMod.c 54 2013-10-09 19:52:48Z 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	* @param enmArch The CPU architecture.
514	* @param enmCpu The CPU series/model.
515	*/
516	int kLdrModCanExecuteOn(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu)
517	{
518	KLDRMOD_VALIDATE(pMod);
519	if (pMod->pOps->pfnCanExecuteOn)
520	return pMod->pOps->pfnCanExecuteOn(pMod, pvBits, enmArch, enmCpu);
521	return kCpuCompare(pMod->enmArch, pMod->enmCpu, enmArch, enmCpu);
522	}
523
524
525	/**
526	* Gets the image stack info.
527	*
528	* @returns 0 on success, non-zero on failure.
529	* @param pMod
530	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
531	* This can be used by some module interpreters to reduce memory consumption.
532	* @param BaseAddress The module base address to use when calculating the stack address.
533	* There are two special values that can be used:
534	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
535	* @param pStackInfo The stack information.
536	*/
537	int kLdrModGetStackInfo(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo)
538	{
539	KLDRMOD_VALIDATE(pMod);
540	return pMod->pOps->pfnGetStackInfo(pMod, pvBits, BaseAddress, pStackInfo);
541	}
542
543
544	/**
545	* Queries the main entrypoint of the module.
546	*
547	* Only executable are supposed to have an main entrypoint, though some object and DLL
548	* formats will also allow this.
549	*
550	* @returns 0 and *pMainEPAddress on success. Non-zero status code on failure.
551	* @param pMod The module.
552	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
553	* This can be used by some module interpreters to reduce memory consumption.
554	* @param BaseAddress The module base address to use when calculating the entrypoint address.
555	* There are two special values that can be used:
556	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
557	* @param pMainEPAddress Where to store the entry point address.
558	*/
559	int kLdrModQueryMainEntrypoint(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress)
560	{
561	KLDRMOD_VALIDATE(pMod);
562	*pMainEPAddress = 0;
563	return pMod->pOps->pfnQueryMainEntrypoint(pMod, pvBits, BaseAddress, pMainEPAddress);
564	}
565
566
567	/**
568	* Queries the image UUID, if the image has one.
569	*
570	* @returns 0 and *pvUuid. Non-zero status code on failure.
571	* @param pMod The module.
572	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
573	* This can be used by some module interpreters to reduce memory consumption.
574	* @param pvUuid Where to store the UUID.
575	* @param cbUuid Size of the UUID buffer, must be at least 16 bytes.
576	*/
577	int kLdrModQueryImageUuid(PKLDRMOD pMod, const void pvBits, void pvUuid, KSIZE cbUuid)
578	{
579	KLDRMOD_VALIDATE(pMod);
580	if (cbUuid < 16)
581	return KERR_INVALID_SIZE;
582	if (pMod->pOps->pfnQueryImageUuid)
583	return pMod->pOps->pfnQueryImageUuid(pMod, pvBits, pvUuid, cbUuid);
584	return KLDR_ERR_NO_IMAGE_UUID;
585	}
586
587
588	/**
589	* Queries info about a resource.
590	*
591	* If there are multiple resources matching the criteria, the best or
592	* first match will be return.
593	*
594	*
595	* @returns 0 on success.
596	* @returns Whatever non-zero status returned by pfnCallback (enumeration was stopped).
597	* @returns non-zero kLdr or native status code on failure.
598	*
599	* @param pMod The module.
600	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
601	* This can be used by some module interpreters to reduce memory consumption.
602	* @param BaseAddress The module base address to use when calculating the resource addresses.
603	* There are two special values that can be used:
604	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
605	* @param idType The resource type id to match if not NIL_KLDRMOD_RSRC_TYPE_ID.
606	* @param pszType The resource type name to match if no NULL.
607	* @param idName The resource name id to match if not NIL_KLDRMOD_RSRC_NAME_ID.
608	* @param pszName The resource name to match if not NULL.
609	* @param idLang The language id to match.
610	* @param pfnCallback The callback function.
611	* @param pvUser The user argument for the callback.
612	*/
613	int kLdrModQueryResource(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
614	KU32 idName, const char pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE pcbRsrc)
615	{
616	KLDRMOD_VALIDATE(pMod);
617	if (!pAddrRsrc && !pcbRsrc)
618	return KERR_INVALID_PARAMETER;
619	if (pAddrRsrc)
620	*pAddrRsrc = NIL_KLDRADDR;
621	if (pcbRsrc)
622	*pcbRsrc = 0;
623	return pMod->pOps->pfnQueryResource(pMod, pvBits, BaseAddress, idType, pszType, idName, pszName, idLang, pAddrRsrc, pcbRsrc);
624	}
625
626
627	/**
628	* Enumerates the resources matching the specfied criteria.
629	*
630	*
631	* @returns 0 on success.
632	* @returns Whatever non-zero status returned by pfnCallback (enumeration was stopped).
633	* @returns non-zero kLdr or native status code on failure.
634	*
635	* @param pMod The module.
636	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
637	* This can be used by some module interpreters to reduce memory consumption.
638	* @param BaseAddress The module base address to use when calculating the resource addresses.
639	* There are two special values that can be used:
640	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
641	* @param idType The resource type id to match if not NIL_KLDRMOD_RSRC_TYPE_ID.
642	* @param pszType The resource type name to match if no NULL.
643	* @param idName The resource name id to match if not NIL_KLDRMOD_RSRC_NAME_ID.
644	* @param pszName The resource name to match if not NULL.
645	* @param idLang The language id to match.
646	* @param pfnCallback The callback function.
647	* @param pvUser The user argument for the callback.
648	*/
649	int kLdrModEnumResources(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
650	KU32 idName, const char pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void pvUser)
651	{
652	KLDRMOD_VALIDATE(pMod);
653	return pMod->pOps->pfnEnumResources(pMod, pvBits, BaseAddress, idType, pszType, idName, pszName, idLang, pfnCallback, pvUser);
654	}
655
656
657	/**
658	* Enumerate the debug info formats contained in the executable image.
659	*
660	* @returns 0 on success, non-zero OS or kLdr status code on failure, or non-zero callback status.
661	* @param pMod The module.
662	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
663	* This can be used by some module interpreters to reduce memory consumption.
664	* @param pfnCallback The callback function.
665	* @param pvUser The user argument.
666	* @see pg_kDbg for the debug info reader.
667	*/
668	int kLdrModEnumDbgInfo(PKLDRMOD pMod, const void pvBits, PFNKLDRENUMDBG pfnCallback, void pvUser)
669	{
670	KLDRMOD_VALIDATE(pMod);
671	return pMod->pOps->pfnEnumDbgInfo(pMod, pvBits, pfnCallback, pvUser);
672	}
673
674
675	/**
676	* Checks if the module has debug info embedded or otherwise associated with it.
677	*
678	* @returns 0 if it has debug info, KLDR_ERR_NO_DEBUG_INFO if no debug info,
679	* and non-zero OS or kLdr status code on failure.
680	* @param pMod The module.
681	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
682	* This can be used by some module interpreters to reduce memory consumption.
683	*/
684	int kLdrModHasDbgInfo(PKLDRMOD pMod, const void *pvBits)
685	{
686	KLDRMOD_VALIDATE(pMod);
687	return pMod->pOps->pfnHasDbgInfo(pMod, pvBits);
688	}
689
690
691	/**
692	* May free up some resources held by the module.
693	*
694	* @todo define exactly what it possible to do after this call.
695	*
696	* @returns 0 on success, KLDR_ERR_* on failure.
697	* @param pMod The module.
698	*/
699	int kLdrModMostlyDone(PKLDRMOD pMod)
700	{
701	KLDRMOD_VALIDATE(pMod);
702	return pMod->pOps->pfnMostlyDone(pMod);
703	}
704
705
706	/**
707	* Maps the module into the memory of the caller.
708	*
709	* On success the actual addresses for the segments can be found in MapAddress
710	* member of each segment in the segment array.
711	*
712	* @returns 0 on success, non-zero OS or kLdr status code on failure.
713	* @param pMod The module to be mapped.
714	* @remark kLdr only supports one mapping at a time of a module.
715	*/
716	int kLdrModMap(PKLDRMOD pMod)
717	{
718	KLDRMOD_VALIDATE(pMod);
719	return pMod->pOps->pfnMap(pMod);
720	}
721
722
723	/**
724	* Unmaps a module previously mapped by kLdrModMap().
725	*
726	* @returns 0 on success, non-zero OS or kLdr status code on failure.
727	* @param pMod The module to unmap.
728	*/
729	int kLdrModUnmap(PKLDRMOD pMod)
730	{
731	KLDRMOD_VALIDATE(pMod);
732	return pMod->pOps->pfnUnmap(pMod);
733	}
734
735
736	/**
737	* Allocates Thread Local Storage for module mapped by kLdrModMap().
738	*
739	* Calling kLdrModAllocTLS() more than once without calling kLdrModFreeTLS()
740	* between each invocation is not supported.
741	*
742	* @returns 0 on success, non-zero OS or kLdr status code on failure.
743	* @param pMod The module.
744	*/
745	int kLdrModAllocTLS(PKLDRMOD pMod)
746	{
747	KLDRMOD_VALIDATE(pMod);
748	return pMod->pOps->pfnAllocTLS(pMod);
749	}
750
751
752	/**
753	* Frees Thread Local Storage previously allocated by kLdrModAllocTLS().
754	*
755	* The caller is responsible for only calling kLdrModFreeTLS() once
756	* after calling kLdrModAllocTLS().
757	*
758	* @returns 0 on success, non-zero OS or kLdr status code on failure.
759	* @param pMod The module.
760	*/
761	void kLdrModFreeTLS(PKLDRMOD pMod)
762	{
763	KLDRMOD_VALIDATE_VOID(pMod);
764	pMod->pOps->pfnFreeTLS(pMod);
765	}
766
767
768	/**
769	* Reloads all dirty pages in a module previously mapped by kLdrModMap().
770	*
771	* The module interpreter may omit code pages if it can safely apply code
772	* fixups again in a subsequent kLdrModFixupMapping() call.
773	*
774	* The caller is responsible for freeing TLS before calling this function.
775	*
776	* @returns 0 on success, non-zero OS or kLdr status code on failure.
777	* @param pMod The module.
778	*/
779	int kLdrModReload(PKLDRMOD pMod)
780	{
781	KLDRMOD_VALIDATE(pMod);
782	return pMod->pOps->pfnReload(pMod);
783	}
784
785
786	/**
787	* Fixup the mapping made by kLdrModMap().
788	*
789	* The caller is only responsible for not calling this function more than
790	* once without doing kLDrModReload() inbetween.
791	*
792	* @returns 0 on success, non-zero OS or kLdr status code on failure.
793	* @param pMod The module.
794	* @param pfnGetImport The callback for resolving external (imported) symbols.
795	* @param pvUser The callback user argument.
796	*/
797	int kLdrModFixupMapping(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser)
798	{
799	KLDRMOD_VALIDATE(pMod);
800	return pMod->pOps->pfnFixupMapping(pMod, pfnGetImport, pvUser);
801	}
802
803
804	/**
805	* Call the module initializiation function of a mapped module (if any).
806	*
807	* @returns 0 on success or no init function, non-zero on init function failure or invalid pMod.
808	* @param pMod The module.
809	* @param uHandle The module handle to use if any of the init functions requires the module handle.
810	*/
811	int kLdrModCallInit(PKLDRMOD pMod, KUPTR uHandle)
812	{
813	KLDRMOD_VALIDATE(pMod);
814	return pMod->pOps->pfnCallInit(pMod, uHandle);
815	}
816
817
818	/**
819	* Call the module termination function of a mapped module (if any).
820	*
821	* @returns 0 on success or no term function, non-zero on invalid pMod.
822	* @param pMod The module.
823	* @param uHandle The module handle to use if any of the term functions requires the module handle.
824	*
825	* @remark Termination function failure will be ignored by the module interpreter.
826	*/
827	int kLdrModCallTerm(PKLDRMOD pMod, KUPTR uHandle)
828	{
829	KLDRMOD_VALIDATE(pMod);
830	return pMod->pOps->pfnCallTerm(pMod, uHandle);
831	}
832
833
834	/**
835	* Call the thread attach or detach function of a mapped module (if any).
836	*
837	* Any per-thread TLS initialization/termination will have to be done at this time too.
838	*
839	* @returns 0 on success or no attach/detach function, non-zero on attach failure or invalid pMod.
840	* @param pMod The module.
841	* @param uHandle The module handle to use if any of the thread attach/detach functions
842	* requires the module handle.
843	*
844	* @remark Detach function failure will be ignored by the module interpreter.
845	*/
846	int kLdrModCallThread(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching)
847	{
848	KLDRMOD_VALIDATE(pMod);
849	K_VALIDATE_FLAGS(fAttachingOrDetaching, 1);
850	return pMod->pOps->pfnCallThread(pMod, uHandle, fAttachingOrDetaching);
851	}
852
853
854	/**
855	* Get the size of the mapped module.
856	*
857	* @returns The size of the mapped module (in bytes).
858	* @param pMod The module.
859	*/
860	KLDRADDR kLdrModSize(PKLDRMOD pMod)
861	{
862	KLDRMOD_VALIDATE_EX(pMod, 0);
863	return pMod->pOps->pfnSize(pMod);
864	}
865
866
867	/**
868	* Gets the module bits.
869	*
870	* The module interpreter will fill a mapping allocated by the caller with the
871	* module bits reallocated to the specified address.
872	*
873	* @returns 0 on succes, non-zero OS or kLdr status code on failure.
874	* @param pMod The module.
875	* @param pvBits Where to put the bits.
876	* @param BaseAddress The base address that should correspond to the first byte in pvBits
877	* upon return.
878	* @param pfnGetImport The callback ufor resolving external (imported) symbols.
879	* @param pvUser The callback user argument.
880	*/
881	int kLdrModGetBits(PKLDRMOD pMod, void pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void pvUser)
882	{
883	KLDRMOD_VALIDATE(pMod);
884	return pMod->pOps->pfnGetBits(pMod, pvBits, BaseAddress, pfnGetImport, pvUser);
885	}
886
887
888	/**
889	* Relocates the module bits previously obtained by kLdrModGetBits().
890	*
891	* @returns 0 on succes, non-zero OS or kLdr status code on failure.
892	* @param pMod The module.
893	* @param pvBits Where to put the bits.
894	* @param NewBaseAddress The new base address.
895	* @param OldBaseAddress The old base address (i.e. the one specified to kLdrModGetBits() or as
896	* NewBaseAddressto the previous kLdrModRelocateBits() call).
897	* @param pfnGetImport The callback ufor resolving external (imported) symbols.
898	* @param pvUser The callback user argument.
899	*/
900	int kLdrModRelocateBits(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
901	PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser)
902	{
903	KLDRMOD_VALIDATE(pMod);
904	return pMod->pOps->pfnRelocateBits(pMod, pvBits, NewBaseAddress, OldBaseAddress, pfnGetImport, pvUser);
905	}
906

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

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

Download in other formats: