kLdr.h@ 13

Last change on this file since 13 was 2, checked in by bird, 17 years ago
Imported http://svn.netlabs.org/repos/libc/trunk/kStuff, revision 3612.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 37.3 KB

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

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

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

Download in other formats: