source: trunk/kLdr/kLdr.h@ 2829

Last change on this file since 2829 was 2829, checked in by bird, 19 years ago

Mapping prototypes.

  • Property svn:keywords set to Id
File size: 14.7 KB
Line 
1/* $Id: kLdr.h 2829 2006-10-23 17:04:04Z bird $ */
2/** @file
3 *
4 * kLdr - The Dynamic Loader.
5 *
6 * Copyright (c) 2006 knut st. osmundsen <bird@anduin.net>
7 *
8 *
9 * This file is part of kLdr.
10 *
11 * kLdr is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
15 *
16 * kLdr is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with kLdr; if not, write to the Free Software
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 *
25 */
26
27#ifndef __kLdr_h__
28#define __kLdr_h__
29
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34/* kLdr depend on size_t, [u]intNN_t, [u]intptr_t and some related constants. */
35#include <sys/types.h>
36#include <stddef.h>
37#ifdef _MSC_VER
38typedef signed char int8_t;
39typedef unsigned char uint8_t;
40typedef signed short int16_t;
41typedef unsigned short uint16_t;
42typedef signed int int32_t;
43typedef unsigned int uint32_t;
44typedef signed __int64 int64_t;
45typedef unsigned __int64 uint64_t;
46typedef uint64_t uintmax_t;
47#else
48# include <stdint.h>
49#endif
50
51
52/** @defgroup grp_kLdrRdr kLdrRdr - The file provider
53 * @{ */
54
55typedef enum KLDRPROT
56{
57 /** The usual invalid 0. */
58 KLDRPROT_INVALID = 0,
59 /** No access (page not present). */
60 KLDRPROT_NOACCESS,
61 /** Read only. */
62 KLDRPROT_READONLY,
63 /** Read & write. */
64 KLDRPROT_READWRITE,
65 /** Read & copy on write. */
66 KLDRPROT_WRITECOPY,
67 /** Execute only. */
68 KLDRPROT_EXECUTE,
69 /** Execute & read. */
70 KLDRPROT_EXECUTE_READONLY,
71 /** Execute, read & write. */
72 KLDRPROT_EXECUTE_READWRITE,
73 /** Execute, read & copy on write. */
74 KLDRPROT_EXECUTE_WRITECOPY,
75 /** The usual end value. (exclusive) */
76 KLDRPROT_END,
77 /** Blow the type up to 32-bits. */
78 KLDRPROT_32BIT_HACK = 0x7fffffff
79} KLDRPROT;
80
81
82/** Pointer to a file provider instance core. */
83typedef struct KLDRRDR *PKLDRRDR;
84/** Pointer to a file provider instance core pointer. */
85typedef struct KLDRRDR **PPKLDRRDR;
86
87/**
88 * File provider instance operations.
89 */
90typedef struct KLDRRDROPS
91{
92 /** The name of this file provider. */
93 const char *pszName;
94 /** Pointer to the next file provider. */
95 const struct KLDRRDROPS *pNext;
96
97 /** Try create a new file provider instance.
98 *
99 * @returns 0 on success, OS specific error code on failure.
100 * @param ppRdr Where to store the file provider instance.
101 * @param pszFilename The filename to open.
102 */
103 int (* pfnCreate)( PPKLDRRDR ppRdr, const char *pszFilename);
104 /** Destroy the file provider instance.
105 *
106 * @returns 0 on success, OS specific error code on failure.
107 * On failure, the file provider instance will be in an indeterminate state - don't touch it!
108 * @param pRdr The file provider instance.
109 */
110 int (* pfnDestroy)( PKLDRRDR pRdr);
111 /** Read bits from the file.
112 *
113 * @returns 0 on success, OS specific error code on failure.
114 * @param pRdr The file provider instance.
115 * @param pvBuf Where to put the bits.
116 * @param cb The number of bytes to read.
117 * @param off Where to start reading.
118 */
119 int (* pfnRead)( PKLDRRDR pRdr, void *pvBuf, size_t cb, off_t off);
120 /** Map all the file bits into memory (read only).
121 *
122 * @returns 0 on success, OS specific error code on failure.
123 * @param pRdr The file provider instance.
124 * @param ppvBits Where to store the address of the mapping.
125 * The size can be obtained using pfnSize.
126 */
127 int (* pfnAllMap)( PKLDRRDR pRdr, const void **ppvBits);
128 /** Unmap a file bits mapping obtained by KLDRRDROPS::pfnAllMap.
129 *
130 * @returns 0 on success, OS specific error code on failure.
131 * @param pRdr The file provider instance.
132 * @param pvBits The mapping address.
133 */
134 int (* pfnAllUnmap)(PKLDRRDR pRdr, const void *pvBits);
135 /** Get the file size.
136 *
137 * @returns The file size. Returns -1 on failure.
138 * @param pRdr The file provider instance.
139 */
140 off_t (* pfnSize)( PKLDRRDR pRdr);
141 /** Get the file pointer offset.
142 *
143 * @returns The file pointer offset. Returns -1 on failure.
144 * @param pRdr The file provider instance.
145 */
146 off_t (* pfnTell)( PKLDRRDR pRdr);
147 /** Get the file name.
148 *
149 * @returns The file size. Returns -1 on failure.
150 * @param pRdr The file provider instance.
151 */
152 const char * (* pfnName)(PKLDRRDR pRdr);
153 /**
154 * Prepares a memory region to map file sections into.
155 *
156 * @returns 0 on success, OS specific error code on failure.
157 * @param pRdr The file provider instance.
158 * @param ppv If fFixed is set, *ppv contains the memory location which
159 * the region should be based at. If fFixed is clear the OS
160 * is free to choose the location.
161 * On successful return *ppv contains address of the prepared
162 * memory region.
163 * @param cb The size of the memory region to prepare.
164 * @param fFixed When set *ppv will contain the desired region address.
165 *
166 */
167 int (* pfnPrepare)(PKLDRRDR pRdr, void **ppv, size_t cb, unsigned fFixed);
168 /**
169 * Maps a section of the file into the memory region reserved by pfnPrepare.
170 *
171 * @returns 0 on success, OS specific error code on failure.
172 * @param pRdr The file provider instance.
173 * @param pv The address in the prepared region.
174 * @param cb The size of the memory mapping.
175 * @param enmProt The desired memory protection.
176 * @param offFile The start of the raw file bytes.
177 * @param cbFile The number of raw file bytes. This must be less or equal to cb.
178 */
179 int (* pfnMap)(PKLDRRDR pRdr, void *pv, size_t cb, KLDRPROT enmProt, off_t offFile, size_t cbFile);
180 /**
181 * Changes the page protection of a section mapped using pfnMap.
182 *
183 * This is typically used for applying fixups and similar.
184 *
185 * @returns 0 on success, OS specific error code on failure.
186 * @param pRdr The file provider instance.
187 * @param pv The address passed to pfnMap.
188 * @param cb The size passed to pfnMap.
189 * @param enmProt The desired memory protection.
190 */
191 int (* pfnProtect)(PKLDRRDR pRdr, void *pv, size_t cb, KLDRPROT enmProt);
192 /**
193 * Unmaps a section of the file previously mapped using pfnMap.
194 *
195 * @returns 0 on success, OS specific error code on failure.
196 * @param pRdr The file provider instance.
197 * @param pv The address passed to pfnMap.
198 * @param cb The size passed to pfnMap.
199 */
200 int (* pfnUnmap)(PKLDRRDR pRdr, void *pv, size_t cb);
201 /**
202 * Releases the memory region prepared by pfnPrepare().
203 *
204 * Before calling this function, all sections mapped by pfnMap must first be unmapped by calling pfnUnmap.
205 *
206 * @returns 0 on success, OS specific error code on failure.
207 * @param pRdr The file provider instance.
208 * @param pv The address of the prepared region.
209 * @param cb The size of the prepared region.
210 */
211 int (* pfnUnprepare)(PKLDRRDR pRdr, void *pv, size_t cb);
212 /**
213 * We're done reading from the file but would like to keep file mappings.
214 *
215 * If the OS support closing the file handle while the file is mapped,
216 * the reader should do so.
217 *
218 * @param pRdr The file provider instance.
219 */
220 void (* pfnDone)(PKLDRRDR pRdr);
221 /** The usual non-zero dummy that makes sure we've initialized all members. */
222 uint32_t u32Dummy;
223} KLDRRDROPS;
224/** Pointer to file provider operations. */
225typedef KLDRRDROPS *PKLDRRDROPS;
226/** Pointer to const file provider operations. */
227typedef const KLDRRDROPS *PCKLDRRDROPS;
228
229
230/**
231 * File provider instance core.
232 */
233typedef struct KLDRRDR
234{
235 /** Pointer to the file provider operations. */
236 PCKLDRRDROPS pOps;
237} KLDRRDR;
238
239void kLdrRdrAddProvider(PKLDRRDROPS pAdd);
240
241int kLdrRdrOpen( PPKLDRRDR ppRdr, const char *pszFilename);
242int kLdrRdrClose( PKLDRRDR pRdr);
243int kLdrRdrRead( PKLDRRDR pRdr, void *pvBuf, size_t cb, off_t off);
244int kLdrRdrAllMap( PKLDRRDR pRdr, const void **ppvBits);
245int kLdrRdrAllUnmap(PKLDRRDR pRdr, const void *pvBits);
246off_t kLdrRdrSize( PKLDRRDR pRdr);
247off_t kLdrRdrTell( PKLDRRDR pRdr);
248const char *kLdrRdrName(PKLDRRDR pRdr);
249
250/** @} */
251
252
253
254/** @defgroup grp_kLdrMod kLdrMod - The executable image intepreter
255 * @{ */
256
257/**
258 * Loader segment.
259 */
260typedef struct KLDRSEG
261{
262 /** The segment load address. */
263 void *pv;
264 /** The size of the segment. */
265 size_t cb;
266 /** The segment is readable. */
267 uint32_t fRead : 1;
268 /** The segment is writable. */
269 uint32_t fWrite : 1;
270 /** The segment is executable. */
271 uint32_t fExecute : 1;
272 /** Reserved for future use. */
273 uint32_t fReserved : 29;
274 /** Reserved for future use. */
275 uint32_t u32Reserved;
276} KLDRSEG, *PKLDRSEG;
277
278
279/**
280 * Loader module type.
281 */
282typedef enum KLDRTYPE
283{
284 /** The usual invalid 0 type. */
285 KLDRTYPE_INVALID = 0,
286 /** The native OS loader. */
287 KLDRTYPE_NATIVE,
288 /** The LX loader. */
289 KLDRTYPE_LX,
290 /** The end type (not included). */
291 KLDRTYPE_END,
292 /** Hack to blow the type up to 32-bit. */
293 KLDRTYPE_32BIT_HACK = 0x7fffffff
294} KLDRTYPE;
295
296
297/**
298 * Loader module.
299 */
300typedef struct KLDRMOD
301{
302 /** Magic number. */
303 uint32_t u32Magic;
304 /** The type of module this is. */
305 KLDRTYPE enmType;
306 /** The module data. */
307 void *pvData;
308 /** The filename length (bytes). */
309 uint32_t cchFilename;
310 /** The filename. */
311 const char *pszFilename;
312 /** The module name. */
313 const char *pszName;
314 /** The module name length (bytes). */
315 uint32_t cchName;
316 /** The number of segments in the module. */
317 uint32_t cSegments;
318 /** Segments. (variable size, can be zero) */
319 KLDRSEG aSegments[1];
320} KLDRMOD, *PKLDRMOD, **PPKLDRMOD;
321
322
323int kLdrModOpen(const char *pszFilename, PPKLDRMOD ppMod);
324int kLdrModClose(PKLDRMOD pMod);
325int kLdrModGetSymbol(PKLDRMOD pMod, const void *pvBits, uintmax_t BaseAddress, const char *pszSymbol, uintmax_t *pValue, unsigned *pfType);
326int kLdrModGetSymbol(PKLDRMOD pMod, const void *pvBits, uintmax_t BaseAddress, const char *pszSymbol, uintmax_t *pValue, unsigned *pfType);
327
328size_t kLdrModSize(PKLDRMOD pMod);
329
330typedef int FNKLDRMODGETIMPORT(PKLDRMOD pMod, const char *pszModule, const char *pszSymbol, unsigned uSymbol, uintmax_t *pValue, void *pvUser);
331typedef FNKLDRMODGETIMPORT *PFNKLDRMODGETIMPORT;
332int kLdrModGetBits(PKLDRMOD pMod, void *pvBits, uintmax_t BaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
333int kLdrModRelocate(PKLDRMOD pMod, void *pvBits, uintmax_t NewBaseAddress, uintmax_t OldBaseAddress, PFNKLDRMODGETIMPORT pfnGetImport, void *pvUser);
334
335typedef int FNKLDRMODENUMSYMS(PKLDRMOD pMod, const char *pszSymbol, unsigned uSymbol, uintmax_t Value, void *pvUser);
336typedef FNKLDRMODENUMSYMS *PFNKLDRMODENUMSYMS;
337int kLdrModEnumSymbols(PKLDRMOD pMod, unsigned fFlags, const void *pvBits, uintmax_t BaseAddress, PFNKLDRMODENUMSYMS pfnCallback, void *pvUser);
338/** @name kLdrModEnumSymbols flags.
339 * @{ */
340/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
341#define KLDRMOD_ENUM_SYMBOL_FLAGS_ALL 0x00000001
342/** @} */
343
344/** @} */
345
346
347
348
349/** @defgroup grp_kLdrDy kLdrDy - The dynamic loader
350 * @{ */
351
352/** The h*/
353typedef struct KLDRDY *PKLDRDY;
354
355/*
356int kLdrLoadDll(const char *pszFilename, unsigned fFlags, unsigned long *pvmod);
357*/
358
359/** @name Process Bootstrapping
360 * @{ */
361
362/**
363 * Argument package from the stub.
364 */
365typedef struct KLDREXEARGS
366{
367 /** Flags. (Currently unused, MBZ.) */
368 uint32_t fFlags;
369 /** The executable file that the stub is supposed to load. */
370 char szExecutable[260];
371 /** The LD_LIBRARY_PATH prefix for the process.. */
372 char szLibPath[4096 - 260 - sizeof(uint32_t)];
373} KLDREXEARGS, *PKLDREXEARGS;
374
375void kLdrLoadExe(PKLDREXEARGS pArgs);
376/** @} */
377
378/** @} */
379
380
381/** @defgroup grp_kLdrErr kLdr Status Codes
382 * kLdr uses a mix of native status codes and it's own status codes.
383 * A status code of 0 means success, all other status codes means failure.
384 * @{
385 */
386#ifdef __OS2__
387# define KLDR_ERR_BASE 0x7face000
388#elif defined(__WIN__)
389# define KLDR_ERR_BASE 0x7face000
390#else
391# error "port me"
392#endif
393/** The image format is unknown. */
394#define KLDR_ERR_UNKNOWN_FORMAT (KLDR_ERR_BASE + 0)
395/** The MZ image format isn't supported by this kLdr build. */
396#define KLDR_ERR_MZ_NOT_SUPPORTED (KLDR_ERR_BASE + 1)
397/** The NE image format isn't supported by this kLdr build. */
398#define KLDR_ERR_NE_NOT_SUPPORTED (KLDR_ERR_BASE + 2)
399/** The LX image format isn't supported by this kLdr build. */
400#define KLDR_ERR_LX_NOT_SUPPORTED (KLDR_ERR_BASE + 3)
401/** The LE image format isn't supported by this kLdr build. */
402#define KLDR_ERR_LE_NOT_SUPPORTED (KLDR_ERR_BASE + 4)
403/** The PE image format isn't supported by this kLdr build. */
404#define KLDR_ERR_PE_NOT_SUPPORTED (KLDR_ERR_BASE + 5)
405/** The ELF image format isn't supported by this kLdr build. */
406#define KLDR_ERR_ELF_NOT_SUPPORTED (KLDR_ERR_BASE + 6)
407/** The mach-o image format isn't supported by this kLdr build. */
408#define KLDR_ERR_MACHO_NOT_SUPPORTED (KLDR_ERR_BASE + 7)
409/** The mach-o image format isn't supported by this kLdr build. */
410#define KLDR_ERR_AOUT_NOT_SUPPORTED (KLDR_ERR_BASE + 8)
411/** The mach-o image format isn't supported by this kLdr build. */
412#define KLDR_ERR_BAD_FIXUP (KLDR_ERR_BASE + 32)
413
414/** @} */
415
416
417#ifdef __cplusplus
418}
419#endif
420
421#endif
422
Note: See TracBrowser for help on using the repository browser.