source: trunk/include/k/kLdr.h@ 37

Last change on this file since 37 was 29, checked in by bird, 16 years ago

Finally got around execute the switch to the MIT license.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 38.0 KB
Line 
1/* $Id: kLdr.h 29 2009-07-01 20:30:29Z 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
35extern "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. */
50typedef KU64 KLDRADDR;
51/** Pointer to a kLdr address. */
52typedef KLDRADDR *PKLDRADDR;
53/** Pointer to a const kLdr address. */
54typedef 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. */
72typedef KU64 KLDRSIZE;
73/** Pointer to a kLdr size. */
74typedef KLDRSIZE *PKLDRSIZE;
75/** Pointer to a const kLdr size. */
76typedef 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. */
88typedef long KLDRFOFF;
89/** Pointer to a kLdr file offset type. */
90typedef KLDRFOFF *PKLDRFOFF;
91/** Pointer to a const kLdr file offset type. */
92typedef 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 */
102typedef 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. */
134typedef KLDRU *PKLDRU;
135/** Pointer to a const integer union. */
136typedef const KLDRU *PCKLDRU;
137
138
139/**
140 * Union of pointers to all the integer types.
141 */
142typedef 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. */
164typedef KLDRPU *PKLDRPU;
165/** Pointer to a const integer pointer union. */
166typedef 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 */
177typedef 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. */
199typedef KLDRDBGINFOTYPE *PKLDRDBGINFOTYPE;
200
201
202/**
203 * Stack information.
204 */
205typedef 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. */
222typedef KLDRSTACKINFO *PKLDRSTACKINFO;
223/** Pointer to const stack information. */
224typedef const KLDRSTACKINFO *PCKLDRSTACKINFO;
225
226
227/**
228 * Loader segment.
229 */
230typedef 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 */
290typedef 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 */
316typedef 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 /** The end of the valid types values (exclusive). */
340 KLDRTYPE_END,
341 /** Hack to blow the type up to 32-bit. */
342 KLDRTYPE_32BIT_HACK = 0x7fffffff
343} KLDRTYPE;
344
345
346/**
347 * Loader endian indicator.
348 */
349typedef enum KLDRENDIAN
350{
351 /** The usual invalid endian. */
352 KLDRENDIAN_INVALID,
353 /** Little endian. */
354 KLDRENDIAN_LITTLE,
355 /** Bit endian. */
356 KLDRENDIAN_BIG,
357 /** Endianness doesn't have a meaning in the context. */
358 KLDRENDIAN_NA,
359 /** The end of the valid endian values (exclusive). */
360 KLDRENDIAN_END,
361 /** Hack to blow the type up to 32-bit. */
362 KLDRENDIAN_32BIT_HACK = 0x7fffffff
363} KLDRENDIAN;
364
365
366/** Pointer to a module interpreter method table. */
367typedef struct KLDRMODOPS *PKLDRMODOPS;
368/** Pointer to const module interpreter methods table. */
369typedef const struct KLDRMODOPS *PCKLDRMODOPS;
370
371/**
372 * Module interpreter instance.
373 * All members are read only unless you're kLdrMod or the module interpreter.
374 */
375typedef struct KLDRMOD
376{
377 /** Magic number (KLDRMOD_MAGIC). */
378 KU32 u32Magic;
379 /** The format of this module. */
380 KLDRFMT enmFmt;
381 /** The type of module. */
382 KLDRTYPE enmType;
383 /** The CPU architecture this module was built for. */
384 KCPUARCH enmArch;
385 /** The minium cpu this module was built for.
386 * This might not be accurate, so use kLdrModCanExecuteOn() to check. */
387 KCPU enmCpu;
388 /** The endian used by the module. */
389 KLDRENDIAN enmEndian;
390 /** The filename length (bytes). */
391 KU32 cchFilename;
392 /** The filename. */
393 const char *pszFilename;
394 /** The module name. */
395 const char *pszName;
396 /** The module name length (bytes). */
397 KU32 cchName;
398 /** The number of segments in the module. */
399 KU32 cSegments;
400 /** Pointer to the loader methods.
401 * Not meant for calling directly thru! */
402 PCKLDRMODOPS pOps;
403 /** Pointer to the read instance. (Can be NULL after kLdrModDone().)*/
404 PKRDR pRdr;
405 /** The module data. */
406 void *pvData;
407 /** Segments. (variable size, can be zero) */
408 KLDRSEG aSegments[1];
409} KLDRMOD, *PKLDRMOD, **PPKLDRMOD;
410
411/** The magic for KLDRMOD::u32Magic. (Kosuke Fujishima) */
412#define KLDRMOD_MAGIC 0x19640707
413
414
415/** Special base address value alias for the link address. */
416#define KLDRMOD_BASEADDRESS_LINK (~(KLDRADDR)1)
417/** Special base address value alias for the actual load address (must be mapped). */
418#define KLDRMOD_BASEADDRESS_MAP (~(KLDRADDR)2)
419
420/** Special import module ordinal value used to indicate that there is no
421 * specific module associated with the requested symbol. */
422#define NIL_KLDRMOD_IMPORT (~(KU32)0)
423
424/** Special symbol ordinal value used to indicate that the symbol
425 * only has a string name. */
426#define NIL_KLDRMOD_SYM_ORDINAL (~(KU32)0)
427
428
429/** @name Load symbol kind flags.
430 * @{ */
431/** The bitness doesn't matter. */
432#define KLDRSYMKIND_NO_BIT 0x00000000
433/** 16-bit symbol. */
434#define KLDRSYMKIND_16BIT 0x00000001
435/** 32-bit symbol. */
436#define KLDRSYMKIND_32BIT 0x00000002
437/** 64-bit symbol. */
438#define KLDRSYMKIND_64BIT 0x00000003
439/** Mask out the bit.*/
440#define KLDRSYMKIND_BIT_MASK 0x00000003
441/** We don't know the type of symbol. */
442#define KLDRSYMKIND_NO_TYPE 0x00000000
443/** The symbol is a code object (method/function/procedure/whateveryouwannacallit). */
444#define KLDRSYMKIND_CODE 0x00000010
445/** The symbol is a data object. */
446#define KLDRSYMKIND_DATA 0x00000020
447/** Mask out the symbol type. */
448#define KLDRSYMKIND_TYPE_MASK 0x00000030
449/** Valid symbol kind mask. */
450#define KLDRSYMKIND_MASK 0x00000033
451/** Weak symbol. */
452#define KLDRSYMKIND_WEAK 0x00000100
453/** Forwarder symbol. */
454#define KLDRSYMKIND_FORWARDER 0x00000200
455/** Request a flat symbol address. */
456#define KLDRSYMKIND_REQ_FLAT 0x00000000
457/** Request a segmented symbol address. */
458#define KLDRSYMKIND_REQ_SEGMENTED 0x40000000
459/** Request type mask. */
460#define KLDRSYMKIND_REQ_TYPE_MASK 0x40000000
461/** @} */
462
463/** @name kLdrModEnumSymbols flags.
464 * @{ */
465/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
466#define KLDRMOD_ENUM_SYMS_FLAGS_ALL 0x00000001
467/** @} */
468
469
470/**
471 * Callback for resolving imported symbols when applying fixups.
472 *
473 * @returns 0 on success and *pValue and *pfKind filled.
474 * @returns Non-zero OS specific or kLdr status code on failure.
475 *
476 * @param pMod The module which fixups are begin applied.
477 * @param iImport The import module ordinal number or NIL_KLDRMOD_IMPORT.
478 * @param iSymbol The symbol ordinal number or NIL_KLDRMOD_SYM_ORDINAL.
479 * @param pchSymbol The symbol name. Can be NULL if iSymbol isn't nil. Doesn't have to be null-terminated.
480 * @param cchSymbol The length of the symbol.
481 * @param pszVersion The symbol version. NULL if not versioned.
482 * @param puValue Where to store the symbol value.
483 * @param pfKind Where to store the symbol kind flags.
484 * @param pvUser The user parameter specified to the relocation function.
485 */
486typedef int FNKLDRMODGETIMPORT(PKLDRMOD pMod, KU32 iImport, KU32 iSymbol, const char *pchSymbol, KSIZE cchSymbol,
487 const char *pszVersion, PKLDRADDR puValue, KU32 *pfKind, void *pvUser);
488/** Pointer to a import callback. */
489typedef FNKLDRMODGETIMPORT *PFNKLDRMODGETIMPORT;
490
491/**
492 * Symbol enumerator callback.
493 *
494 * @returns 0 if enumeration should continue.
495 * @returns non-zero if the enumeration should stop. This status code will then be returned by kLdrModEnumSymbols().
496 *
497 * @param pMod The module which symbols are being enumerated.s
498 * @param iSymbol The symbol ordinal number or NIL_KLDRMOD_SYM_ORDINAL.
499 * @param pchSymbol The symbol name. This can be NULL if there is a symbol ordinal.
500 * This can also be an empty string if the symbol doesn't have a name
501 * or it's name has been stripped.
502 * Important, this doesn't have to be a null-terminated string.
503 * @param cchSymbol The length of the symbol.
504 * @param pszVersion The symbol version. NULL if not versioned.
505 * @param uValue The symbol value.
506 * @param fKind The symbol kind flags.
507 * @param pvUser The user parameter specified to kLdrModEnumSymbols().
508 */
509typedef int FNKLDRMODENUMSYMS(PKLDRMOD pMod, KU32 iSymbol, const char *pchSymbol, KSIZE cchSymbol, const char *pszVersion,
510 KLDRADDR uValue, KU32 fKind, void *pvUser);
511/** Pointer to a symbol enumerator callback. */
512typedef FNKLDRMODENUMSYMS *PFNKLDRMODENUMSYMS;
513
514/**
515 * Debug info enumerator callback.
516 *
517 * @returns 0 to continue the enumeration.
518 * @returns non-zero if the enumeration should stop. This status code will then be returned by kLdrModEnumDbgInfo().
519 *
520 * @param pMod The module.
521 * @param iDbgInfo The debug info ordinal number / id.
522 * @param enmType The debug info type.
523 * @param iMajorVer The major version number of the debug info format. -1 if unknow - implies invalid iMinorVer.
524 * @param iMinorVer The minor version number of the debug info format. -1 when iMajorVer is -1.
525 * @param offFile The file offset *if* this type has one specific location in the executable image file.
526 * This is -1 if there isn't any specific file location.
527 * @param LinkAddress The link address of the debug info if it's loadable. NIL_KLDRADDR if not loadable.
528 * @param cb The size of the debug information. -1 is used if this isn't applicable.
529 * @param pszExtFile This points to the name of an external file containing the debug info.
530 * This is NULL if there isn't any external file.
531 * @param pvUser The user parameter specified to kLdrModEnumDbgInfo.
532 */
533typedef int FNKLDRENUMDBG(PKLDRMOD pMod, KU32 iDbgInfo, KLDRDBGINFOTYPE enmType, KI16 iMajorVer, KI16 iMinorVer,
534 KLDRFOFF offFile, KLDRADDR LinkAddress, KLDRSIZE cb, const char *pszExtFile, void *pvUser);
535/** Pointer to a debug info enumerator callback. */
536typedef FNKLDRENUMDBG *PFNKLDRENUMDBG;
537
538/**
539 * Resource enumerator callback.
540 *
541 * @returns 0 to continue the enumeration.
542 * @returns non-zero if the enumeration should stop. This status code will then be returned by kLdrModEnumResources().
543 *
544 * @param pMod The module.
545 * @param idType The resource type id. NIL_KLDRMOD_RSRC_TYPE_ID if no type id.
546 * @param pszType The resource type name. NULL if no type name.
547 * @param idName The resource id. NIL_KLDRMOD_RSRC_NAME_ID if no id.
548 * @param pszName The resource name. NULL if no name.
549 * @param idLang The language id.
550 * @param AddrRsrc The address value for the resource.
551 * @param cbRsrc The size of the resource.
552 * @param pvUser The user parameter specified to kLdrModEnumDbgInfo.
553 */
554typedef int FNKLDRENUMRSRC(PKLDRMOD pMod, KU32 idType, const char *pszType, KU32 idName, const char *pszName,
555 KU32 idLang, KLDRADDR AddrRsrc, KLDRSIZE cbRsrc, void *pvUser);
556/** Pointer to a resource enumerator callback. */
557typedef FNKLDRENUMRSRC *PFNKLDRENUMRSRC;
558
559/** NIL resource name ID. */
560#define NIL_KLDRMOD_RSRC_NAME_ID ( ~(KU32)0 )
561/** NIL resource type ID. */
562#define NIL_KLDRMOD_RSRC_TYPE_ID ( ~(KU32)0 )
563/** @name Language ID
564 *
565 * Except for the special IDs #defined here, the values are considered
566 * format specific for now since it's only used by the PE resources.
567 *
568 * @{ */
569/** NIL language ID. */
570#define NIL_KLDR_LANG_ID ( ~(KU32)0 )
571/** Special language id value for matching any language. */
572#define KLDR_LANG_ID_ANY ( ~(KU32)1 )
573/** Special language id value indicating language neutral. */
574#define KLDR_LANG_ID_NEUTRAL ( ~(KU32)2 )
575/** Special language id value indicating user default language. */
576#define KLDR_LANG_ID_USER_DEFAULT ( ~(KU32)3 )
577/** Special language id value indicating system default language. */
578#define KLDR_LANG_ID_SYS_DEFAULT ( ~(KU32)4 )
579/** Special language id value indicating default custom locale. */
580#define KLDR_LANG_ID_CUSTOM_DEFAULT ( ~(KU32)5 )
581/** Special language id value indicating unspecified custom locale. */
582#define KLDR_LANG_ID_CUSTOM_UNSPECIFIED ( ~(KU32)6 )
583/** Special language id value indicating default custom MUI locale. */
584#define KLDR_LANG_ID_UI_CUSTOM_DEFAULT ( ~(KU32)7 )
585/** @} */
586
587
588int kLdrModOpen(const char *pszFilename, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod);
589int kLdrModOpenFromRdr(PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod);
590int kLdrModOpenNative(const char *pszFilename, PPKLDRMOD ppMod);
591int kLdrModOpenNativeByHandle(KUPTR uHandle, PPKLDRMOD ppMod);
592int kLdrModClose(PKLDRMOD pMod);
593
594int kLdrModQuerySymbol(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
595 const char *pchSymbol, KSIZE cchSymbol, const char *pszVersion,
596 PFNKLDRMODGETIMPORT pfnGetForwarder, void *pvUser, PKLDRADDR puValue, KU32 *pfKind);
597int kLdrModEnumSymbols(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress,
598 KU32 fFlags, PFNKLDRMODENUMSYMS pfnCallback, void *pvUser);
599int kLdrModGetImport(PKLDRMOD pMod, const void *pvBits, KU32 iImport, char *pszName, KSIZE cchName);
600KI32 kLdrModNumberOfImports(PKLDRMOD pMod, const void *pvBits);
601int kLdrModCanExecuteOn(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu);
602int kLdrModGetStackInfo(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo);
603int kLdrModQueryMainEntrypoint(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress);
604int kLdrModQueryResource(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 idType, const char *pszType,
605 KU32 idName, const char *pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE *pcbRsrc);
606int kLdrModEnumResources(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 idType, const char *pszType,
607 KU32 idName, const char *pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void *pvUser);
608int kLdrModEnumDbgInfo(PKLDRMOD pMod, const void *pvBits, PFNKLDRENUMDBG pfnCallback, void *pvUser);
609int kLdrModHasDbgInfo(PKLDRMOD pMod, const void *pvBits);
610int kLdrModMostlyDone(PKLDRMOD pMod);
611
612
613/** @name Operations On The Internally Managed Mapping
614 * @{ */
615int kLdrModMap(PKLDRMOD pMod);
616int kLdrModUnmap(PKLDRMOD pMod);
617int kLdrModAllocTLS(PKLDRMOD pMod);
618void kLdrModFreeTLS(PKLDRMOD pMod);
619int kLdrModReload(PKLDRMOD pMod);
620int kLdrModFixupMapping(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
621int kLdrModCallInit(PKLDRMOD pMod, KUPTR uHandle);
622int kLdrModCallTerm(PKLDRMOD pMod, KUPTR uHandle);
623int kLdrModCallThread(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching);
624/** @} */
625
626/** @name Operations On The Externally Managed Mappings
627 * @{ */
628KLDRADDR kLdrModSize(PKLDRMOD pMod);
629int kLdrModGetBits(PKLDRMOD pMod, void *pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
630int kLdrModRelocateBits(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
631 PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
632/** @} */
633
634
635/**
636 * The loader module operation.
637 */
638typedef struct KLDRMODOPS
639{
640 /** The name of this module interpreter. */
641 const char *pszName;
642 /** Pointer to the next module interpreter. */
643 PCKLDRMODOPS pNext;
644
645 /**
646 * Create a loader module instance interpreting the executable image found
647 * in the specified file provider instance.
648 *
649 * @returns 0 on success and *ppMod pointing to a module instance.
650 * On failure, a non-zero OS specific error code is returned.
651 * @param pOps Pointer to the registered method table.
652 * @param pRdr The file provider instance to use.
653 * @param fFlags Flags, MBZ.
654 * @param enmCpuArch The desired CPU architecture. KCPUARCH_UNKNOWN means
655 * anything goes, but with a preference for the current
656 * host architecture.
657 * @param offNewHdr The offset of the new header in MZ files. -1 if not found.
658 * @param ppMod Where to store the module instance pointer.
659 */
660 int (* pfnCreate)(PCKLDRMODOPS pOps, PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, KLDRFOFF offNewHdr, PPKLDRMOD ppMod);
661 /**
662 * Destroys an loader module instance.
663 *
664 * The caller is responsible for calling kLdrModUnmap() and kLdrFreeTLS() first.
665 *
666 * @returns 0 on success, non-zero on failure. The module instance state
667 * is unknown on failure, it's best not to touch it.
668 * @param pMod The module.
669 */
670 int (* pfnDestroy)(PKLDRMOD pMod);
671
672 /** @copydoc kLdrModQuerySymbol */
673 int (* pfnQuerySymbol)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
674 const char *pchSymbol, KSIZE cchSymbol, const char *pszVersion,
675 PFNKLDRMODGETIMPORT pfnGetForwarder, void *pvUser, PKLDRADDR puValue, KU32 *pfKind);
676 /** @copydoc kLdrModEnumSymbols */
677 int (* pfnEnumSymbols)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 fFlags,
678 PFNKLDRMODENUMSYMS pfnCallback, void *pvUser);
679 /** @copydoc kLdrModGetImport */
680 int (* pfnGetImport)(PKLDRMOD pMod, const void *pvBits, KU32 iImport, char *pszName, KSIZE cchName);
681 /** @copydoc kLdrModNumberOfImports */
682 KI32 (* pfnNumberOfImports)(PKLDRMOD pMod, const void *pvBits);
683 /** @copydoc kLdrModCanExecuteOn */
684 int (* pfnCanExecuteOn)(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu);
685 /** @copydoc kLdrModGetStackInfo */
686 int (* pfnGetStackInfo)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo);
687 /** @copydoc kLdrModQueryMainEntrypoint */
688 int (* pfnQueryMainEntrypoint)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress);
689 /** @copydoc kLdrModQueryResource */
690 int (* pfnQueryResource)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 idType, const char *pszType,
691 KU32 idName, const char *pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE *pcbRsrc);
692 /** @copydoc kLdrModEnumResources */
693 int (* pfnEnumResources)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 idType, const char *pszType,
694 KU32 idName, const char *pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void *pvUser);
695 /** @copydoc kLdrModEnumDbgInfo */
696 int (* pfnEnumDbgInfo)(PKLDRMOD pMod, const void *pvBits, PFNKLDRENUMDBG pfnCallback, void *pvUser);
697 /** @copydoc kLdrModHasDbgInfo */
698 int (* pfnHasDbgInfo)(PKLDRMOD pMod, const void *pvBits);
699 /** @copydoc kLdrModMap */
700 int (* pfnMap)(PKLDRMOD pMod);
701 /** @copydoc kLdrModUnmap */
702 int (* pfnUnmap)(PKLDRMOD pMod);
703 /** @copydoc kLdrModAllocTLS */
704 int (* pfnAllocTLS)(PKLDRMOD pMod);
705 /** @copydoc kLdrModFreeTLS */
706 void (*pfnFreeTLS)(PKLDRMOD pMod);
707 /** @copydoc kLdrModReload */
708 int (* pfnReload)(PKLDRMOD pMod);
709 /** @copydoc kLdrModFixupMapping */
710 int (* pfnFixupMapping)(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
711 /** @copydoc kLdrModCallInit */
712 int (* pfnCallInit)(PKLDRMOD pMod, KUPTR uHandle);
713 /** @copydoc kLdrModCallTerm */
714 int (* pfnCallTerm)(PKLDRMOD pMod, KUPTR uHandle);
715 /** @copydoc kLdrModCallThread */
716 int (* pfnCallThread)(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching);
717 /** @copydoc kLdrModSize */
718 KLDRADDR (* pfnSize)(PKLDRMOD pMod);
719 /** @copydoc kLdrModGetBits */
720 int (* pfnGetBits)(PKLDRMOD pMod, void *pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
721 /** @copydoc kLdrModRelocateBits */
722 int (* pfnRelocateBits)(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
723 PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
724 /** @copydoc kLdrModMostlyDone */
725 int (* pfnMostlyDone)(PKLDRMOD pMod);
726 /** Dummy which should be assigned a non-zero value. */
727 KU32 uEndOfStructure;
728} KLDRMODOPS;
729
730
731/** @} */
732
733
734
735
736/** @defgroup grp_kLdrDyld kLdrDyld - The dynamic loader
737 * @{ */
738
739/** The handle to a dynamic loader module. */
740typedef struct KLDRDYLDMOD *HKLDRMOD;
741/** Pointer to the handle to a dynamic loader module. */
742typedef HKLDRMOD *PHKLDRMOD;
743/** NIL handle value. */
744#define NIL_HKLDRMOD ((HKLDRMOD)0)
745
746
747/**
748 * File search method.
749 *
750 * In addition to it's own way of finding files, kLdr emulates
751 * the methods employed by the most popular systems.
752 */
753typedef enum KLDRDYLDSEARCH
754{
755 /** The usual invalid file search method. */
756 KLDRDYLD_SEARCH_INVALID = 0,
757 /** Uses the kLdr file search method.
758 * @todo invent me. */
759 KLDRDYLD_SEARCH_KLDR,
760 /** Use the emulation closest to the host system. */
761 KLDRDYLD_SEARCH_HOST,
762 /** Emulate the OS/2 file search method.
763 * On non-OS/2 systems, BEGINLIBPATH, LIBPATH, ENDLIBPATH and LIBPATHSTRICT are
764 * taken form the environment. */
765 KLDRDYLD_SEARCH_OS2,
766 /** Emulate the standard window file search method. */
767 KLDRDYLD_SEARCH_WINDOWS,
768 /** Emulate the alternative window file search method. */
769 KLDRDYLD_SEARCH_WINDOWS_ALTERED,
770 /** Emulate the most common UNIX file search method. */
771 KLDRDYLD_SEARCH_UNIX_COMMON,
772 /** End of the valid file search method values. */
773 KLDRDYLD_SEARCH_END,
774 /** Hack to blow the type up to 32-bit. */
775 KLDRDYLD_SEARCH_32BIT_HACK = 0x7fffffff
776} KLDRDYLDSEARCH;
777
778/** @name kLdrDyldLoad and kLdrDyldFindByName flags.
779 * @{ */
780/** The symbols in the module should be loaded into the global unix namespace.
781 * If not specified, the symbols are local and can only be referenced directly. */
782#define KLDRYDLD_LOAD_FLAGS_GLOBAL_SYMBOLS 0x00000001
783/** The symbols in the module should be loaded into the global unix namespace and
784 * it's symbols should take precedence over all currently loaded modules.
785 * This implies KLDRYDLD_LOAD_FLAGS_GLOBAL_SYMBOLS. */
786#define KLDRYDLD_LOAD_FLAGS_DEEP_SYMBOLS 0x00000002
787/** The module shouldn't be found by a global module search.
788 * If not specified, the module can be found by unspecified module searches,
789 * typical used when loading import/dep modules. */
790#define KLDRYDLD_LOAD_FLAGS_SPECIFIC_MODULE 0x00000004
791/** Do a recursive initialization calls instead of defering them to the outermost call. */
792#define KLDRDYLD_LOAD_FLAGS_RECURSIVE_INIT 0x00000008
793/** We're loading the executable module.
794 * @internal */
795#define KLDRDYLD_LOAD_FLAGS_EXECUTABLE 0x40000000
796/** @} */
797
798
799int kLdrDyldLoad(const char *pszDll, const char *pszPrefix, const char *pszSuffix, KLDRDYLDSEARCH enmSearch,
800 unsigned fFlags, PHKLDRMOD phMod, char *pszErr, KSIZE cchErr);
801int kLdrDyldUnload(HKLDRMOD hMod);
802int kLdrDyldFindByName(const char *pszDll, const char *pszPrefix, const char *pszSuffix, KLDRDYLDSEARCH enmSearch,
803 unsigned fFlags, PHKLDRMOD phMod);
804int kLdrDyldFindByAddress(KUPTR Address, PHKLDRMOD phMod, KU32 *piSegment, KUPTR *poffSegment);
805int kLdrDyldGetName(HKLDRMOD hMod, char *pszName, KSIZE cchName);
806int kLdrDyldGetFilename(HKLDRMOD hMod, char *pszFilename, KSIZE cchFilename);
807int kLdrDyldQuerySymbol(HKLDRMOD hMod, KU32 uSymbolOrdinal, const char *pszSymbolName,
808 const char *pszSymbolVersion, KUPTR *pValue, KU32 *pfKind);
809int kLdrDyldQueryResource(HKLDRMOD hMod, KU32 idType, const char *pszType, KU32 idName,
810 const char *pszName, KU32 idLang, void **pvRsrc, KSIZE *pcbRsrc);
811int kLdrDyldEnumResources(HKLDRMOD hMod, KU32 idType, const char *pszType, KU32 idName,
812 const char *pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void *pvUser);
813
814
815/** @name OS/2 like API
816 * @{ */
817#if defined(__OS2__)
818# define KLDROS2API _System
819#else
820# define KLDROS2API
821#endif
822int kLdrDosLoadModule(char *pszObject, KSIZE cbObject, const char *pszModule, PHKLDRMOD phMod);
823int kLdrDosFreeModule(HKLDRMOD hMod);
824int kLdrDosQueryModuleHandle(const char *pszModname, PHKLDRMOD phMod);
825int kLdrDosQueryModuleName(HKLDRMOD hMod, KSIZE cchName, char *pszName);
826int kLdrDosQueryProcAddr(HKLDRMOD hMod, KU32 iOrdinal, const char *pszProcName, void **ppvProcAddr);
827int kLdrDosQueryProcType(HKLDRMOD hMod, KU32 iOrdinal, const char *pszProcName, KU32 *pfProcType);
828int kLdrDosQueryModFromEIP(PHKLDRMOD phMod, KU32 *piObject, KSIZE cbName, char *pszName, KUPTR *poffObject, KUPTR ulEIP);
829int kLdrDosReplaceModule(const char *pszOldModule, const char *pszNewModule, const char *pszBackupModule);
830int kLdrDosGetResource(HKLDRMOD hMod, KU32 idType, KU32 idName, void **pvResAddr);
831int kLdrDosQueryResourceSize(HKLDRMOD hMod, KU32 idType, KU32 idName, KU32 *pcb);
832int kLdrDosFreeResource(void *pvResAddr);
833/** @} */
834
835/** @name POSIX like API
836 * @{ */
837HKLDRMOD kLdrDlOpen(const char *pszLibrary, int fFlags);
838const char *kLdrDlError(void);
839void * kLdrDlSym(HKLDRMOD hMod, const char *pszSymbol);
840int kLdrDlClose(HKLDRMOD hMod);
841/** @todo GNU extensions */
842/** @} */
843
844/** @name Win32 like API
845 * @{ */
846#if defined(_MSC_VER)
847# define KLDRWINAPI __stdcall
848#else
849# define KLDRWINAPI
850#endif
851HKLDRMOD KLDRWINAPI kLdrWLoadLibrary(const char *pszFilename);
852HKLDRMOD KLDRWINAPI kLdrWLoadLibraryEx(const char *pszFilename, void *hFileReserved, KU32 fFlags);
853KU32 KLDRWINAPI kLdrWGetModuleFileName(HKLDRMOD hMod, char *pszModName, KSIZE cchModName);
854HKLDRMOD KLDRWINAPI kLdrWGetModuleHandle(const char *pszFilename);
855int KLDRWINAPI kLdrWGetModuleHandleEx(KU32 fFlags, const char *pszFilename, HKLDRMOD hMod);
856void * KLDRWINAPI kLdrWGetProcAddress(HKLDRMOD hMod, const char *pszProcName);
857KU32 KLDRWINAPI kLdrWGetDllDirectory(KSIZE cchDir, char *pszDir);
858int KLDRWINAPI kLdrWSetDllDirectory(const char *pszDir);
859int KLDRWINAPI kLdrWFreeLibrary(HKLDRMOD hMod);
860int KLDRWINAPI kLdrWDisableThreadLibraryCalls(HKLDRMOD hMod);
861
862/** The handle to a resource that's been found. */
863typedef struct KLDRWRSRCFOUND *HKLDRWRSRCFOUND;
864/** The handle to a loaded resource. */
865typedef struct KLDRWRSRCLOADED *HKLDRWRSRCLOADED;
866HKLDRWRSRCFOUND KLDRWINAPI kLdrWFindResource(HKLDRMOD hMod, const char *pszType, const char *pszName);
867HKLDRWRSRCFOUND KLDRWINAPI kLdrWFindResourceEx(HKLDRMOD hMod, const char *pszType, const char *pszName, KU16 idLang);
868KU32 KLDRWINAPI kLdrWSizeofResource(HKLDRMOD hMod, HKLDRWRSRCFOUND hFoundRsrc);
869HKLDRWRSRCLOADED KLDRWINAPI kLdrWLoadResource(HKLDRMOD hMod, HKLDRWRSRCFOUND hFoundRsrc);
870void *KLDRWINAPI kLdrWLockResource(HKLDRMOD hMod, HKLDRWRSRCLOADED hLoadedRsrc);
871int KLDRWINAPI kLdrWFreeResource(HKLDRMOD hMod, HKLDRWRSRCLOADED hLoadedRsrc);
872
873typedef int (KLDRWINAPI *PFNKLDRWENUMRESTYPE)(HKLDRMOD hMod, const char *pszType, KUPTR uUser);
874int KLDRWINAPI kLdrWEnumResourceTypes(HKLDRMOD hMod, PFNKLDRWENUMRESTYPE pfnEnum, KUPTR uUser);
875int KLDRWINAPI kLdrWEnumResourceTypesEx(HKLDRMOD hMod, PFNKLDRWENUMRESTYPE pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
876
877typedef int (KLDRWINAPI *PFNKLDRWENUMRESNAME)(HKLDRMOD hMod, const char *pszType, char *pszName, KUPTR uUser);
878int KLDRWINAPI kLdrWEnumResourceNames(HKLDRMOD hMod, const char *pszType, PFNKLDRWENUMRESNAME pfnEnum, KUPTR uUser);
879int KLDRWINAPI kLdrWEnumResourceNamesEx(HKLDRMOD hMod, const char *pszType, PFNKLDRWENUMRESNAME pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
880
881typedef int (KLDRWINAPI *PFNKLDRWENUMRESLANG)(HKLDRMOD hMod, const char *pszType, const char *pszName, KU16 idLang, KUPTR uUser);
882int KLDRWINAPI kLdrWEnumResourceLanguages(HKLDRMOD hMod, const char *pszType, const char *pszName, PFNKLDRWENUMRESLANG pfnEnum, KUPTR uUser);
883int KLDRWINAPI kLdrWEnumResourceLanguagesEx(HKLDRMOD hMod, const char *pszType, const char *pszName,
884 PFNKLDRWENUMRESLANG pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
885/** @} */
886
887
888/** @name Process Bootstrapping
889 * @{ */
890
891/**
892 * Argument package from the stub.
893 */
894typedef struct KLDREXEARGS
895{
896 /** Load & search flags, some which will become defaults. */
897 KU32 fFlags;
898 /** The default search method. */
899 KLDRDYLDSEARCH enmSearch;
900 /** The executable file that the stub is supposed to load. */
901 char szExecutable[260];
902 /** The default prefix used when searching for DLLs. */
903 char szDefPrefix[16];
904 /** The default suffix used when searching for DLLs. */
905 char szDefSuffix[16];
906 /** The LD_LIBRARY_PATH prefix for the process.. */
907 char szLibPath[4096 - sizeof(KU32) - sizeof(KLDRDYLDSEARCH) - 16 - 16 - 260];
908} KLDREXEARGS, *PKLDREXEARGS;
909/** Pointer to a const argument package from the stub. */
910typedef const KLDREXEARGS *PCKLDREXEARGS;
911
912void kLdrLoadExe(PCKLDREXEARGS pArgs, void *pvOS); /** @todo fix this mess... */
913void kLdrDyldLoadExe(PCKLDREXEARGS pArgs, void *pvOS);
914/** @} */
915
916/** @} */
917
918/** @} */
919
920#ifdef __cplusplus
921}
922#endif
923
924#endif
925
Note: See TracBrowser for help on using the repository browser.