kLdrMod.c@ 89

Last change on this file since 89 was 81, checked in by bird, 8 years ago
kLdr: some refactoring and fixes.
Property svn:keywords set to `Id Revision`
File size: 34.9 KB

Line
1	/* $Id: kLdrMod.c 81 2016-08-18 22:10:38Z 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	K_NOREF(fFlags);
156
157	/* Read fat_header_t::nfat_arch. */
158	rc = kRdrRead(pRdr, &cArchs, sizeof(cArchs), off);
159	if (rc)
160	return rc;
161	off += sizeof(KU32);
162	if (u32Magic == IMAGE_FAT_SIGNATURE_OE)
163	cArchs = K_E2E_U32(cArchs);
164	if (cArchs == 0)
165	return KLDR_ERR_FAT_INVALID;
166
167	/* Deal with KCPUARCH_UNKNOWN. */
168	fCpuArchWhatever = enmCpuArch == KCPUARCH_UNKNOWN;
169	if (fCpuArchWhatever)
170	{
171	KCPU enmCpuIgnored;
172	kCpuGetArchAndCpu(&enmCpuArch, &enmCpuIgnored);
173	}
174
175	/*
176	* Iterate the architecture list.
177	*/
178	offEndFAT = off + cArchs * sizeof(fat_arch_t);
179	for (iArch = 0; iArch < cArchs; iArch++)
180	{
181	KCPUARCH enmEntryArch;
182	fat_arch_t Arch;
183	rc = kRdrRead(pRdr, &Arch, sizeof(Arch), off);
184	if (rc)
185	return rc;
186	off += sizeof(Arch);
187
188	if (u32Magic == IMAGE_FAT_SIGNATURE_OE)
189	{
190	Arch.cputype = K_E2E_U32(Arch.cputype);
191	Arch.cpusubtype = K_E2E_U32(Arch.cpusubtype);
192	Arch.offset = K_E2E_U32(Arch.offset);
193	Arch.size = K_E2E_U32(Arch.size);
194	Arch.align = K_E2E_U32(Arch.align);
195	}
196
197	/* Simple validation. */
198	if ( (KLDRFOFF)Arch.offset < offEndFAT
199	\|\| (KLDRFOFF)Arch.offset >= kRdrSize(pRdr)
200	\|\| Arch.align >= 32
201	\|\| Arch.offset & ((KU32_C(1) << Arch.align) - KU32_C(1)))
202	return KLDR_ERR_FAT_INVALID;
203
204	/* deal with the cputype and cpusubtype. (See similar code in kLdrModMachO.c.) */
205	switch (Arch.cputype)
206	{
207	case CPU_TYPE_X86:
208	enmEntryArch = KCPUARCH_X86_32;
209	switch (Arch.cpusubtype)
210	{
211	case CPU_SUBTYPE_I386_ALL:
212	/case CPU_SUBTYPE_386: ^^ ;/
213	case CPU_SUBTYPE_486:
214	case CPU_SUBTYPE_486SX:
215	/case CPU_SUBTYPE_586: vv /
216	case CPU_SUBTYPE_PENT:
217	case CPU_SUBTYPE_PENTPRO:
218	case CPU_SUBTYPE_PENTII_M3:
219	case CPU_SUBTYPE_PENTII_M5:
220	case CPU_SUBTYPE_CELERON:
221	case CPU_SUBTYPE_CELERON_MOBILE:
222	case CPU_SUBTYPE_PENTIUM_3:
223	case CPU_SUBTYPE_PENTIUM_3_M:
224	case CPU_SUBTYPE_PENTIUM_3_XEON:
225	case CPU_SUBTYPE_PENTIUM_M:
226	case CPU_SUBTYPE_PENTIUM_4:
227	case CPU_SUBTYPE_PENTIUM_4_M:
228	case CPU_SUBTYPE_XEON:
229	case CPU_SUBTYPE_XEON_MP:
230	break;
231	default:
232	return KLDR_ERR_FAT_UNSUPPORTED_CPU_SUBTYPE;
233	}
234	break;
235
236	case CPU_TYPE_X86_64:
237	enmEntryArch = KCPUARCH_AMD64;
238	switch (Arch.cpusubtype & ~CPU_SUBTYPE_MASK)
239	{
240	case CPU_SUBTYPE_X86_64_ALL:
241	break;
242	default:
243	return KLDR_ERR_FAT_UNSUPPORTED_CPU_SUBTYPE;
244	}
245	break;
246
247	default:
248	enmEntryArch = KCPUARCH_UNKNOWN;
249	break;
250	}
251
252	/*
253	* Finally the actual image selecting.
254	*
255	* Return immediately on a perfect match. Otherwise continue looking,
256	* if we're none too picky, remember the first image in case we don't
257	* get lucky.
258	*/
259	if (enmEntryArch == enmCpuArch)
260	{
261	*poffHdr = Arch.offset;
262	return 0;
263	}
264
265	if ( fCpuArchWhatever
266	&& rcRet == KLDR_ERR_CPU_ARCH_MISMATCH)
267	{
268	*poffHdr = Arch.offset;
269	rcRet = 0;
270	}
271	}
272
273	return rcRet;
274	}
275
276
277	/**
278	* Open a executable image from a file provider instance.
279	*
280	* @returns 0 on success and *ppMod pointing to a module instance.
281	* On failure, a non-zero OS specific error code is returned.
282	* @param pRdr The file provider instance to use.
283	* On success, the ownership of the instance is taken by the
284	* module and the caller must not ever touch it again.
285	* (The instance is not closed on failure, the call has to do that.)
286	* @param fFlags Flags, MBZ.
287	* @param enmCpuArch The desired CPU architecture. KCPUARCH_UNKNOWN means
288	* anything goes, but with a preference for the current
289	* host architecture.
290	* @param ppMod Where to store the module handle.
291	*/
292	int kLdrModOpenFromRdr(PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod)
293	{
294	union
295	{
296	KU32 u32;
297	KU16 u16;
298	KU16 au16[2];
299	KU8 au8[4];
300	} u;
301	KLDRFOFF offHdr = 0;
302	int rc;
303
304	kHlpAssertReturn(!(fFlags & ~KLDRMOD_OPEN_FLAGS_VALID_MASK), KERR_INVALID_PARAMETER);
305
306	for (;;)
307	{
308	/*
309	* Try figure out what kind of image this is.
310	* Always read the 'new header' if we encounter MZ.
311	*/
312	rc = kRdrRead(pRdr, &u, sizeof(u), offHdr);
313	if (rc)
314	return rc;
315	if ( u.u16 == IMAGE_DOS_SIGNATURE
316	&& kRdrSize(pRdr) > (KFOFF)sizeof(IMAGE_DOS_HEADER))
317	{
318	rc = kRdrRead(pRdr, &u, sizeof(u.u32), K_OFFSETOF(IMAGE_DOS_HEADER, e_lfanew));
319	if (rc)
320	return rc;
321	if ((KLDRFOFF)u.u32 < kRdrSize(pRdr))
322	{
323	offHdr = u.u32;
324	rc = kRdrRead(pRdr, &u, sizeof(u.u32), offHdr);
325	if (rc)
326	return rc;
327	}
328	else
329	u.u16 = IMAGE_DOS_SIGNATURE;
330	}
331
332	/*
333	* Handle FAT images too here (one only).
334	*/
335	if ( ( u.u32 == IMAGE_FAT_SIGNATURE
336	\|\| u.u32 == IMAGE_FAT_SIGNATURE_OE)
337	&& offHdr == 0)
338	{
339	rc = kldrModOpenFromRdrSelectImageFromFAT(pRdr, fFlags, enmCpuArch, u.u32, &offHdr);
340	if (rc)
341	return rc;
342	if (offHdr)
343	continue;
344	}
345	break;
346	}
347
348
349	/*
350	* Use the magic to select the appropriate image interpreter head on.
351	*/
352	if (u.u16 == IMAGE_DOS_SIGNATURE)
353	rc = KLDR_ERR_MZ_NOT_SUPPORTED;
354	else if (u.u16 == IMAGE_NE_SIGNATURE)
355	rc = KLDR_ERR_NE_NOT_SUPPORTED;
356	else if (u.u16 == IMAGE_LX_SIGNATURE)
357	rc = g_kLdrModLXOps.pfnCreate(&g_kLdrModLXOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
358	else if (u.u16 == IMAGE_LE_SIGNATURE)
359	rc = KLDR_ERR_LE_NOT_SUPPORTED;
360	else if (u.u32 == IMAGE_NT_SIGNATURE)
361	rc = g_kLdrModPEOps.pfnCreate(&g_kLdrModPEOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
362	else if ( u.u32 == IMAGE_MACHO32_SIGNATURE
363	\|\| u.u32 == IMAGE_MACHO32_SIGNATURE_OE
364	\|\| u.u32 == IMAGE_MACHO64_SIGNATURE
365	\|\| u.u32 == IMAGE_MACHO64_SIGNATURE_OE)
366	rc = g_kLdrModMachOOps.pfnCreate(&g_kLdrModMachOOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
367	else if (u.u32 == IMAGE_ELF_SIGNATURE)
368	rc = KLDR_ERR_ELF_NOT_SUPPORTED;
369	else
370	rc = KLDR_ERR_UNKNOWN_FORMAT;
371
372	/*
373	* If no head on hit, let each interpreter have a go.
374	*/
375	if (rc)
376	{
377	PCKLDRMODOPS pOps;
378	for (pOps = g_pModInterpreterHead; pOps; pOps = pOps->pNext)
379	{
380	int rc2 = pOps->pfnCreate(pOps, pRdr, fFlags, enmCpuArch, offHdr, ppMod);
381	if (!rc2)
382	return rc;
383	}
384	*ppMod = NULL;
385	}
386	return rc;
387	}
388
389
390	/**
391	* Closes an open module.
392	*
393	* The caller is responsible for calling kLdrModUnmap() and kLdrFreeTLS()
394	* before closing the module.
395	*
396	* @returns 0 on success, non-zero on failure. The module instance state
397	* is unknown on failure, it's best not to touch it.
398	* @param pMod The module.
399	*/
400	int kLdrModClose(PKLDRMOD pMod)
401	{
402	KLDRMOD_VALIDATE(pMod);
403	return pMod->pOps->pfnDestroy(pMod);
404	}
405
406
407	/**
408	* Queries a symbol by name or ordinal number.
409	*
410	* @returns 0 and puValue and pfKind on success.
411	* KLDR_ERR_SYMBOL_NOT_FOUND is returned if the symbol wasn't found.
412	* Other failures could stem from bad executable format failures,
413	* read failure in case pvBits isn't specified and no mapping should be used.
414	* @param pMod The module.
415	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
416	* This can be used by some module interpreters to reduce memory consumption.
417	* @param BaseAddress The module base address to use when calculating the symbol value.
418	* There are two special values that can be used:
419	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
420	* @param iSymbol The symbol ordinal. (optional)
421	* @param pchSymbol The symbol name. (optional)
422	* Important, this doesn't have to be a null-terminated string.
423	* @param cchSymbol The length of the symbol name.
424	* @param pszVersion The symbol version. NULL if not versioned.
425	* @param pfnGetForwarder The callback to use when resolving a forwarder symbol. This is optional
426	* and if not specified KLDR_ERR_FORWARDER is returned instead.
427	* @param pvUser The user argument for the pfnGetForwarder callback.
428	* @param puValue Where to store the symbol value. (optional)
429	* @param pfKind On input one of the KLDRSYMKIND_REQ_* #defines.
430	* On output the symbol kind. (optional)
431	*/
432	int kLdrModQuerySymbol(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
433	const char pchSymbol, KSIZE cchSymbol, const char pszVersion,
434	PFNKLDRMODGETIMPORT pfnGetForwarder, void pvUser, PKLDRADDR puValue, KU32 pfKind)
435	{
436	KLDRMOD_VALIDATE(pMod);
437	if (!puValue && !pfKind)
438	return KERR_INVALID_PARAMETER;
439	if (puValue)
440	*puValue = 0;
441	if (pfKind)
442	K_VALIDATE_FLAGS(*pfKind, KLDRSYMKIND_REQ_SEGMENTED);
443	return pMod->pOps->pfnQuerySymbol(pMod, pvBits, BaseAddress, iSymbol, pchSymbol, cchSymbol, pszVersion,
444	pfnGetForwarder, pvUser, puValue, pfKind);
445	}
446
447
448	/**
449	* Enumerate the symbols in the module.
450	*
451	* @returns 0 on success and non-zero a status code on failure.
452	* @param pMod The module which symbols should be enumerated.
453	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
454	* This can be used by some module interpreters to reduce memory consumption.
455	* @param BaseAddress The module base address to use when calculating the symbol values.
456	* There are two special values that could be can:
457	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
458	* @param fFlags The enumeration flags. A combination of the KLDRMOD_ENUM_SYMS_FLAGS_* \#defines.
459	* @param pfnCallback The enumeration callback function.
460	* @param pvUser The user argument to the callback function.
461	*/
462	int kLdrModEnumSymbols(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 fFlags,
463	PFNKLDRMODENUMSYMS pfnCallback, void *pvUser)
464	{
465	KLDRMOD_VALIDATE(pMod);
466	K_VALIDATE_FLAGS(fFlags, KLDRMOD_ENUM_SYMS_FLAGS_ALL);
467	return pMod->pOps->pfnEnumSymbols(pMod, pvBits, BaseAddress, fFlags, pfnCallback, pvUser);
468	}
469
470
471	/**
472	* Get the name of an import module by ordinal number.
473	*
474	* @returns 0 and name in pszName on success.
475	* On buffer overruns KERR_BUFFER_OVERFLOW will be returned.
476	* On other failures and appropriate error code is returned.
477	* @param pMod The module.
478	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
479	* This can be used by some module interpreters to reduce memory consumption.
480	* @param iImport The import module ordinal number.
481	* @param pszName Where to store the name.
482	* @param cchName The size of the name buffer.
483	*/
484	int kLdrModGetImport(PKLDRMOD pMod, const void pvBits, KU32 iImport, char pszName, KSIZE cchName)
485	{
486	KLDRMOD_VALIDATE(pMod);
487	return pMod->pOps->pfnGetImport(pMod, pvBits, iImport, pszName, cchName);
488	}
489
490
491	/**
492	* Get the number of import modules.
493	*
494	* @returns The number of import modules. -1 if something really bad happens.
495	* @param pMod The module.
496	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
497	* This can be used by some module interpreters to reduce memory consumption.
498	*/
499	KI32 kLdrModNumberOfImports(PKLDRMOD pMod, const void *pvBits)
500	{
501	KLDRMOD_VALIDATE(pMod);
502	return pMod->pOps->pfnNumberOfImports(pMod, pvBits);
503	}
504
505
506	/**
507	* Checks if this module can be executed by the specified arch+cpu.
508	*
509	* @returns 0 if it can, KCPU_ERR_ARCH_CPU_NOT_COMPATIBLE if it can't.
510	* Other failures may occur and cause other return values.
511	* @param pMod The module.
512	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
513	* This can be used by some module interpreters to reduce memory consumption.
514	* @param enmArch The CPU architecture.
515	* @param enmCpu The CPU series/model.
516	*/
517	int kLdrModCanExecuteOn(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu)
518	{
519	KLDRMOD_VALIDATE(pMod);
520	if (pMod->pOps->pfnCanExecuteOn)
521	return pMod->pOps->pfnCanExecuteOn(pMod, pvBits, enmArch, enmCpu);
522	return kCpuCompare(pMod->enmArch, pMod->enmCpu, enmArch, enmCpu);
523	}
524
525
526	/**
527	* Gets the image stack info.
528	*
529	* @returns 0 on success, non-zero on failure.
530	* @param pMod
531	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
532	* This can be used by some module interpreters to reduce memory consumption.
533	* @param BaseAddress The module base address to use when calculating the stack address.
534	* There are two special values that can be used:
535	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
536	* @param pStackInfo The stack information.
537	*/
538	int kLdrModGetStackInfo(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo)
539	{
540	KLDRMOD_VALIDATE(pMod);
541	return pMod->pOps->pfnGetStackInfo(pMod, pvBits, BaseAddress, pStackInfo);
542	}
543
544
545	/**
546	* Queries the main entrypoint of the module.
547	*
548	* Only executable are supposed to have an main entrypoint, though some object and DLL
549	* formats will also allow this.
550	*
551	* @returns 0 and *pMainEPAddress on success. Non-zero status code on failure.
552	* @param pMod The module.
553	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
554	* This can be used by some module interpreters to reduce memory consumption.
555	* @param BaseAddress The module base address to use when calculating the entrypoint address.
556	* There are two special values that can be used:
557	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
558	* @param pMainEPAddress Where to store the entry point address.
559	*/
560	int kLdrModQueryMainEntrypoint(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress)
561	{
562	KLDRMOD_VALIDATE(pMod);
563	*pMainEPAddress = 0;
564	return pMod->pOps->pfnQueryMainEntrypoint(pMod, pvBits, BaseAddress, pMainEPAddress);
565	}
566
567
568	/**
569	* Queries the image UUID, if the image has one.
570	*
571	* @returns 0 and *pvUuid. Non-zero status code on failure.
572	* @param pMod The module.
573	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
574	* This can be used by some module interpreters to reduce memory consumption.
575	* @param pvUuid Where to store the UUID.
576	* @param cbUuid Size of the UUID buffer, must be at least 16 bytes.
577	*/
578	int kLdrModQueryImageUuid(PKLDRMOD pMod, const void pvBits, void pvUuid, KSIZE cbUuid)
579	{
580	KLDRMOD_VALIDATE(pMod);
581	if (cbUuid < 16)
582	return KERR_INVALID_SIZE;
583	if (pMod->pOps->pfnQueryImageUuid)
584	return pMod->pOps->pfnQueryImageUuid(pMod, pvBits, pvUuid, cbUuid);
585	return KLDR_ERR_NO_IMAGE_UUID;
586	}
587
588
589	/**
590	* Queries info about a resource.
591	*
592	* If there are multiple resources matching the criteria, the best or
593	* first match will be return.
594	*
595	*
596	* @returns 0 on success.
597	* @returns Whatever non-zero status returned by pfnCallback (enumeration was stopped).
598	* @returns non-zero kLdr or native status code on failure.
599	*
600	* @param pMod The module.
601	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
602	* This can be used by some module interpreters to reduce memory consumption.
603	* @param BaseAddress The module base address to use when calculating the resource addresses.
604	* There are two special values that can be used:
605	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
606	* @param idType The resource type id to match if not NIL_KLDRMOD_RSRC_TYPE_ID.
607	* @param pszType The resource type name to match if no NULL.
608	* @param idName The resource name id to match if not NIL_KLDRMOD_RSRC_NAME_ID.
609	* @param pszName The resource name to match if not NULL.
610	* @param idLang The language id to match.
611	* @param pfnCallback The callback function.
612	* @param pvUser The user argument for the callback.
613	*/
614	int kLdrModQueryResource(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
615	KU32 idName, const char pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE pcbRsrc)
616	{
617	KLDRMOD_VALIDATE(pMod);
618	if (!pAddrRsrc && !pcbRsrc)
619	return KERR_INVALID_PARAMETER;
620	if (pAddrRsrc)
621	*pAddrRsrc = NIL_KLDRADDR;
622	if (pcbRsrc)
623	*pcbRsrc = 0;
624	return pMod->pOps->pfnQueryResource(pMod, pvBits, BaseAddress, idType, pszType, idName, pszName, idLang, pAddrRsrc, pcbRsrc);
625	}
626
627
628	/**
629	* Enumerates the resources matching the specfied criteria.
630	*
631	*
632	* @returns 0 on success.
633	* @returns Whatever non-zero status returned by pfnCallback (enumeration was stopped).
634	* @returns non-zero kLdr or native status code on failure.
635	*
636	* @param pMod The module.
637	* @param pvBits Optional pointer to bits returned by kLdrModGetBits() currently located at BaseAddress.
638	* This can be used by some module interpreters to reduce memory consumption.
639	* @param BaseAddress The module base address to use when calculating the resource addresses.
640	* There are two special values that can be used:
641	* KLDRMOD_BASEADDRESS_LINK and KLDRMOD_BASEADDRESS_MAP.
642	* @param idType The resource type id to match if not NIL_KLDRMOD_RSRC_TYPE_ID.
643	* @param pszType The resource type name to match if no NULL.
644	* @param idName The resource name id to match if not NIL_KLDRMOD_RSRC_NAME_ID.
645	* @param pszName The resource name to match if not NULL.
646	* @param idLang The language id to match.
647	* @param pfnCallback The callback function.
648	* @param pvUser The user argument for the callback.
649	*/
650	int kLdrModEnumResources(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
651	KU32 idName, const char pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void pvUser)
652	{
653	KLDRMOD_VALIDATE(pMod);
654	return pMod->pOps->pfnEnumResources(pMod, pvBits, BaseAddress, idType, pszType, idName, pszName, idLang, pfnCallback, pvUser);
655	}
656
657
658	/**
659	* Enumerate the debug info formats contained in the executable image.
660	*
661	* @returns 0 on success, non-zero OS or kLdr status code on failure, or non-zero callback status.
662	* @param pMod The module.
663	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
664	* This can be used by some module interpreters to reduce memory consumption.
665	* @param pfnCallback The callback function.
666	* @param pvUser The user argument.
667	* @see pg_kDbg for the debug info reader.
668	*/
669	int kLdrModEnumDbgInfo(PKLDRMOD pMod, const void pvBits, PFNKLDRENUMDBG pfnCallback, void pvUser)
670	{
671	KLDRMOD_VALIDATE(pMod);
672	return pMod->pOps->pfnEnumDbgInfo(pMod, pvBits, pfnCallback, pvUser);
673	}
674
675
676	/**
677	* Checks if the module has debug info embedded or otherwise associated with it.
678	*
679	* @returns 0 if it has debug info, KLDR_ERR_NO_DEBUG_INFO if no debug info,
680	* and non-zero OS or kLdr status code on failure.
681	* @param pMod The module.
682	* @param pvBits Optional pointer to bits returned by kLdrModGetBits().
683	* This can be used by some module interpreters to reduce memory consumption.
684	*/
685	int kLdrModHasDbgInfo(PKLDRMOD pMod, const void *pvBits)
686	{
687	KLDRMOD_VALIDATE(pMod);
688	return pMod->pOps->pfnHasDbgInfo(pMod, pvBits);
689	}
690
691
692	/**
693	* May free up some resources held by the module.
694	*
695	* @todo define exactly what it possible to do after this call.
696	*
697	* @returns 0 on success, KLDR_ERR_* on failure.
698	* @param pMod The module.
699	*/
700	int kLdrModMostlyDone(PKLDRMOD pMod)
701	{
702	KLDRMOD_VALIDATE(pMod);
703	return pMod->pOps->pfnMostlyDone(pMod);
704	}
705
706
707	/**
708	* Maps the module into the memory of the caller.
709	*
710	* On success the actual addresses for the segments can be found in MapAddress
711	* member of each segment in the segment array.
712	*
713	* @returns 0 on success, non-zero OS or kLdr status code on failure.
714	* @param pMod The module to be mapped.
715	* @remark kLdr only supports one mapping at a time of a module.
716	*/
717	int kLdrModMap(PKLDRMOD pMod)
718	{
719	KLDRMOD_VALIDATE(pMod);
720	return pMod->pOps->pfnMap(pMod);
721	}
722
723
724	/**
725	* Unmaps a module previously mapped by kLdrModMap().
726	*
727	* @returns 0 on success, non-zero OS or kLdr status code on failure.
728	* @param pMod The module to unmap.
729	*/
730	int kLdrModUnmap(PKLDRMOD pMod)
731	{
732	KLDRMOD_VALIDATE(pMod);
733	return pMod->pOps->pfnUnmap(pMod);
734	}
735
736
737	/**
738	* Reloads all dirty pages in a module previously mapped by kLdrModMap().
739	*
740	* The module interpreter may omit code pages if it can safely apply code
741	* fixups again in a subsequent kLdrModFixupMapping() call.
742	*
743	* The caller is responsible for freeing TLS before calling this function.
744	*
745	* @returns 0 on success, non-zero OS or kLdr status code on failure.
746	* @param pMod The module.
747	*/
748	int kLdrModReload(PKLDRMOD pMod)
749	{
750	KLDRMOD_VALIDATE(pMod);
751	return pMod->pOps->pfnReload(pMod);
752	}
753
754
755	/**
756	* Fixup the mapping made by kLdrModMap().
757	*
758	* The caller is only responsible for not calling this function more than
759	* once without doing kLDrModReload() inbetween.
760	*
761	* @returns 0 on success, non-zero OS or kLdr status code on failure.
762	* @param pMod The module.
763	* @param pfnGetImport The callback for resolving external (imported) symbols.
764	* @param pvUser The callback user argument.
765	*/
766	int kLdrModFixupMapping(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser)
767	{
768	KLDRMOD_VALIDATE(pMod);
769	return pMod->pOps->pfnFixupMapping(pMod, pfnGetImport, pvUser);
770	}
771
772
773	/**
774	* Get the size of the mapped module.
775	*
776	* @returns The size of the mapped module (in bytes).
777	* @param pMod The module.
778	*/
779	KLDRADDR kLdrModSize(PKLDRMOD pMod)
780	{
781	KLDRMOD_VALIDATE_EX(pMod, 0);
782	return pMod->pOps->pfnSize(pMod);
783	}
784
785
786	/**
787	* Gets the module bits.
788	*
789	* The module interpreter will fill a mapping allocated by the caller with the
790	* module bits reallocated to the specified address.
791	*
792	* @returns 0 on succes, non-zero OS or kLdr status code on failure.
793	* @param pMod The module.
794	* @param pvBits Where to put the bits.
795	* @param BaseAddress The base address that should correspond to the first byte in pvBits
796	* upon return.
797	* @param pfnGetImport The callback ufor resolving external (imported) symbols.
798	* @param pvUser The callback user argument.
799	*/
800	int kLdrModGetBits(PKLDRMOD pMod, void pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void pvUser)
801	{
802	KLDRMOD_VALIDATE(pMod);
803	return pMod->pOps->pfnGetBits(pMod, pvBits, BaseAddress, pfnGetImport, pvUser);
804	}
805
806
807	/**
808	* Relocates the module bits previously obtained by kLdrModGetBits().
809	*
810	* @returns 0 on succes, non-zero OS or kLdr status code on failure.
811	* @param pMod The module.
812	* @param pvBits Where to put the bits.
813	* @param NewBaseAddress The new base address.
814	* @param OldBaseAddress The old base address (i.e. the one specified to kLdrModGetBits() or as
815	* NewBaseAddressto the previous kLdrModRelocateBits() call).
816	* @param pfnGetImport The callback ufor resolving external (imported) symbols.
817	* @param pvUser The callback user argument.
818	*/
819	int kLdrModRelocateBits(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
820	PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser)
821	{
822	KLDRMOD_VALIDATE(pMod);
823	return pMod->pOps->pfnRelocateBits(pMod, pvBits, NewBaseAddress, OldBaseAddress, pfnGetImport, pvUser);
824	}
825
826
827	/**
828	* Allocates Thread Local Storage for module mapped by kLdrModMap().
829	*
830	* Calling kLdrModAllocTLS() more than once without calling kLdrModFreeTLS()
831	* between each invocation is not supported.
832	*
833	* @returns 0 on success, non-zero OS or kLdr status code on failure.
834	* @param pMod The module.
835	* @param pvMapping The external mapping address or RTLDRMOD_INT_MAP.
836	*/
837	int kLdrModAllocTLS(PKLDRMOD pMod, void *pvMapping)
838	{
839	KLDRMOD_VALIDATE(pMod);
840	return pMod->pOps->pfnAllocTLS(pMod, pvMapping);
841	}
842
843
844	/**
845	* Frees Thread Local Storage previously allocated by kLdrModAllocTLS().
846	*
847	* The caller is responsible for only calling kLdrModFreeTLS() once
848	* after calling kLdrModAllocTLS().
849	*
850	* @returns 0 on success, non-zero OS or kLdr status code on failure.
851	* @param pMod The module.
852	* @param pvMapping The external mapping address or RTLDRMOD_INT_MAP.
853	*/
854	void kLdrModFreeTLS(PKLDRMOD pMod, void *pvMapping)
855	{
856	KLDRMOD_VALIDATE_VOID(pMod);
857	pMod->pOps->pfnFreeTLS(pMod, pvMapping);
858	}
859
860
861
862
863	/**
864	* Call the module initializiation function of a mapped module (if any).
865	*
866	* @returns 0 on success or no init function, non-zero on init function failure or invalid pMod.
867	* @param pMod The module.
868	* @param pvMapping The external mapping address or RTLDRMOD_INT_MAP.
869	* @param uHandle The module handle to use if any of the init functions requires the module handle.
870	*/
871	int kLdrModCallInit(PKLDRMOD pMod, void *pvMapping, KUPTR uHandle)
872	{
873	KLDRMOD_VALIDATE(pMod);
874	return pMod->pOps->pfnCallInit(pMod, pvMapping, uHandle);
875	}
876
877
878	/**
879	* Call the module termination function of a mapped module (if any).
880	*
881	* @returns 0 on success or no term function, non-zero on invalid pMod.
882	* @param pMod The module.
883	* @param pvMapping The external mapping address or RTLDRMOD_INT_MAP.
884	* @param uHandle The module handle to use if any of the term functions requires the module handle.
885	*
886	* @remark Termination function failure will be ignored by the module interpreter.
887	*/
888	int kLdrModCallTerm(PKLDRMOD pMod, void *pvMapping, KUPTR uHandle)
889	{
890	KLDRMOD_VALIDATE(pMod);
891	return pMod->pOps->pfnCallTerm(pMod, pvMapping, uHandle);
892	}
893
894
895	/**
896	* Call the thread attach or detach function of a mapped module (if any).
897	*
898	* Any per-thread TLS initialization/termination will have to be done at this time too.
899	*
900	* @returns 0 on success or no attach/detach function, non-zero on attach failure or invalid pMod.
901	* @param pMod The module.
902	* @param pvMapping The external mapping address or RTLDRMOD_INT_MAP.
903	* @param uHandle The module handle to use if any of the thread attach/detach functions
904	* requires the module handle.
905	*
906	* @remark Detach function failure will be ignored by the module interpreter.
907	*/
908	int kLdrModCallThread(PKLDRMOD pMod, void *pvMapping, KUPTR uHandle, unsigned fAttachingOrDetaching)
909	{
910	KLDRMOD_VALIDATE(pMod);
911	K_VALIDATE_FLAGS(fAttachingOrDetaching, 1);
912	return pMod->pOps->pfnCallThread(pMod, pvMapping, uHandle, fAttachingOrDetaching);
913	}
914

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

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

Download in other formats: