kLdr.h@ 41

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

Line
1	/* $Id: kLdr.h 41 2011-08-24 14:35:57Z bird $ */
2	/** @file
3	* kLdr - The Dynamic Loader.
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	#ifndef ___k_kLdr_h___
32	#define ___k_kLdr_h___
33
34	#ifdef __cplusplus
35	extern "C" {
36	#endif
37
38	/*
39	* Include the base typedefs and macros.
40	*/
41	#include <k/kDefs.h>
42	#include <k/kTypes.h>
43	#include <k/kCpus.h>
44
45
46	/** @defgroup grp_kLdrBasic kLdr Basic Types
47	* @{ */
48
49	/** The kLdr address type. */
50	typedef KU64 KLDRADDR;
51	/** Pointer to a kLdr address. */
52	typedef KLDRADDR *PKLDRADDR;
53	/** Pointer to a const kLdr address. */
54	typedef const KLDRADDR *PCKLDRADDR;
55
56	/** NIL address. */
57	#define NIL_KLDRADDR (~(KU64)0)
58
59	/** @def PRI_KLDRADDR
60	* printf format type. */
61	#ifdef _MSC_VER
62	# define PRI_KLDRADDR "I64x"
63	#else
64	# define PRI_KLDRADDR "llx"
65	#endif
66
67	/** Align a KSIZE value. */
68	#define KLDR_ALIGN_ADDR(val, align) ( ((val) + ((align) - 1)) & ~(KLDRADDR)((align) - 1) )
69
70
71	/** The kLdr size type. */
72	typedef KU64 KLDRSIZE;
73	/** Pointer to a kLdr size. */
74	typedef KLDRSIZE *PKLDRSIZE;
75	/** Pointer to a const kLdr size. */
76	typedef const KLDRSIZE *PCKLDRSIZE;
77
78	/** @def PRI_KLDRSIZE
79	* printf format type. */
80	#ifdef _MSC_VER
81	# define PRI_KLDRSIZE "I64x"
82	#else
83	# define PRI_KLDRSIZE "llx"
84	#endif
85
86
87	/** The kLdr file offset type. */
88	typedef long KLDRFOFF;
89	/** Pointer to a kLdr file offset type. */
90	typedef KLDRFOFF *PKLDRFOFF;
91	/** Pointer to a const kLdr file offset type. */
92	typedef const KLDRFOFF *PCKLDRFOFF;
93
94	/** @def PRI_KLDRFOFF
95	* printf format type. */
96	#define PRI_KLDRFOFF "lx"
97
98
99	/**
100	* Union of all the integer types.
101	*/
102	typedef union KLDRU
103	{
104	KI8 i8; /*< KI8 view. /
105	KU8 u8; /*< KU8 view. /
106	KI16 i16; /*< KI16 view. /
107	KU16 u16; /*< KU16 view. /
108	KI32 i32; /*< KI32 view. /
109	KU32 u32; /*< KU32 view. /
110	KI64 i64; /*< KI64 view. /
111	KU64 u64; /*< KU64 view. /
112
113	KI8 ai8[8]; /*< KI8 array view . /
114	KU8 au8[8]; /*< KU8 array view. /
115	KI16 ai16[4];/*< KI16 array view . /
116	KU16 au16[4];/*< KU16 array view. /
117	KI32 ai32[2];/*< KI32 array view . /
118	KU32 au32[2];/*< KU32 array view. /
119
120	signed char ch; /*< signed char view. /
121	unsigned char uch; /*< unsigned char view. /
122	signed short s; /*< signed short view. /
123	unsigned short us; /*< unsigned short view. /
124	signed int i; /*< signed int view. /
125	unsigned int u; /*< unsigned int view. /
126	signed long l; /*< signed long view. /
127	unsigned long ul; /*< unsigned long view. /
128	void pv; /< void pointer view. /
129
130	KLDRADDR Addr; /*< kLdr address view. /
131	KLDRSIZE Size; /*< kLdr size view. /
132	} KLDRU;
133	/** Pointer to an integer union. */
134	typedef KLDRU *PKLDRU;
135	/** Pointer to a const integer union. */
136	typedef const KLDRU *PCKLDRU;
137
138
139	/**
140	* Union of pointers to all the integer types.
141	*/
142	typedef union KLDRPU
143	{
144	KI8 pi8; /< KI8 view. /
145	KU8 pu8; /< KU8 view. /
146	KI16 pi16; /< KI16 view. /
147	KU16 pu16; /< KU16 view. /
148	KI32 pi32; /< KI32 view. /
149	KU32 pu32; /< KU32 view. /
150	KI64 pi64; /< KI64 view. /
151	KU64 pu64; /< KU64 view. /
152
153	signed char pch; /< signed char view. /
154	unsigned char puch; /< unsigned char view. /
155	signed short ps; /< signed short view. /
156	unsigned short pus; /< unsigned short view. /
157	signed int pi; /< signed int view. /
158	unsigned int pu; /< unsigned int view. /
159	signed long pl; /< signed long view. /
160	unsigned long pul; /< unsigned long view. /
161	void pv; /< void pointer view. /
162	} KLDRPU;
163	/** Pointer to an integer pointer union. */
164	typedef KLDRPU *PKLDRPU;
165	/** Pointer to a const integer pointer union. */
166	typedef const KLDRPU *PCKLDRPU;
167
168	/** @} */
169
170
171	/** @defgroup grp_kLdrMod kLdrMod - The executable image intepreter
172	* @{ */
173
174	/**
175	* Debug info type (from the loader point of view).
176	*/
177	typedef enum KLDRDBGINFOTYPE
178	{
179	/** The usual invalid enum value. */
180	KLDRDBGINFOTYPE_INVALID = 0,
181	/** Unknown debug info format. */
182	KLDRDBGINFOTYPE_UNKNOWN,
183	/** Stabs. */
184	KLDRDBGINFOTYPE_STABS,
185	/** Debug With Arbitrary Record Format (DWARF). */
186	KLDRDBGINFOTYPE_DWARF,
187	/** Microsoft Codeview debug info. */
188	KLDRDBGINFOTYPE_CODEVIEW,
189	/** Watcom debug info. */
190	KLDRDBGINFOTYPE_WATCOM,
191	/** IBM High Level Language debug info.. */
192	KLDRDBGINFOTYPE_HLL,
193	/** The end of the valid debug info values (exclusive). */
194	KLDRDBGINFOTYPE_END,
195	/** Blow the type up to 32-bit. */
196	KLDRDBGINFOTYPE_32BIT_HACK = 0x7fffffff
197	} KLDRDBGINFOTYPE;
198	/** Pointer to a kLdr debug info type. */
199	typedef KLDRDBGINFOTYPE *PKLDRDBGINFOTYPE;
200
201
202	/**
203	* Stack information.
204	*/
205	typedef struct KLDRSTACKINFO
206	{
207	/** The base address of the stack (sub) segment.
208	* Set this to NIL_KLDRADDR if the module doesn't include any stack segment. */
209	KLDRADDR Address;
210	/** The base address of the stack (sub) segment, link address.
211	* Set this to NIL_KLDRADDR if the module doesn't include any stack (sub)segment. */
212	KLDRADDR LinkAddress;
213	/** The stack size of the main thread.
214	* If no stack (sub)segment in the module, this is the stack size of the main thread.
215	* If the module doesn't contain this kind of information this field will be set to 0. */
216	KLDRSIZE cbStack;
217	/** The stack size of non-main threads.
218	* If the module doesn't contain this kind of information this field will be set to 0. */
219	KLDRSIZE cbStackThread;
220	} KLDRSTACKINFO;
221	/** Pointer to stack information. */
222	typedef KLDRSTACKINFO *PKLDRSTACKINFO;
223	/** Pointer to const stack information. */
224	typedef const KLDRSTACKINFO *PCKLDRSTACKINFO;
225
226
227	/**
228	* Loader segment.
229	*/
230	typedef struct KLDRSEG
231	{
232	/** Variable free to use for the kLdr user. */
233	void *pvUser;
234	/** The segment name. (Might not be zero terminated!) */
235	const char *pchName;
236	/** The length of the segment name. */
237	KU32 cchName;
238	/** The flat selector to use for the segment (i.e. data/code).
239	* Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
240	KU16 SelFlat;
241	/** The 16-bit selector to use for the segment.
242	* Primarily a way for the user to specify selectors for the LX/LE and NE interpreters. */
243	KU16 Sel16bit;
244	/** Segment flags. */
245	KU32 fFlags;
246	/** The segment protection. */
247	KPROT enmProt;
248	/** The size of the segment. */
249	KLDRSIZE cb;
250	/** The required segment alignment.
251	* The to 0 if the segment isn't supposed to be mapped. */
252	KLDRADDR Alignment;
253	/** The link address.
254	* Set to NIL_KLDRADDR if the segment isn't supposed to be
255	* mapped or if the image doesn't have link addresses. */
256	KLDRADDR LinkAddress;
257	/** File offset of the segment.
258	* Set to -1 if no file backing (like BSS). */
259	KLDRFOFF offFile;
260	/** Size of the file bits of the segment.
261	* Set to -1 if no file backing (like BSS). */
262	KLDRFOFF cbFile;
263	/** The relative virtual address when mapped.
264	* Set to NIL_KLDRADDR if the segment isn't supposed to be mapped. */
265	KLDRADDR RVA;
266	/** The size of the segment including the alignment gap up to the next segment when mapped. */
267	KSIZE cbMapped;
268	/** The address the segment was mapped at by kLdrModMap().
269	* Set to 0 if not mapped. */
270	KUPTR MapAddress;
271	} KLDRSEG;
272
273
274	/** @name Segment flags
275	* @{ */
276	/** The segment is 16-bit. When not set the default of the target architecture is assumed. */
277	#define KLDRSEG_FLAG_16BIT 1
278	/** The segment requires a 16-bit selector alias. (OS/2) */
279	#define KLDRSEG_FLAG_OS2_ALIAS16 2
280	/** Conforming segment (x86 weirdness). (OS/2) */
281	#define KLDRSEG_FLAG_OS2_CONFORM 4
282	/** IOPL (ring-2) segment. (OS/2) */
283	#define KLDRSEG_FLAG_OS2_IOPL 8
284	/** @} */
285
286
287	/**
288	* Loader module format.
289	*/
290	typedef enum KLDRFMT
291	{
292	/** The usual invalid 0 format. */
293	KLDRFMT_INVALID = 0,
294	/** The native OS loader. */
295	KLDRFMT_NATIVE,
296	/** The AOUT loader. */
297	KLDRFMT_AOUT,
298	/** The ELF loader. */
299	KLDRFMT_ELF,
300	/** The LX loader. */
301	KLDRFMT_LX,
302	/** The Mach-O loader. */
303	KLDRFMT_MACHO,
304	/** The PE loader. */
305	KLDRFMT_PE,
306	/** The end of the valid format values (exclusive). */
307	KLDRFMT_END,
308	/** Hack to blow the type up to 32-bit. */
309	KLDRFMT_32BIT_HACK = 0x7fffffff
310	} KLDRFMT;
311
312
313	/**
314	* Loader module type.
315	*/
316	typedef enum KLDRTYPE
317	{
318	/** The usual invalid 0 type. */
319	KLDRTYPE_INVALID = 0,
320	/** Object file. */
321	KLDRTYPE_OBJECT,
322	/** Executable module, fixed load address. */
323	KLDRTYPE_EXECUTABLE_FIXED,
324	/** Executable module, relocatable, non-fixed load address. */
325	KLDRTYPE_EXECUTABLE_RELOCATABLE,
326	/** Executable module, position independent code, non-fixed load address. */
327	KLDRTYPE_EXECUTABLE_PIC,
328	/** Shared library, fixed load address.
329	* Typically a system library. */
330	KLDRTYPE_SHARED_LIBRARY_FIXED,
331	/** Shared library, relocatable, non-fixed load address. */
332	KLDRTYPE_SHARED_LIBRARY_RELOCATABLE,
333	/** Shared library, position independent code, non-fixed load address. */
334	KLDRTYPE_SHARED_LIBRARY_PIC,
335	/** DLL that contains no code or data only imports and exports. (Chiefly OS/2.) */
336	KLDRTYPE_FORWARDER_DLL,
337	/** Core or dump. */
338	KLDRTYPE_CORE,
339	/** Debug module (debug info with empty code & data segments). */
340	KLDRTYPE_DEBUG_INFO,
341	/** The end of the valid types values (exclusive). */
342	KLDRTYPE_END,
343	/** Hack to blow the type up to 32-bit. */
344	KLDRTYPE_32BIT_HACK = 0x7fffffff
345	} KLDRTYPE;
346
347
348	/**
349	* Loader endian indicator.
350	*/
351	typedef enum KLDRENDIAN
352	{
353	/** The usual invalid endian. */
354	KLDRENDIAN_INVALID,
355	/** Little endian. */
356	KLDRENDIAN_LITTLE,
357	/** Bit endian. */
358	KLDRENDIAN_BIG,
359	/** Endianness doesn't have a meaning in the context. */
360	KLDRENDIAN_NA,
361	/** The end of the valid endian values (exclusive). */
362	KLDRENDIAN_END,
363	/** Hack to blow the type up to 32-bit. */
364	KLDRENDIAN_32BIT_HACK = 0x7fffffff
365	} KLDRENDIAN;
366
367
368	/** Pointer to a module interpreter method table. */
369	typedef struct KLDRMODOPS *PKLDRMODOPS;
370	/** Pointer to const module interpreter methods table. */
371	typedef const struct KLDRMODOPS *PCKLDRMODOPS;
372
373	/**
374	* Module interpreter instance.
375	* All members are read only unless you're kLdrMod or the module interpreter.
376	*/
377	typedef struct KLDRMOD
378	{
379	/** Magic number (KLDRMOD_MAGIC). */
380	KU32 u32Magic;
381	/** The format of this module. */
382	KLDRFMT enmFmt;
383	/** The type of module. */
384	KLDRTYPE enmType;
385	/** The CPU architecture this module was built for. */
386	KCPUARCH enmArch;
387	/** The minium cpu this module was built for.
388	* This might not be accurate, so use kLdrModCanExecuteOn() to check. */
389	KCPU enmCpu;
390	/** The endian used by the module. */
391	KLDRENDIAN enmEndian;
392	/** The filename length (bytes). */
393	KU32 cchFilename;
394	/** The filename. */
395	const char *pszFilename;
396	/** The module name. */
397	const char *pszName;
398	/** The module name length (bytes). */
399	KU32 cchName;
400	/** The number of segments in the module. */
401	KU32 cSegments;
402	/** Pointer to the loader methods.
403	* Not meant for calling directly thru! */
404	PCKLDRMODOPS pOps;
405	/** Pointer to the read instance. (Can be NULL after kLdrModDone().)*/
406	PKRDR pRdr;
407	/** The module data. */
408	void *pvData;
409	/** Segments. (variable size, can be zero) */
410	KLDRSEG aSegments[1];
411	} KLDRMOD, PKLDRMOD, *PPKLDRMOD;
412
413	/** The magic for KLDRMOD::u32Magic. (Kosuke Fujishima) */
414	#define KLDRMOD_MAGIC 0x19640707
415
416
417	/** Special base address value alias for the link address. */
418	#define KLDRMOD_BASEADDRESS_LINK (~(KLDRADDR)1)
419	/** Special base address value alias for the actual load address (must be mapped). */
420	#define KLDRMOD_BASEADDRESS_MAP (~(KLDRADDR)2)
421
422	/** Special import module ordinal value used to indicate that there is no
423	* specific module associated with the requested symbol. */
424	#define NIL_KLDRMOD_IMPORT (~(KU32)0)
425
426	/** Special symbol ordinal value used to indicate that the symbol
427	* only has a string name. */
428	#define NIL_KLDRMOD_SYM_ORDINAL (~(KU32)0)
429
430
431	/** @name Load symbol kind flags.
432	* @{ */
433	/** The bitness doesn't matter. */
434	#define KLDRSYMKIND_NO_BIT 0x00000000
435	/** 16-bit symbol. */
436	#define KLDRSYMKIND_16BIT 0x00000001
437	/** 32-bit symbol. */
438	#define KLDRSYMKIND_32BIT 0x00000002
439	/** 64-bit symbol. */
440	#define KLDRSYMKIND_64BIT 0x00000003
441	/** Mask out the bit.*/
442	#define KLDRSYMKIND_BIT_MASK 0x00000003
443	/** We don't know the type of symbol. */
444	#define KLDRSYMKIND_NO_TYPE 0x00000000
445	/** The symbol is a code object (method/function/procedure/whateveryouwannacallit). */
446	#define KLDRSYMKIND_CODE 0x00000010
447	/** The symbol is a data object. */
448	#define KLDRSYMKIND_DATA 0x00000020
449	/** Mask out the symbol type. */
450	#define KLDRSYMKIND_TYPE_MASK 0x00000030
451	/** Valid symbol kind mask. */
452	#define KLDRSYMKIND_MASK 0x00000033
453	/** Weak symbol. */
454	#define KLDRSYMKIND_WEAK 0x00000100
455	/** Forwarder symbol. */
456	#define KLDRSYMKIND_FORWARDER 0x00000200
457	/** Request a flat symbol address. */
458	#define KLDRSYMKIND_REQ_FLAT 0x00000000
459	/** Request a segmented symbol address. */
460	#define KLDRSYMKIND_REQ_SEGMENTED 0x40000000
461	/** Request type mask. */
462	#define KLDRSYMKIND_REQ_TYPE_MASK 0x40000000
463	/** @} */
464
465	/** @name kLdrModEnumSymbols flags.
466	* @{ */
467	/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
468	#define KLDRMOD_ENUM_SYMS_FLAGS_ALL 0x00000001
469	/** @} */
470
471
472	/**
473	* Callback for resolving imported symbols when applying fixups.
474	*
475	* @returns 0 on success and pValue and pfKind filled.
476	* @returns Non-zero OS specific or kLdr status code on failure.
477	*
478	* @param pMod The module which fixups are begin applied.
479	* @param iImport The import module ordinal number or NIL_KLDRMOD_IMPORT.
480	* @param iSymbol The symbol ordinal number or NIL_KLDRMOD_SYM_ORDINAL.
481	* @param pchSymbol The symbol name. Can be NULL if iSymbol isn't nil. Doesn't have to be null-terminated.
482	* @param cchSymbol The length of the symbol.
483	* @param pszVersion The symbol version. NULL if not versioned.
484	* @param puValue Where to store the symbol value.
485	* @param pfKind Where to store the symbol kind flags.
486	* @param pvUser The user parameter specified to the relocation function.
487	*/
488	typedef int FNKLDRMODGETIMPORT(PKLDRMOD pMod, KU32 iImport, KU32 iSymbol, const char *pchSymbol, KSIZE cchSymbol,
489	const char pszVersion, PKLDRADDR puValue, KU32 pfKind, void *pvUser);
490	/** Pointer to a import callback. */
491	typedef FNKLDRMODGETIMPORT *PFNKLDRMODGETIMPORT;
492
493	/**
494	* Symbol enumerator callback.
495	*
496	* @returns 0 if enumeration should continue.
497	* @returns non-zero if the enumeration should stop. This status code will then be returned by kLdrModEnumSymbols().
498	*
499	* @param pMod The module which symbols are being enumerated.s
500	* @param iSymbol The symbol ordinal number or NIL_KLDRMOD_SYM_ORDINAL.
501	* @param pchSymbol The symbol name. This can be NULL if there is a symbol ordinal.
502	* This can also be an empty string if the symbol doesn't have a name
503	* or it's name has been stripped.
504	* Important, this doesn't have to be a null-terminated string.
505	* @param cchSymbol The length of the symbol.
506	* @param pszVersion The symbol version. NULL if not versioned.
507	* @param uValue The symbol value.
508	* @param fKind The symbol kind flags.
509	* @param pvUser The user parameter specified to kLdrModEnumSymbols().
510	*/
511	typedef int FNKLDRMODENUMSYMS(PKLDRMOD pMod, KU32 iSymbol, const char pchSymbol, KSIZE cchSymbol, const char pszVersion,
512	KLDRADDR uValue, KU32 fKind, void *pvUser);
513	/** Pointer to a symbol enumerator callback. */
514	typedef FNKLDRMODENUMSYMS *PFNKLDRMODENUMSYMS;
515
516	/**
517	* Debug info enumerator callback.
518	*
519	* @returns 0 to continue the enumeration.
520	* @returns non-zero if the enumeration should stop. This status code will then be returned by kLdrModEnumDbgInfo().
521	*
522	* @param pMod The module.
523	* @param iDbgInfo The debug info ordinal number / id.
524	* @param enmType The debug info type.
525	* @param iMajorVer The major version number of the debug info format. -1 if unknow - implies invalid iMinorVer.
526	* @param iMinorVer The minor version number of the debug info format. -1 when iMajorVer is -1.
527	* @param pszPartNm The name of the debug info part, NULL if not applicable.
528	* @param offFile The file offset if this type has one specific location in the executable image file.
529	* This is -1 if there isn't any specific file location.
530	* @param LinkAddress The link address of the debug info if it's loadable. NIL_KLDRADDR if not loadable.
531	* @param cb The size of the debug information. -1 is used if this isn't applicable.
532	* @param pszExtFile This points to the name of an external file containing the debug info.
533	* This is NULL if there isn't any external file.
534	* @param pvUser The user parameter specified to kLdrModEnumDbgInfo.
535	*/
536	typedef int FNKLDRENUMDBG(PKLDRMOD pMod, KU32 iDbgInfo, KLDRDBGINFOTYPE enmType, KI16 iMajorVer, KI16 iMinorVer,
537	const char *pszPartNm, KLDRFOFF offFile, KLDRADDR LinkAddress, KLDRSIZE cb,
538	const char pszExtFile, void pvUser);
539	/** Pointer to a debug info enumerator callback. */
540	typedef FNKLDRENUMDBG *PFNKLDRENUMDBG;
541
542	/**
543	* Resource enumerator callback.
544	*
545	* @returns 0 to continue the enumeration.
546	* @returns non-zero if the enumeration should stop. This status code will then be returned by kLdrModEnumResources().
547	*
548	* @param pMod The module.
549	* @param idType The resource type id. NIL_KLDRMOD_RSRC_TYPE_ID if no type id.
550	* @param pszType The resource type name. NULL if no type name.
551	* @param idName The resource id. NIL_KLDRMOD_RSRC_NAME_ID if no id.
552	* @param pszName The resource name. NULL if no name.
553	* @param idLang The language id.
554	* @param AddrRsrc The address value for the resource.
555	* @param cbRsrc The size of the resource.
556	* @param pvUser The user parameter specified to kLdrModEnumDbgInfo.
557	*/
558	typedef int FNKLDRENUMRSRC(PKLDRMOD pMod, KU32 idType, const char pszType, KU32 idName, const char pszName,
559	KU32 idLang, KLDRADDR AddrRsrc, KLDRSIZE cbRsrc, void *pvUser);
560	/** Pointer to a resource enumerator callback. */
561	typedef FNKLDRENUMRSRC *PFNKLDRENUMRSRC;
562
563	/** NIL resource name ID. */
564	#define NIL_KLDRMOD_RSRC_NAME_ID ( ~(KU32)0 )
565	/** NIL resource type ID. */
566	#define NIL_KLDRMOD_RSRC_TYPE_ID ( ~(KU32)0 )
567	/** @name Language ID
568	*
569	* Except for the special IDs #defined here, the values are considered
570	* format specific for now since it's only used by the PE resources.
571	*
572	* @{ */
573	/** NIL language ID. */
574	#define NIL_KLDR_LANG_ID ( ~(KU32)0 )
575	/** Special language id value for matching any language. */
576	#define KLDR_LANG_ID_ANY ( ~(KU32)1 )
577	/** Special language id value indicating language neutral. */
578	#define KLDR_LANG_ID_NEUTRAL ( ~(KU32)2 )
579	/** Special language id value indicating user default language. */
580	#define KLDR_LANG_ID_USER_DEFAULT ( ~(KU32)3 )
581	/** Special language id value indicating system default language. */
582	#define KLDR_LANG_ID_SYS_DEFAULT ( ~(KU32)4 )
583	/** Special language id value indicating default custom locale. */
584	#define KLDR_LANG_ID_CUSTOM_DEFAULT ( ~(KU32)5 )
585	/** Special language id value indicating unspecified custom locale. */
586	#define KLDR_LANG_ID_CUSTOM_UNSPECIFIED ( ~(KU32)6 )
587	/** Special language id value indicating default custom MUI locale. */
588	#define KLDR_LANG_ID_UI_CUSTOM_DEFAULT ( ~(KU32)7 )
589	/** @} */
590
591
592	int kLdrModOpen(const char *pszFilename, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod);
593	int kLdrModOpenFromRdr(PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod);
594	int kLdrModOpenNative(const char *pszFilename, PPKLDRMOD ppMod);
595	int kLdrModOpenNativeByHandle(KUPTR uHandle, PPKLDRMOD ppMod);
596	int kLdrModClose(PKLDRMOD pMod);
597
598	int kLdrModQuerySymbol(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
599	const char pchSymbol, KSIZE cchSymbol, const char pszVersion,
600	PFNKLDRMODGETIMPORT pfnGetForwarder, void pvUser, PKLDRADDR puValue, KU32 pfKind);
601	int kLdrModEnumSymbols(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress,
602	KU32 fFlags, PFNKLDRMODENUMSYMS pfnCallback, void *pvUser);
603	int kLdrModGetImport(PKLDRMOD pMod, const void pvBits, KU32 iImport, char pszName, KSIZE cchName);
604	KI32 kLdrModNumberOfImports(PKLDRMOD pMod, const void *pvBits);
605	int kLdrModCanExecuteOn(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu);
606	int kLdrModGetStackInfo(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo);
607	int kLdrModQueryMainEntrypoint(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress);
608	int kLdrModQueryResource(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
609	KU32 idName, const char pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE pcbRsrc);
610	int kLdrModEnumResources(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
611	KU32 idName, const char pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void pvUser);
612	int kLdrModEnumDbgInfo(PKLDRMOD pMod, const void pvBits, PFNKLDRENUMDBG pfnCallback, void pvUser);
613	int kLdrModHasDbgInfo(PKLDRMOD pMod, const void *pvBits);
614	int kLdrModMostlyDone(PKLDRMOD pMod);
615
616
617	/** @name Operations On The Internally Managed Mapping
618	* @{ */
619	int kLdrModMap(PKLDRMOD pMod);
620	int kLdrModUnmap(PKLDRMOD pMod);
621	int kLdrModAllocTLS(PKLDRMOD pMod);
622	void kLdrModFreeTLS(PKLDRMOD pMod);
623	int kLdrModReload(PKLDRMOD pMod);
624	int kLdrModFixupMapping(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
625	int kLdrModCallInit(PKLDRMOD pMod, KUPTR uHandle);
626	int kLdrModCallTerm(PKLDRMOD pMod, KUPTR uHandle);
627	int kLdrModCallThread(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching);
628	/** @} */
629
630	/** @name Operations On The Externally Managed Mappings
631	* @{ */
632	KLDRADDR kLdrModSize(PKLDRMOD pMod);
633	int kLdrModGetBits(PKLDRMOD pMod, void pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void pvUser);
634	int kLdrModRelocateBits(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
635	PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
636	/** @} */
637
638
639	/**
640	* The loader module operation.
641	*/
642	typedef struct KLDRMODOPS
643	{
644	/** The name of this module interpreter. */
645	const char *pszName;
646	/** Pointer to the next module interpreter. */
647	PCKLDRMODOPS pNext;
648
649	/**
650	* Create a loader module instance interpreting the executable image found
651	* in the specified file provider instance.
652	*
653	* @returns 0 on success and *ppMod pointing to a module instance.
654	* On failure, a non-zero OS specific error code is returned.
655	* @param pOps Pointer to the registered method table.
656	* @param pRdr The file provider instance to use.
657	* @param fFlags Flags, MBZ.
658	* @param enmCpuArch The desired CPU architecture. KCPUARCH_UNKNOWN means
659	* anything goes, but with a preference for the current
660	* host architecture.
661	* @param offNewHdr The offset of the new header in MZ files. -1 if not found.
662	* @param ppMod Where to store the module instance pointer.
663	*/
664	int (* pfnCreate)(PCKLDRMODOPS pOps, PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, KLDRFOFF offNewHdr, PPKLDRMOD ppMod);
665	/**
666	* Destroys an loader module instance.
667	*
668	* The caller is responsible for calling kLdrModUnmap() and kLdrFreeTLS() first.
669	*
670	* @returns 0 on success, non-zero on failure. The module instance state
671	* is unknown on failure, it's best not to touch it.
672	* @param pMod The module.
673	*/
674	int (* pfnDestroy)(PKLDRMOD pMod);
675
676	/** @copydoc kLdrModQuerySymbol */
677	int (* pfnQuerySymbol)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
678	const char pchSymbol, KSIZE cchSymbol, const char pszVersion,
679	PFNKLDRMODGETIMPORT pfnGetForwarder, void pvUser, PKLDRADDR puValue, KU32 pfKind);
680	/** @copydoc kLdrModEnumSymbols */
681	int (* pfnEnumSymbols)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 fFlags,
682	PFNKLDRMODENUMSYMS pfnCallback, void *pvUser);
683	/** @copydoc kLdrModGetImport */
684	int (* pfnGetImport)(PKLDRMOD pMod, const void pvBits, KU32 iImport, char pszName, KSIZE cchName);
685	/** @copydoc kLdrModNumberOfImports */
686	KI32 (* pfnNumberOfImports)(PKLDRMOD pMod, const void *pvBits);
687	/** @copydoc kLdrModCanExecuteOn */
688	int (* pfnCanExecuteOn)(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu);
689	/** @copydoc kLdrModGetStackInfo */
690	int (* pfnGetStackInfo)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo);
691	/** @copydoc kLdrModQueryMainEntrypoint */
692	int (* pfnQueryMainEntrypoint)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress);
693	/** @copydoc kLdrModQueryResource */
694	int (* pfnQueryResource)(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
695	KU32 idName, const char pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE pcbRsrc);
696	/** @copydoc kLdrModEnumResources */
697	int (* pfnEnumResources)(PKLDRMOD pMod, const void pvBits, KLDRADDR BaseAddress, KU32 idType, const char pszType,
698	KU32 idName, const char pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void pvUser);
699	/** @copydoc kLdrModEnumDbgInfo */
700	int (* pfnEnumDbgInfo)(PKLDRMOD pMod, const void pvBits, PFNKLDRENUMDBG pfnCallback, void pvUser);
701	/** @copydoc kLdrModHasDbgInfo */
702	int (* pfnHasDbgInfo)(PKLDRMOD pMod, const void *pvBits);
703	/** @copydoc kLdrModMap */
704	int (* pfnMap)(PKLDRMOD pMod);
705	/** @copydoc kLdrModUnmap */
706	int (* pfnUnmap)(PKLDRMOD pMod);
707	/** @copydoc kLdrModAllocTLS */
708	int (* pfnAllocTLS)(PKLDRMOD pMod);
709	/** @copydoc kLdrModFreeTLS */
710	void (*pfnFreeTLS)(PKLDRMOD pMod);
711	/** @copydoc kLdrModReload */
712	int (* pfnReload)(PKLDRMOD pMod);
713	/** @copydoc kLdrModFixupMapping */
714	int (* pfnFixupMapping)(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
715	/** @copydoc kLdrModCallInit */
716	int (* pfnCallInit)(PKLDRMOD pMod, KUPTR uHandle);
717	/** @copydoc kLdrModCallTerm */
718	int (* pfnCallTerm)(PKLDRMOD pMod, KUPTR uHandle);
719	/** @copydoc kLdrModCallThread */
720	int (* pfnCallThread)(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching);
721	/** @copydoc kLdrModSize */
722	KLDRADDR (* pfnSize)(PKLDRMOD pMod);
723	/** @copydoc kLdrModGetBits */
724	int (* pfnGetBits)(PKLDRMOD pMod, void pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void pvUser);
725	/** @copydoc kLdrModRelocateBits */
726	int (* pfnRelocateBits)(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
727	PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
728	/** @copydoc kLdrModMostlyDone */
729	int (* pfnMostlyDone)(PKLDRMOD pMod);
730	/** Dummy which should be assigned a non-zero value. */
731	KU32 uEndOfStructure;
732	} KLDRMODOPS;
733
734
735	/** @} */
736
737
738
739
740	/** @defgroup grp_kLdrDyld kLdrDyld - The dynamic loader
741	* @{ */
742
743	/** The handle to a dynamic loader module. */
744	typedef struct KLDRDYLDMOD *HKLDRMOD;
745	/** Pointer to the handle to a dynamic loader module. */
746	typedef HKLDRMOD *PHKLDRMOD;
747	/** NIL handle value. */
748	#define NIL_HKLDRMOD ((HKLDRMOD)0)
749
750
751	/**
752	* File search method.
753	*
754	* In addition to it's own way of finding files, kLdr emulates
755	* the methods employed by the most popular systems.
756	*/
757	typedef enum KLDRDYLDSEARCH
758	{
759	/** The usual invalid file search method. */
760	KLDRDYLD_SEARCH_INVALID = 0,
761	/** Uses the kLdr file search method.
762	* @todo invent me. */
763	KLDRDYLD_SEARCH_KLDR,
764	/** Use the emulation closest to the host system. */
765	KLDRDYLD_SEARCH_HOST,
766	/** Emulate the OS/2 file search method.
767	* On non-OS/2 systems, BEGINLIBPATH, LIBPATH, ENDLIBPATH and LIBPATHSTRICT are
768	* taken form the environment. */
769	KLDRDYLD_SEARCH_OS2,
770	/** Emulate the standard window file search method. */
771	KLDRDYLD_SEARCH_WINDOWS,
772	/** Emulate the alternative window file search method. */
773	KLDRDYLD_SEARCH_WINDOWS_ALTERED,
774	/** Emulate the most common UNIX file search method. */
775	KLDRDYLD_SEARCH_UNIX_COMMON,
776	/** End of the valid file search method values. */
777	KLDRDYLD_SEARCH_END,
778	/** Hack to blow the type up to 32-bit. */
779	KLDRDYLD_SEARCH_32BIT_HACK = 0x7fffffff
780	} KLDRDYLDSEARCH;
781
782	/** @name kLdrDyldLoad and kLdrDyldFindByName flags.
783	* @{ */
784	/** The symbols in the module should be loaded into the global unix namespace.
785	* If not specified, the symbols are local and can only be referenced directly. */
786	#define KLDRYDLD_LOAD_FLAGS_GLOBAL_SYMBOLS 0x00000001
787	/** The symbols in the module should be loaded into the global unix namespace and
788	* it's symbols should take precedence over all currently loaded modules.
789	* This implies KLDRYDLD_LOAD_FLAGS_GLOBAL_SYMBOLS. */
790	#define KLDRYDLD_LOAD_FLAGS_DEEP_SYMBOLS 0x00000002
791	/** The module shouldn't be found by a global module search.
792	* If not specified, the module can be found by unspecified module searches,
793	* typical used when loading import/dep modules. */
794	#define KLDRYDLD_LOAD_FLAGS_SPECIFIC_MODULE 0x00000004
795	/** Do a recursive initialization calls instead of defering them to the outermost call. */
796	#define KLDRDYLD_LOAD_FLAGS_RECURSIVE_INIT 0x00000008
797	/** We're loading the executable module.
798	* @internal */
799	#define KLDRDYLD_LOAD_FLAGS_EXECUTABLE 0x40000000
800	/** @} */
801
802
803	int kLdrDyldLoad(const char pszDll, const char pszPrefix, const char *pszSuffix, KLDRDYLDSEARCH enmSearch,
804	unsigned fFlags, PHKLDRMOD phMod, char *pszErr, KSIZE cchErr);
805	int kLdrDyldUnload(HKLDRMOD hMod);
806	int kLdrDyldFindByName(const char pszDll, const char pszPrefix, const char *pszSuffix, KLDRDYLDSEARCH enmSearch,
807	unsigned fFlags, PHKLDRMOD phMod);
808	int kLdrDyldFindByAddress(KUPTR Address, PHKLDRMOD phMod, KU32 piSegment, KUPTR poffSegment);
809	int kLdrDyldGetName(HKLDRMOD hMod, char *pszName, KSIZE cchName);
810	int kLdrDyldGetFilename(HKLDRMOD hMod, char *pszFilename, KSIZE cchFilename);
811	int kLdrDyldQuerySymbol(HKLDRMOD hMod, KU32 uSymbolOrdinal, const char *pszSymbolName,
812	const char pszSymbolVersion, KUPTR pValue, KU32 *pfKind);
813	int kLdrDyldQueryResource(HKLDRMOD hMod, KU32 idType, const char *pszType, KU32 idName,
814	const char pszName, KU32 idLang, void pvRsrc, KSIZE pcbRsrc);
815	int kLdrDyldEnumResources(HKLDRMOD hMod, KU32 idType, const char *pszType, KU32 idName,
816	const char pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void pvUser);
817
818
819	/** @name OS/2 like API
820	* @{ */
821	#if defined(__OS2__)
822	# define KLDROS2API _System
823	#else
824	# define KLDROS2API
825	#endif
826	int kLdrDosLoadModule(char pszObject, KSIZE cbObject, const char pszModule, PHKLDRMOD phMod);
827	int kLdrDosFreeModule(HKLDRMOD hMod);
828	int kLdrDosQueryModuleHandle(const char *pszModname, PHKLDRMOD phMod);
829	int kLdrDosQueryModuleName(HKLDRMOD hMod, KSIZE cchName, char *pszName);
830	int kLdrDosQueryProcAddr(HKLDRMOD hMod, KU32 iOrdinal, const char pszProcName, void *ppvProcAddr);
831	int kLdrDosQueryProcType(HKLDRMOD hMod, KU32 iOrdinal, const char pszProcName, KU32 pfProcType);
832	int kLdrDosQueryModFromEIP(PHKLDRMOD phMod, KU32 piObject, KSIZE cbName, char pszName, KUPTR *poffObject, KUPTR ulEIP);
833	int kLdrDosReplaceModule(const char pszOldModule, const char pszNewModule, const char *pszBackupModule);
834	int kLdrDosGetResource(HKLDRMOD hMod, KU32 idType, KU32 idName, void **pvResAddr);
835	int kLdrDosQueryResourceSize(HKLDRMOD hMod, KU32 idType, KU32 idName, KU32 *pcb);
836	int kLdrDosFreeResource(void *pvResAddr);
837	/** @} */
838
839	/** @name POSIX like API
840	* @{ */
841	HKLDRMOD kLdrDlOpen(const char *pszLibrary, int fFlags);
842	const char *kLdrDlError(void);
843	void * kLdrDlSym(HKLDRMOD hMod, const char *pszSymbol);
844	int kLdrDlClose(HKLDRMOD hMod);
845	/** @todo GNU extensions */
846	/** @} */
847
848	/** @name Win32 like API
849	* @{ */
850	#if defined(_MSC_VER)
851	# define KLDRWINAPI __stdcall
852	#else
853	# define KLDRWINAPI
854	#endif
855	HKLDRMOD KLDRWINAPI kLdrWLoadLibrary(const char *pszFilename);
856	HKLDRMOD KLDRWINAPI kLdrWLoadLibraryEx(const char pszFilename, void hFileReserved, KU32 fFlags);
857	KU32 KLDRWINAPI kLdrWGetModuleFileName(HKLDRMOD hMod, char *pszModName, KSIZE cchModName);
858	HKLDRMOD KLDRWINAPI kLdrWGetModuleHandle(const char *pszFilename);
859	int KLDRWINAPI kLdrWGetModuleHandleEx(KU32 fFlags, const char *pszFilename, HKLDRMOD hMod);
860	void * KLDRWINAPI kLdrWGetProcAddress(HKLDRMOD hMod, const char *pszProcName);
861	KU32 KLDRWINAPI kLdrWGetDllDirectory(KSIZE cchDir, char *pszDir);
862	int KLDRWINAPI kLdrWSetDllDirectory(const char *pszDir);
863	int KLDRWINAPI kLdrWFreeLibrary(HKLDRMOD hMod);
864	int KLDRWINAPI kLdrWDisableThreadLibraryCalls(HKLDRMOD hMod);
865
866	/** The handle to a resource that's been found. */
867	typedef struct KLDRWRSRCFOUND *HKLDRWRSRCFOUND;
868	/** The handle to a loaded resource. */
869	typedef struct KLDRWRSRCLOADED *HKLDRWRSRCLOADED;
870	HKLDRWRSRCFOUND KLDRWINAPI kLdrWFindResource(HKLDRMOD hMod, const char pszType, const char pszName);
871	HKLDRWRSRCFOUND KLDRWINAPI kLdrWFindResourceEx(HKLDRMOD hMod, const char pszType, const char pszName, KU16 idLang);
872	KU32 KLDRWINAPI kLdrWSizeofResource(HKLDRMOD hMod, HKLDRWRSRCFOUND hFoundRsrc);
873	HKLDRWRSRCLOADED KLDRWINAPI kLdrWLoadResource(HKLDRMOD hMod, HKLDRWRSRCFOUND hFoundRsrc);
874	void *KLDRWINAPI kLdrWLockResource(HKLDRMOD hMod, HKLDRWRSRCLOADED hLoadedRsrc);
875	int KLDRWINAPI kLdrWFreeResource(HKLDRMOD hMod, HKLDRWRSRCLOADED hLoadedRsrc);
876
877	typedef int (KLDRWINAPI PFNKLDRWENUMRESTYPE)(HKLDRMOD hMod, const char pszType, KUPTR uUser);
878	int KLDRWINAPI kLdrWEnumResourceTypes(HKLDRMOD hMod, PFNKLDRWENUMRESTYPE pfnEnum, KUPTR uUser);
879	int KLDRWINAPI kLdrWEnumResourceTypesEx(HKLDRMOD hMod, PFNKLDRWENUMRESTYPE pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
880
881	typedef int (KLDRWINAPI PFNKLDRWENUMRESNAME)(HKLDRMOD hMod, const char pszType, char *pszName, KUPTR uUser);
882	int KLDRWINAPI kLdrWEnumResourceNames(HKLDRMOD hMod, const char *pszType, PFNKLDRWENUMRESNAME pfnEnum, KUPTR uUser);
883	int KLDRWINAPI kLdrWEnumResourceNamesEx(HKLDRMOD hMod, const char *pszType, PFNKLDRWENUMRESNAME pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
884
885	typedef int (KLDRWINAPI PFNKLDRWENUMRESLANG)(HKLDRMOD hMod, const char pszType, const char *pszName, KU16 idLang, KUPTR uUser);
886	int KLDRWINAPI kLdrWEnumResourceLanguages(HKLDRMOD hMod, const char pszType, const char pszName, PFNKLDRWENUMRESLANG pfnEnum, KUPTR uUser);
887	int KLDRWINAPI kLdrWEnumResourceLanguagesEx(HKLDRMOD hMod, const char pszType, const char pszName,
888	PFNKLDRWENUMRESLANG pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
889	/** @} */
890
891
892	/** @name Process Bootstrapping
893	* @{ */
894
895	/**
896	* Argument package from the stub.
897	*/
898	typedef struct KLDREXEARGS
899	{
900	/** Load & search flags, some which will become defaults. */
901	KU32 fFlags;
902	/** The default search method. */
903	KLDRDYLDSEARCH enmSearch;
904	/** The executable file that the stub is supposed to load. */
905	char szExecutable[260];
906	/** The default prefix used when searching for DLLs. */
907	char szDefPrefix[16];
908	/** The default suffix used when searching for DLLs. */
909	char szDefSuffix[16];
910	/** The LD_LIBRARY_PATH prefix for the process.. */
911	char szLibPath[4096 - sizeof(KU32) - sizeof(KLDRDYLDSEARCH) - 16 - 16 - 260];
912	} KLDREXEARGS, *PKLDREXEARGS;
913	/** Pointer to a const argument package from the stub. */
914	typedef const KLDREXEARGS *PCKLDREXEARGS;
915
916	void kLdrLoadExe(PCKLDREXEARGS pArgs, void pvOS); /* @todo fix this mess... */
917	void kLdrDyldLoadExe(PCKLDREXEARGS pArgs, void *pvOS);
918	/** @} */
919
920	/** @} */
921
922	/** @} */
923
924	#ifdef __cplusplus
925	}
926	#endif
927
928	#endif
929

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

source: kStuff/trunk/include/k/kLdr.h@ 41

Download in other formats: