VirtualBox

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

Last change on this file since 52 was 52, checked in by bird, 11 years ago

Added KLDRMOD_OPEN_FLAGS_FOR_INFO and fixed more mach-o issues.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 38.5 KB
Line 
1/* $Id: kLdr.h 52 2013-07-09 17:03:37Z 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 /** 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 */
351typedef 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. */
369typedef struct KLDRMODOPS *PKLDRMODOPS;
370/** Pointer to const module interpreter methods table. */
371typedef 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 */
377typedef 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 */
488typedef 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. */
491typedef 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 */
511typedef 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. */
514typedef 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 */
536typedef 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. */
540typedef 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 */
558typedef 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. */
561typedef 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/** @name Module Open Flags
592 * @{ */
593/** Indicates that we won't be loading the module, we're just getting
594 * information (like symbols and line numbers) out of it. */
595#define KLDRMOD_OPEN_FLAGS_FOR_INFO K_BIT32(0)
596/** Mask of valid flags. */
597#define KLDRMOD_OPEN_FLAGS_VALID_MASK KU32_C(0x00000001)
598/** @} */
599
600int kLdrModOpen(const char *pszFilename, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod);
601int kLdrModOpenFromRdr(PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, PPKLDRMOD ppMod);
602int kLdrModOpenNative(const char *pszFilename, PPKLDRMOD ppMod);
603int kLdrModOpenNativeByHandle(KUPTR uHandle, PPKLDRMOD ppMod);
604int kLdrModClose(PKLDRMOD pMod);
605
606int kLdrModQuerySymbol(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
607 const char *pchSymbol, KSIZE cchSymbol, const char *pszVersion,
608 PFNKLDRMODGETIMPORT pfnGetForwarder, void *pvUser, PKLDRADDR puValue, KU32 *pfKind);
609int kLdrModEnumSymbols(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress,
610 KU32 fFlags, PFNKLDRMODENUMSYMS pfnCallback, void *pvUser);
611int kLdrModGetImport(PKLDRMOD pMod, const void *pvBits, KU32 iImport, char *pszName, KSIZE cchName);
612KI32 kLdrModNumberOfImports(PKLDRMOD pMod, const void *pvBits);
613int kLdrModCanExecuteOn(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu);
614int kLdrModGetStackInfo(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo);
615int kLdrModQueryMainEntrypoint(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress);
616int kLdrModQueryResource(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 idType, const char *pszType,
617 KU32 idName, const char *pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE *pcbRsrc);
618int kLdrModEnumResources(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 idType, const char *pszType,
619 KU32 idName, const char *pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void *pvUser);
620int kLdrModEnumDbgInfo(PKLDRMOD pMod, const void *pvBits, PFNKLDRENUMDBG pfnCallback, void *pvUser);
621int kLdrModHasDbgInfo(PKLDRMOD pMod, const void *pvBits);
622int kLdrModMostlyDone(PKLDRMOD pMod);
623
624
625/** @name Operations On The Internally Managed Mapping
626 * @{ */
627int kLdrModMap(PKLDRMOD pMod);
628int kLdrModUnmap(PKLDRMOD pMod);
629int kLdrModAllocTLS(PKLDRMOD pMod);
630void kLdrModFreeTLS(PKLDRMOD pMod);
631int kLdrModReload(PKLDRMOD pMod);
632int kLdrModFixupMapping(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
633int kLdrModCallInit(PKLDRMOD pMod, KUPTR uHandle);
634int kLdrModCallTerm(PKLDRMOD pMod, KUPTR uHandle);
635int kLdrModCallThread(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching);
636/** @} */
637
638/** @name Operations On The Externally Managed Mappings
639 * @{ */
640KLDRADDR kLdrModSize(PKLDRMOD pMod);
641int kLdrModGetBits(PKLDRMOD pMod, void *pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
642int kLdrModRelocateBits(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
643 PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
644/** @} */
645
646
647/**
648 * The loader module operation.
649 */
650typedef struct KLDRMODOPS
651{
652 /** The name of this module interpreter. */
653 const char *pszName;
654 /** Pointer to the next module interpreter. */
655 PCKLDRMODOPS pNext;
656
657 /**
658 * Create a loader module instance interpreting the executable image found
659 * in the specified file provider instance.
660 *
661 * @returns 0 on success and *ppMod pointing to a module instance.
662 * On failure, a non-zero OS specific error code is returned.
663 * @param pOps Pointer to the registered method table.
664 * @param pRdr The file provider instance to use.
665 * @param fFlags Flags, MBZ.
666 * @param enmCpuArch The desired CPU architecture. KCPUARCH_UNKNOWN means
667 * anything goes, but with a preference for the current
668 * host architecture.
669 * @param offNewHdr The offset of the new header in MZ files. -1 if not found.
670 * @param ppMod Where to store the module instance pointer.
671 */
672 int (* pfnCreate)(PCKLDRMODOPS pOps, PKRDR pRdr, KU32 fFlags, KCPUARCH enmCpuArch, KLDRFOFF offNewHdr, PPKLDRMOD ppMod);
673 /**
674 * Destroys an loader module instance.
675 *
676 * The caller is responsible for calling kLdrModUnmap() and kLdrFreeTLS() first.
677 *
678 * @returns 0 on success, non-zero on failure. The module instance state
679 * is unknown on failure, it's best not to touch it.
680 * @param pMod The module.
681 */
682 int (* pfnDestroy)(PKLDRMOD pMod);
683
684 /** @copydoc kLdrModQuerySymbol */
685 int (* pfnQuerySymbol)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 iSymbol,
686 const char *pchSymbol, KSIZE cchSymbol, const char *pszVersion,
687 PFNKLDRMODGETIMPORT pfnGetForwarder, void *pvUser, PKLDRADDR puValue, KU32 *pfKind);
688 /** @copydoc kLdrModEnumSymbols */
689 int (* pfnEnumSymbols)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 fFlags,
690 PFNKLDRMODENUMSYMS pfnCallback, void *pvUser);
691 /** @copydoc kLdrModGetImport */
692 int (* pfnGetImport)(PKLDRMOD pMod, const void *pvBits, KU32 iImport, char *pszName, KSIZE cchName);
693 /** @copydoc kLdrModNumberOfImports */
694 KI32 (* pfnNumberOfImports)(PKLDRMOD pMod, const void *pvBits);
695 /** @copydoc kLdrModCanExecuteOn */
696 int (* pfnCanExecuteOn)(PKLDRMOD pMod, const void *pvBits, KCPUARCH enmArch, KCPU enmCpu);
697 /** @copydoc kLdrModGetStackInfo */
698 int (* pfnGetStackInfo)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRSTACKINFO pStackInfo);
699 /** @copydoc kLdrModQueryMainEntrypoint */
700 int (* pfnQueryMainEntrypoint)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, PKLDRADDR pMainEPAddress);
701 /** @copydoc kLdrModQueryResource */
702 int (* pfnQueryResource)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 idType, const char *pszType,
703 KU32 idName, const char *pszName, KU32 idLang, PKLDRADDR pAddrRsrc, KSIZE *pcbRsrc);
704 /** @copydoc kLdrModEnumResources */
705 int (* pfnEnumResources)(PKLDRMOD pMod, const void *pvBits, KLDRADDR BaseAddress, KU32 idType, const char *pszType,
706 KU32 idName, const char *pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void *pvUser);
707 /** @copydoc kLdrModEnumDbgInfo */
708 int (* pfnEnumDbgInfo)(PKLDRMOD pMod, const void *pvBits, PFNKLDRENUMDBG pfnCallback, void *pvUser);
709 /** @copydoc kLdrModHasDbgInfo */
710 int (* pfnHasDbgInfo)(PKLDRMOD pMod, const void *pvBits);
711 /** @copydoc kLdrModMap */
712 int (* pfnMap)(PKLDRMOD pMod);
713 /** @copydoc kLdrModUnmap */
714 int (* pfnUnmap)(PKLDRMOD pMod);
715 /** @copydoc kLdrModAllocTLS */
716 int (* pfnAllocTLS)(PKLDRMOD pMod);
717 /** @copydoc kLdrModFreeTLS */
718 void (*pfnFreeTLS)(PKLDRMOD pMod);
719 /** @copydoc kLdrModReload */
720 int (* pfnReload)(PKLDRMOD pMod);
721 /** @copydoc kLdrModFixupMapping */
722 int (* pfnFixupMapping)(PKLDRMOD pMod, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
723 /** @copydoc kLdrModCallInit */
724 int (* pfnCallInit)(PKLDRMOD pMod, KUPTR uHandle);
725 /** @copydoc kLdrModCallTerm */
726 int (* pfnCallTerm)(PKLDRMOD pMod, KUPTR uHandle);
727 /** @copydoc kLdrModCallThread */
728 int (* pfnCallThread)(PKLDRMOD pMod, KUPTR uHandle, unsigned fAttachingOrDetaching);
729 /** @copydoc kLdrModSize */
730 KLDRADDR (* pfnSize)(PKLDRMOD pMod);
731 /** @copydoc kLdrModGetBits */
732 int (* pfnGetBits)(PKLDRMOD pMod, void *pvBits, KLDRADDR BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
733 /** @copydoc kLdrModRelocateBits */
734 int (* pfnRelocateBits)(PKLDRMOD pMod, void *pvBits, KLDRADDR NewBaseAddress, KLDRADDR OldBaseAddress,
735 PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
736 /** @copydoc kLdrModMostlyDone */
737 int (* pfnMostlyDone)(PKLDRMOD pMod);
738 /** Dummy which should be assigned a non-zero value. */
739 KU32 uEndOfStructure;
740} KLDRMODOPS;
741
742
743/** @} */
744
745
746
747
748/** @defgroup grp_kLdrDyld kLdrDyld - The dynamic loader
749 * @{ */
750
751/** The handle to a dynamic loader module. */
752typedef struct KLDRDYLDMOD *HKLDRMOD;
753/** Pointer to the handle to a dynamic loader module. */
754typedef HKLDRMOD *PHKLDRMOD;
755/** NIL handle value. */
756#define NIL_HKLDRMOD ((HKLDRMOD)0)
757
758
759/**
760 * File search method.
761 *
762 * In addition to it's own way of finding files, kLdr emulates
763 * the methods employed by the most popular systems.
764 */
765typedef enum KLDRDYLDSEARCH
766{
767 /** The usual invalid file search method. */
768 KLDRDYLD_SEARCH_INVALID = 0,
769 /** Uses the kLdr file search method.
770 * @todo invent me. */
771 KLDRDYLD_SEARCH_KLDR,
772 /** Use the emulation closest to the host system. */
773 KLDRDYLD_SEARCH_HOST,
774 /** Emulate the OS/2 file search method.
775 * On non-OS/2 systems, BEGINLIBPATH, LIBPATH, ENDLIBPATH and LIBPATHSTRICT are
776 * taken form the environment. */
777 KLDRDYLD_SEARCH_OS2,
778 /** Emulate the standard window file search method. */
779 KLDRDYLD_SEARCH_WINDOWS,
780 /** Emulate the alternative window file search method. */
781 KLDRDYLD_SEARCH_WINDOWS_ALTERED,
782 /** Emulate the most common UNIX file search method. */
783 KLDRDYLD_SEARCH_UNIX_COMMON,
784 /** End of the valid file search method values. */
785 KLDRDYLD_SEARCH_END,
786 /** Hack to blow the type up to 32-bit. */
787 KLDRDYLD_SEARCH_32BIT_HACK = 0x7fffffff
788} KLDRDYLDSEARCH;
789
790/** @name kLdrDyldLoad and kLdrDyldFindByName flags.
791 * @{ */
792/** The symbols in the module should be loaded into the global unix namespace.
793 * If not specified, the symbols are local and can only be referenced directly. */
794#define KLDRYDLD_LOAD_FLAGS_GLOBAL_SYMBOLS 0x00000001
795/** The symbols in the module should be loaded into the global unix namespace and
796 * it's symbols should take precedence over all currently loaded modules.
797 * This implies KLDRYDLD_LOAD_FLAGS_GLOBAL_SYMBOLS. */
798#define KLDRYDLD_LOAD_FLAGS_DEEP_SYMBOLS 0x00000002
799/** The module shouldn't be found by a global module search.
800 * If not specified, the module can be found by unspecified module searches,
801 * typical used when loading import/dep modules. */
802#define KLDRYDLD_LOAD_FLAGS_SPECIFIC_MODULE 0x00000004
803/** Do a recursive initialization calls instead of defering them to the outermost call. */
804#define KLDRDYLD_LOAD_FLAGS_RECURSIVE_INIT 0x00000008
805/** We're loading the executable module.
806 * @internal */
807#define KLDRDYLD_LOAD_FLAGS_EXECUTABLE 0x40000000
808/** @} */
809
810
811int kLdrDyldLoad(const char *pszDll, const char *pszPrefix, const char *pszSuffix, KLDRDYLDSEARCH enmSearch,
812 unsigned fFlags, PHKLDRMOD phMod, char *pszErr, KSIZE cchErr);
813int kLdrDyldUnload(HKLDRMOD hMod);
814int kLdrDyldFindByName(const char *pszDll, const char *pszPrefix, const char *pszSuffix, KLDRDYLDSEARCH enmSearch,
815 unsigned fFlags, PHKLDRMOD phMod);
816int kLdrDyldFindByAddress(KUPTR Address, PHKLDRMOD phMod, KU32 *piSegment, KUPTR *poffSegment);
817int kLdrDyldGetName(HKLDRMOD hMod, char *pszName, KSIZE cchName);
818int kLdrDyldGetFilename(HKLDRMOD hMod, char *pszFilename, KSIZE cchFilename);
819int kLdrDyldQuerySymbol(HKLDRMOD hMod, KU32 uSymbolOrdinal, const char *pszSymbolName,
820 const char *pszSymbolVersion, KUPTR *pValue, KU32 *pfKind);
821int kLdrDyldQueryResource(HKLDRMOD hMod, KU32 idType, const char *pszType, KU32 idName,
822 const char *pszName, KU32 idLang, void **pvRsrc, KSIZE *pcbRsrc);
823int kLdrDyldEnumResources(HKLDRMOD hMod, KU32 idType, const char *pszType, KU32 idName,
824 const char *pszName, KU32 idLang, PFNKLDRENUMRSRC pfnCallback, void *pvUser);
825
826
827/** @name OS/2 like API
828 * @{ */
829#if defined(__OS2__)
830# define KLDROS2API _System
831#else
832# define KLDROS2API
833#endif
834int kLdrDosLoadModule(char *pszObject, KSIZE cbObject, const char *pszModule, PHKLDRMOD phMod);
835int kLdrDosFreeModule(HKLDRMOD hMod);
836int kLdrDosQueryModuleHandle(const char *pszModname, PHKLDRMOD phMod);
837int kLdrDosQueryModuleName(HKLDRMOD hMod, KSIZE cchName, char *pszName);
838int kLdrDosQueryProcAddr(HKLDRMOD hMod, KU32 iOrdinal, const char *pszProcName, void **ppvProcAddr);
839int kLdrDosQueryProcType(HKLDRMOD hMod, KU32 iOrdinal, const char *pszProcName, KU32 *pfProcType);
840int kLdrDosQueryModFromEIP(PHKLDRMOD phMod, KU32 *piObject, KSIZE cbName, char *pszName, KUPTR *poffObject, KUPTR ulEIP);
841int kLdrDosReplaceModule(const char *pszOldModule, const char *pszNewModule, const char *pszBackupModule);
842int kLdrDosGetResource(HKLDRMOD hMod, KU32 idType, KU32 idName, void **pvResAddr);
843int kLdrDosQueryResourceSize(HKLDRMOD hMod, KU32 idType, KU32 idName, KU32 *pcb);
844int kLdrDosFreeResource(void *pvResAddr);
845/** @} */
846
847/** @name POSIX like API
848 * @{ */
849HKLDRMOD kLdrDlOpen(const char *pszLibrary, int fFlags);
850const char *kLdrDlError(void);
851void * kLdrDlSym(HKLDRMOD hMod, const char *pszSymbol);
852int kLdrDlClose(HKLDRMOD hMod);
853/** @todo GNU extensions */
854/** @} */
855
856/** @name Win32 like API
857 * @{ */
858#if defined(_MSC_VER)
859# define KLDRWINAPI __stdcall
860#else
861# define KLDRWINAPI
862#endif
863HKLDRMOD KLDRWINAPI kLdrWLoadLibrary(const char *pszFilename);
864HKLDRMOD KLDRWINAPI kLdrWLoadLibraryEx(const char *pszFilename, void *hFileReserved, KU32 fFlags);
865KU32 KLDRWINAPI kLdrWGetModuleFileName(HKLDRMOD hMod, char *pszModName, KSIZE cchModName);
866HKLDRMOD KLDRWINAPI kLdrWGetModuleHandle(const char *pszFilename);
867int KLDRWINAPI kLdrWGetModuleHandleEx(KU32 fFlags, const char *pszFilename, HKLDRMOD hMod);
868void * KLDRWINAPI kLdrWGetProcAddress(HKLDRMOD hMod, const char *pszProcName);
869KU32 KLDRWINAPI kLdrWGetDllDirectory(KSIZE cchDir, char *pszDir);
870int KLDRWINAPI kLdrWSetDllDirectory(const char *pszDir);
871int KLDRWINAPI kLdrWFreeLibrary(HKLDRMOD hMod);
872int KLDRWINAPI kLdrWDisableThreadLibraryCalls(HKLDRMOD hMod);
873
874/** The handle to a resource that's been found. */
875typedef struct KLDRWRSRCFOUND *HKLDRWRSRCFOUND;
876/** The handle to a loaded resource. */
877typedef struct KLDRWRSRCLOADED *HKLDRWRSRCLOADED;
878HKLDRWRSRCFOUND KLDRWINAPI kLdrWFindResource(HKLDRMOD hMod, const char *pszType, const char *pszName);
879HKLDRWRSRCFOUND KLDRWINAPI kLdrWFindResourceEx(HKLDRMOD hMod, const char *pszType, const char *pszName, KU16 idLang);
880KU32 KLDRWINAPI kLdrWSizeofResource(HKLDRMOD hMod, HKLDRWRSRCFOUND hFoundRsrc);
881HKLDRWRSRCLOADED KLDRWINAPI kLdrWLoadResource(HKLDRMOD hMod, HKLDRWRSRCFOUND hFoundRsrc);
882void *KLDRWINAPI kLdrWLockResource(HKLDRMOD hMod, HKLDRWRSRCLOADED hLoadedRsrc);
883int KLDRWINAPI kLdrWFreeResource(HKLDRMOD hMod, HKLDRWRSRCLOADED hLoadedRsrc);
884
885typedef int (KLDRWINAPI *PFNKLDRWENUMRESTYPE)(HKLDRMOD hMod, const char *pszType, KUPTR uUser);
886int KLDRWINAPI kLdrWEnumResourceTypes(HKLDRMOD hMod, PFNKLDRWENUMRESTYPE pfnEnum, KUPTR uUser);
887int KLDRWINAPI kLdrWEnumResourceTypesEx(HKLDRMOD hMod, PFNKLDRWENUMRESTYPE pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
888
889typedef int (KLDRWINAPI *PFNKLDRWENUMRESNAME)(HKLDRMOD hMod, const char *pszType, char *pszName, KUPTR uUser);
890int KLDRWINAPI kLdrWEnumResourceNames(HKLDRMOD hMod, const char *pszType, PFNKLDRWENUMRESNAME pfnEnum, KUPTR uUser);
891int KLDRWINAPI kLdrWEnumResourceNamesEx(HKLDRMOD hMod, const char *pszType, PFNKLDRWENUMRESNAME pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
892
893typedef int (KLDRWINAPI *PFNKLDRWENUMRESLANG)(HKLDRMOD hMod, const char *pszType, const char *pszName, KU16 idLang, KUPTR uUser);
894int KLDRWINAPI kLdrWEnumResourceLanguages(HKLDRMOD hMod, const char *pszType, const char *pszName, PFNKLDRWENUMRESLANG pfnEnum, KUPTR uUser);
895int KLDRWINAPI kLdrWEnumResourceLanguagesEx(HKLDRMOD hMod, const char *pszType, const char *pszName,
896 PFNKLDRWENUMRESLANG pfnEnum, KUPTR uUser, KU32 fFlags, KU16 idLang);
897/** @} */
898
899
900/** @name Process Bootstrapping
901 * @{ */
902
903/**
904 * Argument package from the stub.
905 */
906typedef struct KLDREXEARGS
907{
908 /** Load & search flags, some which will become defaults. */
909 KU32 fFlags;
910 /** The default search method. */
911 KLDRDYLDSEARCH enmSearch;
912 /** The executable file that the stub is supposed to load. */
913 char szExecutable[260];
914 /** The default prefix used when searching for DLLs. */
915 char szDefPrefix[16];
916 /** The default suffix used when searching for DLLs. */
917 char szDefSuffix[16];
918 /** The LD_LIBRARY_PATH prefix for the process.. */
919 char szLibPath[4096 - sizeof(KU32) - sizeof(KLDRDYLDSEARCH) - 16 - 16 - 260];
920} KLDREXEARGS, *PKLDREXEARGS;
921/** Pointer to a const argument package from the stub. */
922typedef const KLDREXEARGS *PCKLDREXEARGS;
923
924void kLdrLoadExe(PCKLDREXEARGS pArgs, void *pvOS); /** @todo fix this mess... */
925void kLdrDyldLoadExe(PCKLDREXEARGS pArgs, void *pvOS);
926/** @} */
927
928/** @} */
929
930/** @} */
931
932#ifdef __cplusplus
933}
934#endif
935
936#endif
937
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette