Context Navigation

source: trunk/kLdr/kLdr.h@ 2850

Visit:

Last change on this file since 2850 was 2850, checked in by bird, 19 years ago
import resolving kldrDyldMod is nearly 100 complete now.
Property svn:keywords set to `Id`
File size: 34.9 KB

Line
1	/* $Id: kLdr.h 2850 2006-11-02 02:28:29Z bird $ */
2	/** @file
3	*
4	* kLdr - The Dynamic Loader.
5	*
6	* Copyright (c) 2006 knut st. osmundsen <bird@anduin.net>
7	*
8	*
9	* This file is part of kLdr.
10	*
11	* kLdr is free software; you can redistribute it and/or modify
12	* it under the terms of the GNU General Public License as published by
13	* the Free Software Foundation; either version 2 of the License, or
14	* (at your option) any later version.
15	*
16	* kLdr is distributed in the hope that it will be useful,
17	* but WITHOUT ANY WARRANTY; without even the implied warranty of
18	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19	* GNU General Public License for more details.
20	*
21	* You should have received a copy of the GNU General Public License
22	* along with kLdr; if not, write to the Free Software
23	* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24	*
25	*/
26
27	#ifndef __kLdr_h__
28	#define __kLdr_h__
29
30	#ifdef __cplusplus
31	extern "C" {
32	#endif
33
34	/* kLdr depend on size_t, [u]intNN_t, [u]intptr_t and some related constants. */
35	#include <sys/types.h>
36	#include <stddef.h>
37	#ifdef _MSC_VER
38	typedef signed char int8_t;
39	typedef unsigned char uint8_t;
40	typedef signed short int16_t;
41	typedef unsigned short uint16_t;
42	typedef signed int int32_t;
43	typedef unsigned int uint32_t;
44	typedef signed __int64 int64_t;
45	typedef unsigned __int64 uint64_t;
46	typedef int64_t intmax_t;
47	typedef uint64_t uintmax_t;
48	#else
49	# include <stdint.h>
50	#endif
51
52
53	/** @defgroup grp_kLdrRdr kLdrRdr - The file provider
54	* @{ */
55
56	/** The kLdr address type. */
57	typedef uint64_t KLDRADDR;
58	/** Pointer to a kLdr address. */
59	typedef KLDRADDR *PKLDRADDR;
60	/** Pointer to a const kLdr address. */
61	typedef const KLDRADDR *PCKLDRADDR;
62
63	/** NIL address. */
64	#define NIL_KLDRADDR (~(uint64_t)0)
65
66	/** The kLdr size type. */
67	typedef uint64_t KLDRSIZE;
68	/** Pointer to a kLdr size. */
69	typedef KLDRSIZE *PKLDRSIZE;
70	/** Pointer to a const kLdr size. */
71	typedef const KLDRSIZE *PCKLDRSIZE;
72
73
74
75	/**
76	* Memory Mapping Protections.
77	*
78	* @remark Shared segments can be mapped using the non copy-on-write variant.
79	* (Normally the copy-on-write variant is used because changes must
80	* be private and not shared with other processes mapping the file.)
81	*/
82	typedef enum KLDRPROT
83	{
84	/** The usual invalid 0. */
85	KLDRPROT_INVALID = 0,
86	/** No access (page not present). */
87	KLDRPROT_NOACCESS,
88	/** Read only. */
89	KLDRPROT_READONLY,
90	/** Read & write. */
91	KLDRPROT_READWRITE,
92	/** Read & copy on write. */
93	KLDRPROT_WRITECOPY,
94	/** Execute only. */
95	KLDRPROT_EXECUTE,
96	/** Execute & read. */
97	KLDRPROT_EXECUTE_READ,
98	/** Execute, read & write. */
99	KLDRPROT_EXECUTE_READWRITE,
100	/** Execute, read & copy on write. */
101	KLDRPROT_EXECUTE_WRITECOPY,
102	/** The usual end value. (exclusive) */
103	KLDRPROT_END,
104	/** Blow the type up to 32-bits. */
105	KLDRPROT_32BIT_HACK = 0x7fffffff
106	} KLDRPROT;
107
108
109	/** Pointer to a file provider instance core. */
110	typedef struct KLDRRDR *PKLDRRDR;
111	/** Pointer to a file provider instance core pointer. */
112	typedef struct KLDRRDR **PPKLDRRDR;
113
114	/**
115	* File provider instance operations.
116	*/
117	typedef struct KLDRRDROPS
118	{
119	/** The name of this file provider. */
120	const char *pszName;
121	/** Pointer to the next file provider. */
122	const struct KLDRRDROPS *pNext;
123
124	/** Try create a new file provider instance.
125	*
126	* @returns 0 on success, OS specific error code on failure.
127	* @param ppRdr Where to store the file provider instance.
128	* @param pszFilename The filename to open.
129	*/
130	int (* pfnCreate)( PPKLDRRDR ppRdr, const char *pszFilename);
131	/** Destroy the file provider instance.
132	*
133	* @returns 0 on success, OS specific error code on failure.
134	* On failure, the file provider instance will be in an indeterminate state - don't touch it!
135	* @param pRdr The file provider instance.
136	*/
137	int (* pfnDestroy)( PKLDRRDR pRdr);
138	/** Read bits from the file.
139	*
140	* @returns 0 on success, OS specific error code on failure.
141	* @param pRdr The file provider instance.
142	* @param pvBuf Where to put the bits.
143	* @param cb The number of bytes to read.
144	* @param off Where to start reading.
145	*/
146	int (* pfnRead)( PKLDRRDR pRdr, void *pvBuf, size_t cb, off_t off);
147	/** Map all the file bits into memory (read only).
148	*
149	* @returns 0 on success, OS specific error code on failure.
150	* @param pRdr The file provider instance.
151	* @param ppvBits Where to store the address of the mapping.
152	* The size can be obtained using pfnSize.
153	*/
154	int (* pfnAllMap)( PKLDRRDR pRdr, const void **ppvBits);
155	/** Unmap a file bits mapping obtained by KLDRRDROPS::pfnAllMap.
156	*
157	* @returns 0 on success, OS specific error code on failure.
158	* @param pRdr The file provider instance.
159	* @param pvBits The mapping address.
160	*/
161	int (* pfnAllUnmap)(PKLDRRDR pRdr, const void *pvBits);
162	/** Get the file size.
163	*
164	* @returns The file size. Returns -1 on failure.
165	* @param pRdr The file provider instance.
166	*/
167	off_t (* pfnSize)( PKLDRRDR pRdr);
168	/** Get the file pointer offset.
169	*
170	* @returns The file pointer offset. Returns -1 on failure.
171	* @param pRdr The file provider instance.
172	*/
173	off_t (* pfnTell)( PKLDRRDR pRdr);
174	/** Get the file name.
175	*
176	* @returns The file size. Returns -1 on failure.
177	* @param pRdr The file provider instance.
178	*/
179	const char * (* pfnName)(PKLDRRDR pRdr);
180	/**
181	* Prepares a memory region to map file sections into.
182	*
183	* @returns 0 on success, OS specific error code on failure.
184	* @param pRdr The file provider instance.
185	* @param ppv If fFixed is set, *ppv contains the memory location which
186	* the region should be based at. If fFixed is clear the OS
187	* is free to choose the location.
188	* On successful return *ppv contains address of the prepared
189	* memory region.
190	* @param cb The size of the memory region to prepare.
191	* @param fFixed When set *ppv will contain the desired region address.
192	*
193	*/
194	int (* pfnPrepare)(PKLDRRDR pRdr, void **ppv, size_t cb, unsigned fFixed);
195	/**
196	* Maps a section of the file into the memory region reserved by pfnPrepare.
197	*
198	* @returns 0 on success, OS specific error code on failure.
199	* @param pRdr The file provider instance.
200	* @param pv The address in the prepared region.
201	* @param cb The size of the memory mapping.
202	* @param enmProt The desired memory protection.
203	* @param offFile The start of the raw file bytes.
204	* @param cbFile The number of raw file bytes. This must be less or equal to cb.
205	*/
206	int (* pfnMap)(PKLDRRDR pRdr, void *pv, size_t cb, KLDRPROT enmProt, off_t offFile, size_t cbFile);
207	/**
208	* Changes the page protection of a section mapped using pfnMap.
209	*
210	* This is typically used for applying fixups and similar.
211	*
212	* @returns 0 on success, OS specific error code on failure.
213	* @param pRdr The file provider instance.
214	* @param pv The address passed to pfnMap.
215	* @param cb The size passed to pfnMap.
216	* @param enmProt The desired memory protection.
217	*/
218	int (* pfnProtect)(PKLDRRDR pRdr, void *pv, size_t cb, KLDRPROT enmProt);
219	/**
220	* Unmaps a section of the file previously mapped using pfnMap.
221	*
222	* @returns 0 on success, OS specific error code on failure.
223	* @param pRdr The file provider instance.
224	* @param pv The address passed to pfnMap.
225	* @param cb The size passed to pfnMap.
226	*/
227	int (* pfnUnmap)(PKLDRRDR pRdr, void *pv, size_t cb);
228	/**
229	* Releases the memory region prepared by pfnPrepare().
230	*
231	* Before calling this function, all sections mapped by pfnMap must first be unmapped by calling pfnUnmap.
232	*
233	* @returns 0 on success, OS specific error code on failure.
234	* @param pRdr The file provider instance.
235	* @param pv The address of the prepared region.
236	* @param cb The size of the prepared region.
237	*/
238	int (* pfnUnprepare)(PKLDRRDR pRdr, void *pv, size_t cb);
239	/**
240	* We're done reading from the file but would like to keep file mappings.
241	*
242	* If the OS support closing the file handle while the file is mapped,
243	* the reader should do so.
244	*
245	* @param pRdr The file provider instance.
246	*/
247	void (* pfnDone)(PKLDRRDR pRdr);
248	/** The usual non-zero dummy that makes sure we've initialized all members. */
249	uint32_t u32Dummy;
250	} KLDRRDROPS;
251	/** Pointer to file provider operations. */
252	typedef KLDRRDROPS *PKLDRRDROPS;
253	/** Pointer to const file provider operations. */
254	typedef const KLDRRDROPS *PCKLDRRDROPS;
255
256
257	/**
258	* File provider instance core.
259	*/
260	typedef struct KLDRRDR
261	{
262	/** Pointer to the file provider operations. */
263	PCKLDRRDROPS pOps;
264	} KLDRRDR;
265
266	void kLdrRdrAddProvider(PKLDRRDROPS pAdd);
267
268	int kLdrRdrOpen( PPKLDRRDR ppRdr, const char *pszFilename);
269	int kLdrRdrClose( PKLDRRDR pRdr);
270	int kLdrRdrRead( PKLDRRDR pRdr, void *pvBuf, size_t cb, off_t off);
271	int kLdrRdrAllMap( PKLDRRDR pRdr, const void **ppvBits);
272	int kLdrRdrAllUnmap(PKLDRRDR pRdr, const void *pvBits);
273	off_t kLdrRdrSize( PKLDRRDR pRdr);
274	off_t kLdrRdrTell( PKLDRRDR pRdr);
275	const char *kLdrRdrName(PKLDRRDR pRdr);
276
277	/** @} */
278
279
280
281	/** @defgroup grp_kLdrMod kLdrMod - The executable image intepreter
282	* @{ */
283
284
285	/**
286	* Debug info type (from the loader point of view).
287	*/
288	typedef enum KLDRDBGINFOTYPE
289	{
290	/** The usual invalid enum value. */
291	KLDRDBGINFOTYPE_INVALID = 0,
292	/** Stabs. */
293	KLDRDBGINFOTYPE_STABS,
294	/** Debug With Arbitrary Record Format (DWARF). */
295	KLDRDBGINFOTYPE_DWARF,
296	/** Microsoft Codeview debug info. */
297	KLDRDBGINFOTYPE_CODEVIEW,
298	/** Watcom debug info. */
299	KLDRDBGINFOTYPE_WATCOM,
300	/** IBM High Level Language debug info.. */
301	KLDRDBGINFOTYPE_HLL,
302	/** The end of the valid debug info values (exclusive). */
303	KLDRDBGINFOTYPE_END,
304	/** Blow the type up to 32-bit. */
305	KLDRDBGINFOTYPE_32BIT_HACK = 0x7fffffff
306	} KLDRDBGINFOTYPE;
307	/** Pointer to a kLdr debug info type. */
308	typedef KLDRDBGINFOTYPE *PKLDRDBGINFOTYPE;
309
310
311	/**
312	* Stack information.
313	*/
314	typedef struct KLDRSTACKINFO
315	{
316	/** The base address of the stack (sub) segment.
317	* Set this to NIL_KLDRADDR if the module doesn't include any stack segment. */
318	KLDRADDR Address;
319	/** The base address of the stack (sub) segment, link address.
320	* Set this to NIL_KLDRADDR if the module doesn't include any stack (sub)segment. */
321	KLDRADDR LinkAddress;
322	/** The stack size of the main thread.
323	* If no stack (sub)segment in the module, this is the stack size of the main thread.
324	* If the module doesn't contain this kind of information this field will be set to 0. */
325	KLDRSIZE cbStack;
326	/** The stack size of non-main threads.
327	* If the module doesn't contain this kind of information this field will be set to 0. */
328	KLDRSIZE cbStackThread;
329	} KLDRSTACKINFO;
330	/** Pointer to stack information. */
331	typedef KLDRSTACKINFO *PKLDRSTACKINFO;
332	/** Pointer to const stack information. */
333	typedef const KLDRSTACKINFO *PCKLDRSTACKINFO;
334
335
336	/**
337	* Loader segment.
338	*/
339	typedef struct KLDRSEG
340	{
341	/** Variable free to use for the kLdr user. */
342	void *pvUser;
343	/** The segment name. */
344	const char *pszName;
345	/** The size of the segment. */
346	KLDRSIZE cb;
347	/** The link time load address. */
348	KLDRADDR LinkAddress;
349	/** The address the segment was mapped at by kLdrModMap().
350	* Set to NIL_KLDRADDR if not mapped. */
351	KLDRADDR MapAddress;
352	/** The segment protection. */
353	KLDRPROT enmProt;
354	} KLDRSEG;
355	/** Pointer to a loader segment. */
356	typedef KLDRSEG *PKLDRSEG;
357	/** Pointer to a loader segment. */
358	typedef const KLDRSEG *PCKLDRSEG;
359
360
361	/**
362	* Loader module format.
363	*/
364	typedef enum KLDRFMT
365	{
366	/** The usual invalid 0 format. */
367	KLDRFMT_INVALID = 0,
368	/** The native OS loader. */
369	KLDRFMT_NATIVE,
370	/** The AOUT loader. */
371	KLDRFMT_AOUT,
372	/** The ELF loader. */
373	KLDRFMT_ELF,
374	/** The LX loader. */
375	KLDRFMT_LX,
376	/** The mach-o loader. */
377	KLDRFMT_MACHO,
378	/** The LX loader. */
379	KLDRFMT_PE,
380	/** The end of the valid format values (exclusive). */
381	KLDRFMT_END,
382	/** Hack to blow the type up to 32-bit. */
383	KLDRFMT_32BIT_HACK = 0x7fffffff
384	} KLDRFMT;
385
386
387	/**
388	* Loader module type.
389	*/
390	typedef enum KLDRTYPE
391	{
392	/** The usual invalid 0 type. */
393	KLDRTYPE_INVALID = 0,
394	/** Object file. */
395	KLDRTYPE_OBJECT,
396	/** Executable module, fixed load address. */
397	KLDRTYPE_EXECUTABLE_FIXED,
398	/** Executable module, relocatable, non-fixed load address. */
399	KLDRTYPE_EXECUTABLE_RELOCATABLE,
400	/** Executable module, position independent code, non-fixed load address. */
401	KLDRTYPE_EXECUTABLE_PIC,
402	/** Shared library, fixed load address.
403	* Typically a system library. */
404	KLDRTYPE_SHARED_LIBRARY_FIXED,
405	/** Shared library, relocatable, non-fixed load address. */
406	KLDRTYPE_SHARED_LIBRARY_RELOCATABLE,
407	/** Shared library, position independent code, non-fixed load address. */
408	KLDRTYPE_SHARED_LIBRARY_PIC,
409	/** DLL that contains no code or data only imports and exports. (Chiefly OS/2.) */
410	KLDRTYPE_FORWARDER_DLL,
411	/** Core or dump. */
412	KLDRTYPE_CORE,
413	/** The end of the valid types values (exclusive). */
414	KLDRTYPE_END,
415	/** Hack to blow the type up to 32-bit. */
416	KLDRTYPE_32BIT_HACK = 0x7fffffff
417	} KLDRTYPE;
418
419
420	/**
421	* CPU Architecture.
422	* @todo Double check the non intel architectures.
423	*/
424	typedef enum KLDRARCH
425	{
426	/** The usual invalid one. */
427	KLDRARCH_INVALID = 0,
428	/** Clone or Intel 16-bit x86. */
429	KLDRARCH_X86_16,
430	/** Clone or Intel 32-bit x86. */
431	KLDRARCH_X86_32,
432	/** AMD64 (including clones). */
433	KLDRARCH_AMD64,
434	/** Itanic (64-bit). */
435	KLDRARCH_IA64,
436	/** ALPHA (64-bit). */
437	KLDRARCH_ALPHA,
438	/** ALPHA limited to 32-bit. */
439	KLDRARCH_ALPHA_32,
440	/** 32-bit ARM. */
441	KLDRARCH_ARM_32,
442	/** 64-bit ARM. */
443	KLDRARCH_ARM_64,
444	/** 32-bit MIPS. */
445	KLDRARCH_MIPS_32,
446	/** 64-bit MIPS. */
447	KLDRARCH_MIPS_64,
448	/** 32-bit PowerPC. */
449	KLDRARCH_POWERPC_32,
450	/** 64-bit PowerPC. */
451	KLDRARCH_POWERPC_64,
452	/** 32-bit SPARC. */
453	KLDRARCH_SPARC_32,
454	/** 64-bit SPARC. */
455	KLDRARCH_SPARC_64,
456	/** The end of the valid architecture values (exclusive). */
457	KLDRARCH_END,
458	/** Hack to blow the type up to 32-bit. */
459	KLDRARCH_32BIT_HACK = 0x7fffffff
460	} KLDRARCH;
461
462
463	/**
464	* CPU models.
465	*/
466	typedef enum KLDRCPU
467	{
468	/** The usual invalid cpu. */
469	KLDRCPU_INVALID = 0,
470	/** @name KLDRARCH_X86_16
471	* @{ */
472	KLDRCPU_I8086,
473	KLDRCPU_I8088,
474	KLDRCPU_I80186,
475	KLDRCPU_I80286,
476	KLDRCPU_I386_16,
477	KLDRCPU_I486_16,
478	KLDRCPU_I486SX_16,
479	KLDRCPU_I586_16,
480	KLDRCPU_I686_16,
481	KLDRCPU_K6_16,
482	KLDRCPU_K7_16,
483	KLDRCPU_K8_16,
484	/** @} */
485
486	/** @name KLDRARCH_X86_32
487	* @{ */
488	KLDRCPU_I386,
489	KLDRCPU_I486,
490	KLDRCPU_I486SX,
491	KLDRCPU_I586,
492	KLDRCPU_I686,
493	KLDRCPU_P4,
494	KLDRCPU_CORE2_32,
495	KLDRCPU_K6,
496	KLDRCPU_K7,
497	KLDRCPU_K8_32,
498	/** @} */
499
500	/** @name KLDRARCH_AMD64
501	* @{ */
502	KLDRCPU_K8,
503	KLDRCPU_P4_64,
504	KLDRCPU_CORE2,
505	/** @} */
506
507	/** The end of the valid cpu values (exclusive). */
508	KLDRCPU_END,
509	/** Hack to blow the type up to 32-bit. */
510	KLDRCPU_32BIT_HACK = 0x7fffffff
511	} KLDRCPU;
512
513
514	/**
515	* Loader endian indicator.
516	*/
517	typedef enum KLDRENDIAN
518	{
519	/** The usual invalid endian. */
520	KLDRENDIAN_INVALID,
521	/** Little endian. */
522	KLDRENDIAN_LITTLE,
523	/** Bit endian. */
524	KLDRENDIAN_BIG,
525	/** Endianness doesn't have a meaning in the context. */
526	KLDRENDIAN_NA,
527	/** The end of the valid endian values (exclusive). */
528	KLDRENDIAN_END,
529	/** Hack to blow the type up to 32-bit. */
530	KLDRENDIAN_32BIT_HACK = 0x7fffffff
531	} KLDRENDIAN;
532
533
534	/**
535	* Loader module.
536	*/
537	typedef struct KLDRMOD
538	{
539	/** Magic number. */
540	uint32_t u32Magic;
541	/** The format of this module. */
542	KLDRFMT enmFmt;
543	/** The type of module. */
544	KLDRTYPE enmType;
545	/** The architecture this module was built for. */
546	KLDRARCH enmArch;
547	/** The minium cpu this module was built for.
548	* This might not be accurate, so use kLdrModCanExecuteOn() to check. */
549	KLDRARCH enmCpu;
550	/** The endian used by the module. */
551	KLDRENDIAN enmEndian;
552	/** The filename length (bytes). */
553	uint32_t cchFilename;
554	/** The filename. */
555	const char *pszFilename;
556	/** The module name. */
557	const char *pszName;
558	/** The module name length (bytes). */
559	uint32_t cchName;
560	/** The number of segments in the module. */
561	uint32_t cSegments;
562	/** The module data. */
563	void *pvData;
564	/** Segments. (variable size, can be zero) */
565	KLDRSEG aSegments[1];
566	} KLDRMOD, PKLDRMOD, *PPKLDRMOD;
567
568
569	/** Special base address value alias for the link address. */
570	#define KLDRMOD_BASEADDRESS_LINK (~(KLDRADDR)1)
571	/** Special base address value alias for the actual load address (must be mapped). */
572	#define KLDRMOD_BASEADDRESS_MAP (~(KLDRADDR)2)
573
574	/** Special import module ordinal value used to indicate that there is no
575	* specific module associated with the requested symbol. */
576	#define NIL_KLDRMOD_IMPORT (~(uint32_t)0)
577
578	/** Special symbol ordinal value used to indicate that the symbol
579	* only has a string name. */
580	#define NIL_KLDRMOD_SYM_ORDINAL (~(uint32_t)0)
581
582
583	/** @name Load symbol kind flags.
584	* @{ */
585	/** The bitness doesn't matter. */
586	#define KLDRSYMKIND_NO_BIT 0x00000000
587	/** 16-bit symbol. */
588	#define KLDRSYMKIND_16BIT 0x00000001
589	/** 32-bit symbol. */
590	#define KLDRSYMKIND_32BIT 0x00000002
591	/** 64-bit symbol. */
592	#define KLDRSYMKIND_64BIT 0x00000003
593	/** Mask out the bit.*/
594	#define KLDRSYMKIND_BIT_MASK 0x00000003
595	/** We don't know the type of symbol. */
596	#define KLDRSYMKIND_NO_TYPE 0x00000000
597	/** The symbol is a code object (method/function/procedure/whateveryouwannacallit). */
598	#define KLDRSYMKIND_CODE 0x00000010
599	/** The symbol is a data object. */
600	#define KLDRSYMKIND_DATA 0x00000020
601	/** Mask out the symbol type. */
602	#define KLDRSYMKIND_TYPE_MASK 0x00000030
603	/** Valid symbol kind mask. */
604	#define KLDRSYMKIND_MASK 0x00000033
605	/** Weak symbol. */
606	#define KLDRSYMKIND_WEAK 0x00000100
607	/** @} */
608
609	/** @name kLdrModEnumSymbols flags.
610	* @{ */
611	/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
612	#define KLDRMOD_ENUM_SYMS_FLAGS_ALL 0x00000001
613	/** @} */
614
615
616	/**
617	* Callback for resolving imported symbols when applying fixups.
618	*
619	* @returns 0 on success and pValue and pfKind filled.
620	* @returns Non-zero OS specific or kLdr status code on failure.
621	*
622	* @param pMod The module which fixups are begin applied.
623	* @param iImport The import module ordinal number or NIL_KLDRMOD_IMPORT.
624	* @param uSymbol The symbol ordinal number or NIL_KLDRMOD_SYM_ORDINAL.
625	* @param pszSymbol The symbol name. Can be NULL if uSymbol isn't nil.
626	* @param puValue Where to store the symbol value.
627	* @param pfKind Where to store the symbol kind flags.
628	* @param pvUser The user parameter specified to the relocation function.
629	*/
630	typedef int FNKLDRMODGETIMPORT(PKLDRMOD pMod, uint32_t iImport, uint32_t uSymbol, const char *pszSymbol,
631	PKLDRADDR puValue, uint32_t pfKind, void pvUser);
632	/** Pointer to a import callback. */
633	typedef FNKLDRMODGETIMPORT *PFNKLDRMODGETIMPORT;
634
635	/**
636	* Symbol enumerator callback.
637	*
638	* @returns 0 if enumeration should continue.
639	* @returns non-zero if the enumeration should stop. This status code will then be returned by kLdrModEnumSymbols().
640	*
641	* @param pMod The module which symbols are being enumerated.s
642	* @param uSymbol The symbol ordinal number or NIL_KLDRMOD_SYM_ORDINAL.
643	* @param pszSymbol The symbol name. This can be NULL if there is a symbol ordinal.
644	* This can also be an empty string if the symbol doesn't have a name
645	* or it's name has been stripped.
646	* @param uValue The symbol value.
647	* @param fKind The symbol kind flags.
648	* @param pvUser The user parameter specified to kLdrModEnumSymbols().
649	*/
650	typedef int FNKLDRMODENUMSYMS(PKLDRMOD pMod, uint32_t uSymbol, const char *pszSymbol,
651	KLDRADDR uValue, uint32_t fKind, void *pvUser);
652	/** Pointer to a symbol enumerator callback. */
653	typedef FNKLDRMODENUMSYMS *PFNKLDRMODENUMSYMS;
654
655	/**
656	* Debug info enumerator callback.
657	*
658	* @returns 0 to continue the enumeration.
659	* @returns non-zero if the enumeration should stop. This status code will then be returned by kLdrModEnumDbgInfo().
660	*
661	* @param pMod The module.
662	* @param enmType The debug info type.
663	* @param iDbgInfo The debug info ordinal number / id.
664	* @param offFile The file offset if this type has one specific location in the executable image file.
665	* This is -1 if there isn't any specific file location.
666	* @param cbFile The file size.
667	* This is 0 if there isn't any specific file location.
668	* @param pszExtFile This points to the name of an external file containing the debug info.
669	* This is NULL if there isn't any external file.
670	* @param pvUser The user parameter specified to kLdrModEnumDbgInfo.
671	*/
672	typedef int FNKLDRENUMDBG(PKLDRMOD pMod, KLDRDBGINFOTYPE enmType, uint32_t iDbgInfo, off_t offFile, off_t cbFile,
673	const char pszExtFile, void pvUser);
674
675	int kLdrModOpen(const char *pszFilename, PPKLDRMOD ppMod);
676	int kLdrModOpenFromRdr(PKLDRRDR pRdr, PPKLDRMOD ppMod);
677	int kLdrModOpenNative(const char *pszFilename, PPKLDRMOD ppMod);
678	int kLdrModClose(PKLDRMOD pMod);
679
680	int kLdrModQuerySymbol(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, uint32_t uSymbol,
681	const char pszSymbol, PKLDRADDR puValue, uint32_t pfKind);
682	int kLdrModEnumSymbols(PKLDRMOD pMod, uint32_t fFlags, const void *pvBits, KLDRADDR BaseAddress,
683	PFNKLDRMODENUMSYMS pfnCallback, void *pvUser);
684	int kLdrModGetImport(PKLDRMOD pMod, void pvBits, uint32_t iImport, const char pszName, size_t cchName);
685	int32_t kLdrModNumberOfImports(PKLDRMOD pMod, void *pvBits);
686	int kLdrModCanExecuteOn(PKLDRMOD pMod, void *pvBits, KLDRARCH enmArch, KLDRCPU enmCpu);
687	int kLdrModGetStackInfo(PKLDRMOD pMod, void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo);
688	int kLdrModQueryMainEntrypoint(PKLDRMOD pMod, void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress);
689	/** Pointer to a debug info enumberator callback. */
690	typedef FNKLDRENUMDBG *PFNKLDRENUMDBG;
691	int kLdrModEnumDbgInfo(PKLDRMOD pMod, void pvBits, PFNKLDRENUMDBG pfnCallback, void pvUser);
692	int kLdrModHasDbgInfo(PKLDRMOD pMod, void *pvBits);
693
694	/** @name Operations On The Internally Managed Mapping
695	* @{ */
696	int kLdrModMap(PKLDRMOD pMod);
697	int kLdrModUnmap(PKLDRMOD pMod);
698	int kLdrModAllocTLS(PKLDRMOD pMod);
699	void kLdrModFreeTLS(PKLDRMOD pMod);
700	int kLdrModReload(PKLDRMOD pMod);
701	int kLdrModFixupMapping(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
702	int kLdrModCallInit(PKLDRMOD pMod);
703	int kLdrModCallTerm(PKLDRMOD pMod);
704	int kLdrModCallThread(PKLDRMOD pMod, unsigned fAttachingOrDetaching);
705	/** @} */
706
707	/** @name Operations On The Externally Managed Mappings
708	* @{ */
709	size_t kLdrModSize(PKLDRMOD pMod);
710	int kLdrModGetBits(PKLDRMOD pMod, void pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void pvUser);
711	int kLdrModRelocateBits(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
712	PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
713	/** @} */
714
715
716	/** @} */
717
718
719
720
721	/** @defgroup grp_kLdrDyld kLdrDyld - The dynamic loader
722	* @{ */
723
724	/** The handle to a dynamic loader module. */
725	typedef struct KLDRDYLDMOD *HKLDRMOD;
726	/** Pointer to the handle to a dynamic loader module. */
727	typedef HKLDRMOD *PHKLDRMOD;
728	/** NIL handle value. */
729	#define NIL_HKLDRMOD ((HKLDRMOD)0)
730
731
732	/**
733	* File search method.
734	*
735	* In addition to it's own way of finding files, kLdr emulates
736	* the methods employed by the most popular systems.
737	*/
738	typedef enum KLDRDYLDSEARCH
739	{
740	/** The usual invalid file search method. */
741	KLDRDYLD_SEARCH_INVALID = 0,
742	/** Uses the kLdr file search method.
743	* @todo invent me. */
744	KLDRDYLD_SEARCH_KLDR,
745	/** Use the emulation closest to the host system. */
746	KLDRDYLD_SEARCH_HOST,
747	/** Emulate the OS/2 file search method.
748	* On non-OS/2 systems, BEGINLIBPATH, LIBPATH, ENDLIBPATH and LIBPATHSTRICT are
749	* taken form the environment. */
750	KLDRDYLD_SEARCH_OS2,
751	/** Emulate the standard window file search method. */
752	KLDRDYLD_SEARCH_WINDOWS,
753	/** Emulate the alternative window file search method. */
754	KLDRDYLD_SEARCH_WINDOWS_ALTERED,
755	/** Emulate the most common UNIX file search method. */
756	KLDRDYLD_SEARCH_UNIX_COMMON,
757	/** End of the valid file search method values. */
758	KLDRDYLD_SEARCH_END,
759	/** Hack to blow the type up to 32-bit. */
760	KLDRDYLD_SEARCH_32BIT_HACK = 0x7fffffff
761	} KLDRDYLDSEARCH;
762
763	/** @name kLdrDyldLoad and kLdrDyldFindByName flags.
764	* @{ */
765	/** The symbols in the module should be loaded into the global unix namespace.
766	* If not specified, the symbols are local and can only be referenced directly. */
767	#define KLDRYDLD_LOAD_FLAGS_GLOBAL_SYMBOLS 0x00000001
768	/** The module shouldn't be found by a global module search.
769	* If not specified, the module can be found by unspecified module searches,
770	* typical used when loading import/dep modules. */
771	#define KLDRYDLD_LOAD_FLAGS_SPECIFIC_MODULE 0x00000002
772	/** Do a recursive initialization calls instead of defering them to the outermost call. */
773	#define KLDRDYLD_LOAD_FLAGS_RECURSIVE_INIT 0x00000004
774	/** We're loading the executable module.
775	* Internal flag which will be rejected by kLdrDyldLoad. */
776	#define KLDRDYLD_LOAD_FLAGS_EXECUTABLE 0x40000000
777	/** @} */
778
779
780	int kLdrDyldLoad(const char pszDll, const char pszPrefix, const char *pszSuffix, KLDRDYLDSEARCH enmSearch,
781	unsigned fFlags, PHKLDRMOD phMod, char *pszErr, size_t cchErr);
782	int kLdrDyldUnload(HKLDRMOD hMod);
783	int kLdrDyldFindByName(const char pszDll, const char pszPrefix, const char *pszSuffix, KLDRDYLDSEARCH enmSearch,
784	unsigned fFlags, PHKLDRMOD phMod);
785	int kLdrDyldFindByAddress(uintptr_t Address, PHKLDRMOD phMod, uint32_t piSegment, uintptr_t poffSegment);
786	int kLdrDyldGetName(HKLDRMOD hMod, char *pszName, size_t cchName);
787	int kLdrDyldGetFilename(HKLDRMOD hMod, char *pszFilename, size_t cchFilename);
788	int kLdrDyldQuerySymbol(HKLDRMOD hMod, uint32_t uSymbolOrdinal, const char pszSymbolName, uintptr_t pValue, uint32_t *pfKind);
789
790	/** @name OS/2 like API
791	* @{ */
792	int kLdrDosLoadModule(char pszObject, size_t cbObject, const char pszModule, PHKLDRMOD phMod);
793	int kLdrDosFreeModule(HKLDRMOD hMod);
794	int kLdrDosQueryModuleHandle(const char *pszModname, PHKLDRMOD phMod);
795	int kLdrDosQueryModuleName(HKLDRMOD hMod, size_t cchName, char *pszName);
796	int kLdrDosQueryProcAddr(HKLDRMOD hMod, uint32_t iOrdinal, const char pszProcName, void *ppvProcAddr);
797	int kLdrDosQueryProcType(HKLDRMOD hMod, uint32_t iOrdinal, const char pszProcName, uint32_t pfProcType);
798	int kLdrDosQueryModFromEIP(PHKLDRMOD phMod, uint32_t piObject, size_t cbName, char pszName, uintptr_t *poffObject, uintptr_t ulEIP);
799	int kLdrDosReplaceModule(const char pszOldModule, const char pszNewModule, const char *pszBackupModule);
800	int kLdrDosGetResource(HKLDRMOD hMod, uint32_t idType, uint32_t idName, void **pvResAddr);
801	int kLdrDosQueryResourceSize(HKLDRMOD hMod, uint32_t idTypeID, uint32_t idName, uint32_t *pcb);
802	int kLdrDosFreeResource(void *pvResAddr);
803	/** @} */
804
805	/** @name POSIX like API
806	* @{ */
807	HKLDRMOD kLdrDlOpen(const char *pszLibrary, int fFlags);
808	const char *kLdrDlError(void);
809	void * kLdrDlSym(HKLDRMOD hMod, const char *pszSymbol);
810	int kLdrDlClose(HKLDRMOD hMod);
811	/** @} */
812
813	/** @name Win32 like API
814	* @{ */
815	HKLDRMOD kLdrWLoadLibrary(const char *pszFilename);
816	HKLDRMOD kLdrWLoadLibraryEx(const char pszFilename, void hFileReserved, uint32_t fFlags);
817	uint32_t kLdrWGetModuleFileName(HKLDRMOD hMod, char *pszModName, size_t cchModName);
818	HKLDRMOD kLdrWGetModuleHandle(const char *pszFilename);
819	int kLdrWGetModuleHandleEx(uint32_t fFlags, const char *pszFilename, HKLDRMOD hMod);
820	void * kLdrWGetProcAddress(HKLDRMOD hMod, const char *pszProcName);
821	uint32_t kLdrWGetDllDirectory(size_t cchDir, char *pszDir);
822	int kLdrWSetDllDirectory(const char *pszDir);
823	int kLdrWFreeLibrary(HKLDRMOD hMod);
824	int kLdrWDisableThreadLibraryCalls(HKLDRMOD hMod);
825
826	/** @} */
827
828
829	/** @name Process Bootstrapping
830	* @{ */
831
832	/**
833	* Argument package from the stub.
834	*/
835	typedef struct KLDREXEARGS
836	{
837	/** Flags. (Currently unused, MBZ.) */
838	uint32_t fFlags;
839	/** The search method to use when loading this executable. */
840	KLDRDYLDSEARCH enmSearch;
841	/** The executable file that the stub is supposed to load. */
842	char szExecutable[260];
843	/** The default prefix used when searching for DLLs. */
844	char szDefPrefix[16];
845	/** The default suffix used when searching for DLLs. */
846	char szDefSuffix[16];
847	/** The LD_LIBRARY_PATH prefix for the process.. */
848	char szLibPath[4096 - sizeof(uint32_t) - sizeof(KLDRDYLDSEARCH) - 16 - 16 - 260];
849	} KLDREXEARGS, *PKLDREXEARGS;
850
851	void kLdrLoadExe(PKLDREXEARGS pArgs, void *pvOS);
852
853	/** @} */
854
855	/** @} */
856
857
858	/** @defgroup grp_kLdrErr kLdr Status Codes
859	* kLdr uses a mix of native status codes and it's own status codes.
860	* A status code of 0 means success, all other status codes means failure.
861	* @{
862	*/
863	#ifdef __OS2__
864	# define KLDR_ERR_BASE 0x7face000
865	#elif defined(__WIN__)
866	# define KLDR_ERR_BASE 0x7face000
867	#else
868	# error "port me"
869	#endif
870	/** The image format is unknown. */
871	#define KLDR_ERR_UNKNOWN_FORMAT (KLDR_ERR_BASE + 0)
872	/** The MZ image format isn't supported by this kLdr build. */
873	#define KLDR_ERR_MZ_NOT_SUPPORTED (KLDR_ERR_BASE + 1)
874	/** The NE image format isn't supported by this kLdr build. */
875	#define KLDR_ERR_NE_NOT_SUPPORTED (KLDR_ERR_BASE + 2)
876	/** The LX image format isn't supported by this kLdr build. */
877	#define KLDR_ERR_LX_NOT_SUPPORTED (KLDR_ERR_BASE + 3)
878	/** The LE image format isn't supported by this kLdr build. */
879	#define KLDR_ERR_LE_NOT_SUPPORTED (KLDR_ERR_BASE + 4)
880	/** The PE image format isn't supported by this kLdr build. */
881	#define KLDR_ERR_PE_NOT_SUPPORTED (KLDR_ERR_BASE + 5)
882	/** The ELF image format isn't supported by this kLdr build. */
883	#define KLDR_ERR_ELF_NOT_SUPPORTED (KLDR_ERR_BASE + 6)
884	/** The mach-o image format isn't supported by this kLdr build. */
885	#define KLDR_ERR_MACHO_NOT_SUPPORTED (KLDR_ERR_BASE + 7)
886	/** The mach-o image format isn't supported by this kLdr build. */
887	#define KLDR_ERR_AOUT_NOT_SUPPORTED (KLDR_ERR_BASE + 8)
888
889	/** Invalid parameter to a kLdr API. */
890	#define KLDR_ERR_INVALID_PARAMETER (KLDR_ERR_BASE + 32)
891	/** Invalid handle parameter to a kLdr API. */
892	#define KLDR_ERR_INVALID_HANDLE (KLDR_ERR_BASE + 33)
893	/** The module wasn't loaded dynamically. */
894	#define KLDR_ERR_NOT_LOADED_DYNAMICALLY (KLDR_ERR_BASE + 34)
895	/** The module wasn't found. */
896	#define KLDR_ERR_MODULE_NOT_FOUND (KLDR_ERR_BASE + 35)
897	/** A prerequisit module wasn't found. */
898	#define KLDR_ERR_PREREQUISITE_MODULE_NOT_FOUND (KLDR_ERR_BASE + 36)
899	/** The module is being terminated and can therefore not be loaded. */
900	#define KLDR_ERR_MODULE_TERMINATING (KLDR_ERR_BASE + 37)
901	/** A prerequisit module is being terminated and can therefore not be loaded. */
902	#define KLDR_ERR_PREREQUISITE_MODULE_TERMINATING (KLDR_ERR_BASE + 38)
903	/** The module initialization failed. */
904	#define KLDR_ERR_MODULE_INIT_FAILED (KLDR_ERR_BASE + 39)
905	/** The initialization of a prerequisite module failed. */
906	#define KLDR_ERR_PREREQUISITE_MODULE_INIT_FAILED (KLDR_ERR_BASE + 40)
907	/** The module has already failed initialization and can't be attempted reloaded until
908	* after we've finished garbage collection. */
909	#define KLDR_ERR_MODULE_INIT_FAILED_ALREADY (KLDR_ERR_BASE + 41)
910	/** A prerequisite module has already failed initialization and can't be attempted
911	* reloaded until after we've finished garbage collection. */
912	#define KLDR_ERR_PREREQUISITE_MODULE_INIT_FAILED_ALREADY (KLDR_ERR_BASE + 42)
913	/** Prerequisite recursed too deeply. */
914	#define KLDR_ERR_PREREQUISITE_RECURSED_TOO_DEEPLY (KLDR_ERR_BASE + 43)
915	/** Failed to allocate the main stack. */
916	#define KLDR_ERR_MAIN_STACK_ALLOC_FAILED (KLDR_ERR_BASE + 44)
917	/** Buffer overflow. */
918	#define KLDR_ERR_BUFFER_OVERFLOW (KLDR_ERR_BASE + 45)
919	/** The specified ARCH+CPU isn't compatible with image. */
920	#define KLDR_ERR_ARCH_CPU_NOT_COMPATIBLE (KLDR_ERR_BASE + 45)
921	/** Symbol not found. */
922	#define KLDR_ERR_SYMBOL_NOT_FOUND (KLDR_ERR_BASE + 46)
923
924	/** Encountered a bad fixup. */
925	#define KLDR_ERR_BAD_FIXUP (KLDR_ERR_BASE + 48)
926
927	/** A memory allocation failed. */
928	#define KLDR_ERR_NO_MEMORY (KLDR_ERR_BASE + 64)
929
930	/** @} */
931
932
933	#ifdef __cplusplus
934	}
935	#endif
936
937	#endif
938

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

Download in other formats: