f265da4e320ddaf3f09e702c6fd1fc6512290ef7
[ipc/ipcdev.git] / qnx / src / ipc3x_dev / ti / syslink / procMgr / hlos / knl / loaders / Elf / Qnx / DLOAD / DLOAD_API / dload_api.h
1 /*
2 * dload_api.h
3 *
4 * Dynamic Loader API Specification
5 * --------------------------------
6 *
7 * Client-side of API is assumed to be platform dependent, but object file
8 * format independent.
9 *
10 * Core Loader side of API is assumed to be platform independent, but
11 * object file format dependent and target dependent.
12 *
13 * Copyright (C) 2009 Texas Instruments Incorporated - http://www.ti.com/
14 *
15 *
16 * Redistribution and use in source and binary forms, with or without
17 * modification, are permitted provided that the following conditions
18 * are met:
19 *
20 * Redistributions of source code must retain the above copyright
21 * notice, this list of conditions and the following disclaimer.
22 *
23 * Redistributions in binary form must reproduce the above copyright
24 * notice, this list of conditions and the following disclaimer in the
25 * documentation and/or other materials provided with the
26 * distribution.
27 *
28 * Neither the name of Texas Instruments Incorporated nor the names of
29 * its contributors may be used to endorse or promote products derived
30 * from this software without specific prior written permission.
31 *
32 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
33 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
34 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
35 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
36 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
37 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
38 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
39 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
40 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
41 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
42 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
43 *
44 */
46 #ifndef DLOAD_API_H
47 #define DLOAD_API_H
48 #include <ti/syslink/Std.h>
49 #include <inttypes.h>
50 #include <stdio.h>
52 /*****************************************************************************/
53 /* Specification of Loader File Descriptor.  If client side of the loader    */
54 /* supports virtual memory, this may need to be updated to facilitate the    */
55 /* use of mmap().                                                            */
56 /*****************************************************************************/
58 #if defined (__KERNEL__)
59 typedef struct file LOADER_FILE_DESC;
60 #else
61 typedef FILE LOADER_FILE_DESC;
62 #endif
64 static const int LOADER_SEEK_SET = SEEK_SET;
65 static const int LOADER_SEEK_CUR = SEEK_CUR;
66 static const int LOADER_SEEK_END = SEEK_END;
68 /*****************************************************************************/
69 /* TARGET_ADDRESS - type suitable for storing target memory address values.  */
70 /*****************************************************************************/
71 typedef void* TARGET_ADDRESS;
73 /*****************************************************************************/
74 /* DLOAD_HANDLE - defines the DLoad object handle.                           */
75 /*****************************************************************************/
76 typedef void * DLOAD_HANDLE;
78 /*****************************************************************************/
79 /* Core Loader Provided API Functions (Core Loader Entry Points)             */
80 /*****************************************************************************/
82 /*---------------------------------------------------------------------------*/
83 /* DLOAD_version()                                                           */
84 /*                                                                           */
85 /*    Return a string constant representation for the version ID of the      */
86 /*    dynamic loader's core loader source code.                              */
87 /*                                                                           */
88 /*---------------------------------------------------------------------------*/
89 #define VERSION 1.2
90 #define DLOAD_version() VERSION
92 /*---------------------------------------------------------------------------*/
93 /* DLOAD_create()                                                            */
94 /*                                                                           */
95 /*    Create an instance of the dynamic loader, passing a handle to the      */
96 /*    client-specific handle for this instance.                              */
97 /*                                                                           */
98 /*---------------------------------------------------------------------------*/
99 DLOAD_HANDLE  DLOAD_create(void * client_handle);
101 /*---------------------------------------------------------------------------*/
102 /* DLOAD_destroy()                                                           */
103 /*                                                                           */
104 /*    Destroy the specified dynamic loader instance.                         */
105 /*                                                                           */
106 /*---------------------------------------------------------------------------*/
107 void     DLOAD_destroy(DLOAD_HANDLE handle);
109 /*---------------------------------------------------------------------------*/
110 /* DLOAD_initialize()                                                        */
111 /*                                                                           */
112 /*    Construct and initialize data structures internal to the dynamic       */
113 /*    loader core.                                                           */
114 /*                                                                           */
115 /*---------------------------------------------------------------------------*/
116 void     DLOAD_initialize(DLOAD_HANDLE handle);
118 /*---------------------------------------------------------------------------*/
119 /* DLOAD_finalize()                                                          */
120 /*                                                                           */
121 /*    Finalize the dynamic loader core.                                      */
122 /*                                                                           */
123 /*---------------------------------------------------------------------------*/
124 void     DLOAD_finalize(DLOAD_HANDLE handle);
126 /*---------------------------------------------------------------------------*/
127 /* DLOAD_load_symbols()                                                      */
128 /*                                                                           */
129 /*    Load externally visible symbols from the specified file so that they   */
130 /*    can be linked against when another object file is subsequntly loaded.  */
131 /*    External symbols will be made available for global symbol linkage.     */
132 /*                                                                           */
133 /*---------------------------------------------------------------------------*/
134 int32_t  DLOAD_load_symbols(DLOAD_HANDLE handle, LOADER_FILE_DESC* fp);
136 /*---------------------------------------------------------------------------*/
137 /* DLOAD_load()                                                              */
138 /*                                                                           */
139 /*    Dynamically load the specified file and return a file handle for the   */
140 /*    loaded file.  If the load fails, this function will return a value     */
141 /*    zero (0).                                                              */
142 /*                                                                           */
143 /*    The core loader must have read access to the file pointed by fp.       */
144 /*                                                                           */
145 /*---------------------------------------------------------------------------*/
146 int      DLOAD_load(DLOAD_HANDLE handle, LOADER_FILE_DESC* fp, int argc,
147                     char** argv);
149 /*---------------------------------------------------------------------------*/
150 /* DLOAD_unload()                                                            */
151 /*                                                                           */
152 /*    Given a file handle ID, unload all object segments associated with     */
153 /*    the identified file and any of its dependents that are not still in    */
154 /*    use.                                                                   */
155 /*                                                                           */
156 /*---------------------------------------------------------------------------*/
157 BOOL     DLOAD_unload(DLOAD_HANDLE handle, uint32_t pseudopid);
159 /*---------------------------------------------------------------------------*/
160 /* DLOAD_get_entry_names_info()                                              */
161 /*                                                                           */
162 /*    Given a file handle, get the information needed to create an array of  */
163 /*    sufficient size to call DLOAD_get_entry_names.                         */
164 /*                                                                           */
165 /*---------------------------------------------------------------------------*/
166 BOOL     DLOAD_get_entry_names_info(DLOAD_HANDLE handle,
167                                     uint32_t file_handle,
168                                     int32_t *entry_pt_cnt,
169                                     int32_t *entry_pt_max_name_len);
171 /*---------------------------------------------------------------------------*/
172 /* DLOAD_get_entry_names()                                                   */
173 /*                                                                           */
174 /*    Given a file handle, build a list of entry point names that are        */
175 /*    available in the specified file.  This can be used when querying       */
176 /*    the list of global functions available in a shared library.            */
177 /*                                                                           */
178 /*---------------------------------------------------------------------------*/
179 BOOL     DLOAD_get_entry_names(DLOAD_HANDLE handle, uint32_t file_handle,
180                                int32_t* entry_pt_cnt, char*** entry_pt_names);
182 /*---------------------------------------------------------------------------*/
183 /* DLOAD_query_symbol()                                                      */
184 /*                                                                           */
185 /*    Query the value of a symbol that is defined by an object file that     */
186 /*    has previously been loaded.  Boolean return value will be false if     */
187 /*    the symbol is not found.                                               */
188 /*                                                                           */
189 /*---------------------------------------------------------------------------*/
190 BOOL     DLOAD_query_symbol(DLOAD_HANDLE handle, uint32_t file_handle,
191                             const char *sym_name, TARGET_ADDRESS *sym_val);
193 /*---------------------------------------------------------------------------*/
194 /* DLOAD_get_section_info()                                                  */
195 /*                                                                           */
196 /*    Query the value of a section that is defined by an object file that    */
197 /*    has previously been loaded.  Boolean return value will be false if     */
198 /*    the symbol is not found.                                               */
199 /*                                                                           */
200 /*---------------------------------------------------------------------------*/
201 BOOL     DLOAD_get_section_info(DLOAD_HANDLE handle, uint32_t file_handle,
202                                 const char *sect_name,
203                                 TARGET_ADDRESS *sect_val, uint32_t *sect_size);
205 /*---------------------------------------------------------------------------*/
206 /* DLOAD_get_section_offset()                                                  */
207 /*                                                                           */
208 /*    Query the value of a section that is defined by an object file that    */
209 /*    has previously been loaded.  Boolean return value will be false if     */
210 /*    the symbol is not found.                                               */
211 /*                                                                           */
212 /*---------------------------------------------------------------------------*/
213 BOOL     DLOAD_get_section_offset(LOADER_FILE_DESC *fd, char * sect_name,
214                                   uint32_t *sect_offs, uint32_t *sect_size,
215                                   uint32_t *sect_addr);
217 /*---------------------------------------------------------------------------*/
218 /* DLOAD_get_entry_point()                                                   */
219 /*                                                                           */
220 /*    Given a file handle, return the entry point target address associated  */
221 /*    with that object file.  The entry point address value is written to    */
222 /*    *sym_val.  The return value of the function indicates whether the      */
223 /*    file with the specified handle was found or not.                       */
224 /*                                                                           */
225 /*---------------------------------------------------------------------------*/
226 BOOL     DLOAD_get_entry_point(DLOAD_HANDLE handle, uint32_t file_handle,
227                                TARGET_ADDRESS *sym_val);
229 /*****************************************************************************/
230 /* Client Provided API Functions                                             */
231 /*****************************************************************************/
233 /*---------------------------------------------------------------------------*/
234 /* File I/O                                                                  */
235 /*                                                                           */
236 /*    The client side of the dynamic loader must provide basic file I/O      */
237 /*    capabilities so that the core loader has random access into any        */
238 /*    object file that it is asked to load.                                  */
239 /*                                                                           */
240 /*    The client side of the dynamic loader must provide a definition of     */
241 /*    the LOADER_FILE_DESC in dload_filedefs.h.  This allows the core loader */
242 /*    to be independent of how the client accesses raw data in an object     */
243 /*    file.                                                                  */
244 /*                                                                           */
245 /*---------------------------------------------------------------------------*/
247 /*---------------------------------------------------------------------------*/
248 /* DLIF_fseek()                                                              */
249 /*                                                                           */
250 /*    Seek to a position in a file (accessed via 'stream') based on the      */
251 /*    values for offset and origin.                                          */
252 /*                                                                           */
253 /*---------------------------------------------------------------------------*/
254 int      DLIF_fseek(LOADER_FILE_DESC *stream, int32_t offset, int origin);
256 /*---------------------------------------------------------------------------*/
257 /* DLIF_ftell()                                                              */
258 /*                                                                           */
259 /*    Return the current file position in the file identified in the         */
260 /*    LOADER_FILE_DESC pointed to by 'stream'.                               */
261 /*                                                                           */
262 /*---------------------------------------------------------------------------*/
263 int32_t  DLIF_ftell(LOADER_FILE_DESC *stream);
265 /*---------------------------------------------------------------------------*/
266 /* DLIF_fread()                                                              */
267 /*                                                                           */
268 /*    Read 'size' * 'nmemb' bytes of data from the file identified in the    */
269 /*    LOADER_FILE_DESC object pointed to by 'stream', and write that data    */
270 /*    into the memory accessed via 'ptr'.                                    */
271 /*                                                                           */
272 /*---------------------------------------------------------------------------*/
273 size_t   DLIF_fread(void *ptr, size_t size, size_t nmemb,
274                     LOADER_FILE_DESC *stream);
276 /*---------------------------------------------------------------------------*/
277 /* DLIF_fclose()                                                             */
278 /*                                                                           */
279 /*    Close a file that was opened on behalf of the core loader. Ownership   */
280 /*    of the file pointer in question belongs to the core loader, but the    */
281 /*    client has exclusive access to the file system.                        */
282 /*                                                                           */
283 /*---------------------------------------------------------------------------*/
284 int      DLIF_fclose(LOADER_FILE_DESC *fd);
286 /*---------------------------------------------------------------------------*/
287 /* Host Memory Management                                                    */
288 /*                                                                           */
289 /*    Allocate and free host memory as needed for the dynamic loader's       */
290 /*    internal data structures.  If the dynamic loader resides on the        */
291 /*    target architecture, then this memory is allocated from a target       */
292 /*    memory heap that must be managed separately from memory that is        */
293 /*    allocated for a dynamically loaded object file.                        */
294 /*                                                                           */
295 /*---------------------------------------------------------------------------*/
297 /*---------------------------------------------------------------------------*/
298 /* DLIF_malloc()                                                             */
299 /*                                                                           */
300 /*    Allocate 'size' bytes of memory space that is usable as scratch space  */
301 /*    (appropriate for the loader's internal data structures) by the dynamic */
302 /*    loader.                                                                */
303 /*                                                                           */
304 /*---------------------------------------------------------------------------*/
305 void*    DLIF_malloc(size_t size);
307 /*---------------------------------------------------------------------------*/
308 /* DLIF_free()                                                               */
309 /*                                                                           */
310 /*    Free memory space that was previously allocated by DLIF_malloc().      */
311 /*                                                                           */
312 /*---------------------------------------------------------------------------*/
313 void     DLIF_free(void* ptr);
315 /*---------------------------------------------------------------------------*/
316 /* Target Memory Allocator Interface                                         */
317 /*                                                                           */
318 /*    The client side of the dynamic loader must create and maintain an      */
319 /*    infrastructure to manage target memory.  The client must keep track    */
320 /*    of what target memory is associated with each object segment,          */
321 /*    allocating target memory for newly loaded objects and release target   */
322 /*    memory that is associated with objects that are being unloaded from    */
323 /*    the target architecture.                                               */
324 /*                                                                           */
325 /*    The two client-supplied functions, DLIF_allocate() and DLIF_release(), */
326 /*    are used by the core loader to interface into the client side's        */
327 /*    target memory allocator infrastructure.                                */
328 /*                                                                           */
329 /*---------------------------------------------------------------------------*/
331 /*---------------------------------------------------------------------------*/
332 /* DLOAD_SEGMENT_FLAGS - segment characteristics.                            */
333 /*---------------------------------------------------------------------------*/
334 typedef uint32_t DLOAD_SEGMENT_FLAGS;
335 static const int DLOAD_SF_executable = 0x1;  /* Memory must be executable    */
336 static const int DLOAD_SF_relocatable = 0x2; /* Segment must be relocatable  */
338 /*---------------------------------------------------------------------------*/
339 /* DLOAD_MEMORY_SEGMENT - Define structure to represent placement and size   */
340 /*      details of a segment to be loaded.                                   */
341 /*---------------------------------------------------------------------------*/
342 struct DLOAD_MEMORY_SEGMENT
344    uint32_t            target_page;     /* requested/returned memory page    */
345    TARGET_ADDRESS      target_address;  /* requested/returned address        */
346    uint32_t            objsz_in_bytes;  /* size of init'd part of segment    */
347    uint32_t            memsz_in_bytes;  /* size of memory block for segment  */
348    DLOAD_SEGMENT_FLAGS flags;           /* allocation request flags    */
349 };
351 /*---------------------------------------------------------------------------*/
352 /* DLOAD_MEMORY_REQUEST - Define structure to represent a target memory      */
353 /*      request made by the core loader on behalf of a segment that the      */
354 /*      loader needs to relocate and write into target memory.               */
355 /*---------------------------------------------------------------------------*/
356 struct DLOAD_MEMORY_REQUEST
358    LOADER_FILE_DESC            *fp;           /* file being loaded           */
359    struct DLOAD_MEMORY_SEGMENT *segment;      /* obj for req/ret alloc       */
360    void                        *host_address; /* ret hst ptr from DLIF_copy()*/
361    BOOL                         is_loaded;    /* returned as true if segment */
362                                               /* is already in target memory */
363    uint32_t                     offset;       /* file offset of segment's    */
364                                               /* raw data                    */
365    uint32_t                     flip_endian;  /* endianness of trg opp host  */
366    DLOAD_SEGMENT_FLAGS          flags;        /* allocation request flags    */
367    uint32_t                     align;        /* align of trg memory block   */
368 };
370 /*---------------------------------------------------------------------------*/
371 /* DLIF_allocate()                                                           */
372 /*                                                                           */
373 /*    Given a DLOAD_MEMORY_REQUEST created by the core loader, allocate      */
374 /*    target memory to fulfill the request using the target memory           */
375 /*    management infrastrucutre on the client side of the dynamic loader.    */
376 /*    The contents of the DLOAD_MEMORY_REQUEST will be updated per the       */
377 /*    details of a successful allocation.  The allocated page and address    */
378 /*    can be found in the DLOAD_MEMORY_SEGMENT attached to the request.      */
379 /*    The boolean return value reflects whether the allocation was           */
380 /*    successful or not.                                                     */
381 /*                                                                           */
382 /*---------------------------------------------------------------------------*/
383 BOOL     DLIF_allocate(void * client_handle, struct DLOAD_MEMORY_REQUEST *req);
385 /*---------------------------------------------------------------------------*/
386 /* DLIF_release()                                                            */
387 /*                                                                           */
388 /*    Given a DLOAD_MEMORY_SEGMENT description, free the target memory       */
389 /*    associated with the segment using the target memory management         */
390 /*    infrastructure on the client side of the dynamic loader.               */
391 /*                                                                           */
392 /*---------------------------------------------------------------------------*/
393 BOOL     DLIF_release(void* client_handle, struct DLOAD_MEMORY_SEGMENT* ptr);
395 /*---------------------------------------------------------------------------*/
396 /* Target Memory Access / Write Services                                     */
397 /*                                                                           */
398 /*    The client side's target memory allocator infrastructure communicates  */
399 /*    with the core loader through the DLOAD_MEMORY_REQUEST and              */
400 /*    DLOAD_MEMORY_SEGMENT data structures defined above.  To complete the   */
401 /*    loading of an object segment, the segment may need to be relocated     */
402 /*    before it is actually written to target memory in the space that was   */
403 /*    allocated for it by DLIF_allocate().                                   */
404 /*                                                                           */
405 /*    The client side of the dynamic loader provides two functions to help   */
406 /*    complete the process of loading an object segment, DLIF_copy() and     */
407 /*    DLIF_write().                                                          */
408 /*                                                                           */
409 /*    These functions help to make the core loader truly independent of      */
410 /*    whether it is running on the host or target architecture and how the   */
411 /*    client provides for reading/writing from/to target memory.             */
412 /*                                                                           */
413 /*---------------------------------------------------------------------------*/
414 /*---------------------------------------------------------------------------*/
415 /* DLIF_copy()                                                               */
416 /*                                                                           */
417 /*    Copy segment data from the object file described in the 'fp' and       */
418 /*    'offset' of the DLOAD_MEMORY_REQUEST into host accessible memory so    */
419 /*    that it can relocated or otherwise manipulated by the core loader.     */
420 /*                                                                           */
421 /*---------------------------------------------------------------------------*/
422 BOOL     DLIF_copy(void* client_handle, struct DLOAD_MEMORY_REQUEST* req);
424 /*---------------------------------------------------------------------------*/
425 /* DLIF_write()                                                              */
426 /*                                                                           */
427 /*    Once the segment data described in the DLOAD_MEMORY_REQUEST is ready   */
428 /*    (relocated, if needed), write the segment contents to the target       */
429 /*    memory identified in the DLOAD_MEMORY_SEGMENT attached to the request. */
430 /*                                                                           */
431 /*    After the segment contents have been written to target memory, the     */
432 /*    core loader should discard the DLOAD_MEMORY_REQUEST object, but retain */
433 /*    the DLOAD_MEMORY_SEGMENT object so that the target memory associated   */
434 /*    with the segment can be releases when the segment is unloaded.         */
435 /*                                                                           */
436 /*---------------------------------------------------------------------------*/
437 BOOL     DLIF_write(void* client_handle, struct DLOAD_MEMORY_REQUEST* req);
439 /*---------------------------------------------------------------------------*/
440 /* DLIF_read()                                                               */
441 /*                                                                           */
442 /*    Given a host accessible buffer, read content of indicated target       */
443 /*    memory address into the buffer.                                        */
444 /*---------------------------------------------------------------------------*/
445 BOOL     DLIF_read(void* client_handle, void *ptr, size_t size, size_t nmemb,
446                    TARGET_ADDRESS src);
448 /*---------------------------------------------------------------------------*/
449 /* DLIF_execute()                                                            */
450 /*                                                                           */
451 /*    Start execution on the target architecture from given 'exec_addr'.     */
452 /*    If the dynamic loader is running on the target architecture, this can  */
453 /*    be effected as a simple function call.                                 */
454 /*                                                                           */
455 /*---------------------------------------------------------------------------*/
456 int32_t  DLIF_execute(void* client_handle, TARGET_ADDRESS exec_addr);
458 /*---------------------------------------------------------------------------*/
459 /* Loading and Unloading of Dependent Files                                  */
460 /*                                                                           */
461 /*    The dynamic loader core loader must coordinate loading and unloading   */
462 /*    dependent object files with the client side of the dynamic loader.     */
463 /*    This allows the client to keep its bookkeeping information up to date  */
464 /*    with what is currently loaded on the target architecture.              */
465 /*                                                                           */
466 /*    For instance, the client may need to interact with a file system or    */
467 /*    registry.  The client may also need to update debug information in     */
468 /*    synch with the loading and unloading of shared objects.                */
469 /*                                                                           */
470 /*---------------------------------------------------------------------------*/
471 /*---------------------------------------------------------------------------*/
472 /* DLIF_load_dependent()                                                     */
473 /*                                                                           */
474 /*    Ask client to find and open a dependent file identified by the         */
475 /*    'so_name' parameter, then, if necessary, initiate a DLOAD_load()       */
476 /*    call to actually load the shared object onto the target.  A            */
477 /*    successful load will return a file handle ID that the client can       */
478 /*    associate with the newly loaded file.                                  */
479 /*                                                                           */
480 /*---------------------------------------------------------------------------*/
481 int      DLIF_load_dependent(void* client_handle, const char* so_name);
483 /*---------------------------------------------------------------------------*/
484 /* DLIF_unload_dependent()                                                   */
485 /*                                                                           */
486 /*    Ask client to unload a dependent file identified by the 'file_handle'  */
487 /*    parameter.  Initiate a call to DLOAD_unload() to actually free up      */
488 /*    the target memory that was occupied by the object file.                */
489 /*                                                                           */
490 /*---------------------------------------------------------------------------*/
491 void     DLIF_unload_dependent(void* client_handle, uint32_t file_handle);
493 /*---------------------------------------------------------------------------*/
494 /* Error/Warning Registration Functions                                      */
495 /*                                                                           */
496 /*    The client will maintain an error/warning log.  This will allow the    */
497 /*    core loader to register errors and warnings in the load during a       */
498 /*    given dynamic load.  The client is required to check the log after     */
499 /*    each load attempt to report any problems.                              */
500 /*                                                                           */
501 /*---------------------------------------------------------------------------*/
503 /*---------------------------------------------------------------------------*/
504 /* DLIF_trace()                                                              */
505 /*                                                                           */
506 /*    Client implementation of Trace message output, alternative to printf.  */
507 /*                                                                           */
508 /*---------------------------------------------------------------------------*/
509 void     DLIF_trace(const char *fmt, ...);
511 /*---------------------------------------------------------------------------*/
512 /* Loader Warning Types                                                      */
513 /*---------------------------------------------------------------------------*/
514 typedef enum {
515     DLWT_MISC = 0,              /* Miscellaneous warning                     */
516     DLWT_FILE                   /* Warning missing/invalid file information  */
517 } LOADER_WARNING_TYPE;
519 /*---------------------------------------------------------------------------*/
520 /* DLIF_warning()                                                            */
521 /*                                                                           */
522 /*    Log a warning message with the client's error/warning handling         */
523 /*    infrastructure.                                                        */
524 /*                                                                           */
525 /*---------------------------------------------------------------------------*/
526 void     DLIF_warning(LOADER_WARNING_TYPE wtype, const char *fmt, ...);
528 /*---------------------------------------------------------------------------*/
529 /* Loader Error Types                                                        */
530 /*---------------------------------------------------------------------------*/
531 typedef enum {
532     DLET_MISC = 0,              /* Miscellaneous error                       */
533     DLET_FILE,                  /* Error reading/processing file             */
534     DLET_SYMBOL,                /* Symbol resolution error                   */
535     DLET_RELOC,                 /* Relocation error                          */
536     DLET_MEMORY,                /* Host memory allocation/free error         */
537     DLET_TRGMEM,                /* Target memory allocation/free error       */
538     DLET_DEBUG                  /* Shared object or DLL debug error          */
539 } LOADER_ERROR_TYPE;
541 /*---------------------------------------------------------------------------*/
542 /* DLIF_error()                                                              */
543 /*                                                                           */
544 /*    Log an error message with the client's error/warning handling          */
545 /*    infrastructure.                                                        */
546 /*                                                                           */
547 /*---------------------------------------------------------------------------*/
548 void     DLIF_error(LOADER_ERROR_TYPE etype, const char *fmt, ...);
551 /*---------------------------------------------------------------------------*/
552 /* Dynamic Static Base Table (DSBT) Support Functions                        */
553 /*---------------------------------------------------------------------------*/
554 #define DSBT_INDEX_INVALID        -1
555 #define DSBT_DSBT_BASE_INVALID     0
556 #define DSBT_STATIC_BASE_INVALID   0
558 /*****************************************************************************/
559 /* Core Loader Side of DSBT Support                                          */
560 /*****************************************************************************/
562 /*---------------------------------------------------------------------------*/
563 /* DLOAD_get_dsbt_size()                                                     */
564 /*                                                                           */
565 /*    Query the size of the DSBT associated with a specified file. The       */
566 /*    client will check the size of a module's DSBT before it writes a copy  */
567 /*    of the master DSBT to the module's DSBT. If the module's DSBT is not   */
568 /*    big enough, an error will be emitted and the load will fail.           */
569 /*                                                                           */
570 /*---------------------------------------------------------------------------*/
571 uint32_t  DLOAD_get_dsbt_size(DLOAD_HANDLE handle, int32_t file_handle);
573 /*---------------------------------------------------------------------------*/
574 /* DLOAD_get_dsbt_base()                                                     */
575 /*                                                                           */
576 /*    Find DSBT address for specified file. The client will query for this   */
577 /*    address after allocation and symbol relocation has been completed.     */
578 /*    The client will write a copy of the master DSBT to the returned DSBT   */
579 /*    address if the module's DSBT size is big enough.                       */
580 /*                                                                           */
581 /*---------------------------------------------------------------------------*/
582 BOOL     DLOAD_get_dsbt_base(DLOAD_HANDLE handle, int32_t file_handle,
583                              TARGET_ADDRESS *dsbt_base);
585 /*---------------------------------------------------------------------------*/
586 /* DLOAD_get_static_base()                                                   */
587 /*                                                                           */
588 /*    Find static base for a specified file. The client will query for this  */
589 /*    address after allocation and symbol relocation has been completed.     */
590 /*    The client will use the returned static base value to fill the slot    */
591 /*    in the master DSBT that is associated with this module.                */
592 /*                                                                           */
593 /*---------------------------------------------------------------------------*/
594 BOOL     DLOAD_get_static_base(DLOAD_HANDLE handle, int32_t file_handle,
595                                TARGET_ADDRESS *static_base);
598 /*****************************************************************************/
599 /* Client Side of DSBT Support                                               */
600 /*****************************************************************************/
602 /*---------------------------------------------------------------------------*/
603 /* DLIF_register_dsbt_index_request()                                        */
604 /*                                                                           */
605 /*    Register a request for a DSBT index with the client. A module can      */
606 /*    make a specific DSBT index request or it can allow the client to       */
607 /*    assign a DSBT index on its behalf (requested_dsbt_index == -1). The    */
608 /*    client implementation of this function must check that a specific DSBT */
609 /*    index request does not conflict with a previous specific DSBT index    */
610 /*    request.                                                               */
611 /*                                                                           */
612 /*---------------------------------------------------------------------------*/
613 BOOL     DLIF_register_dsbt_index_request(DLOAD_HANDLE handle,
614                                           const char * requestor_name,
615                                           int32_t      requestor_file_handle,
616                                           int32_t      requested_dsbt_index);
618 /*---------------------------------------------------------------------------*/
619 /* DLIF_assign_dsbt_indices()                                                */
620 /*                                                                           */
621 /*    Bind each module that registered a request for a DSBT index to a       */
622 /*    specific slot in the DSBT. Specific requests for DSBT indices will be  */
623 /*    honored first. Any general requests that remain will be assigned to    */
624 /*    the first available slot in the DSBT.                                  */
625 /*                                                                           */
626 /*---------------------------------------------------------------------------*/
627 void     DLIF_assign_dsbt_indices(void);
629 /*---------------------------------------------------------------------------*/
630 /* DLIF_get_dsbt_index()                                                     */
631 /*                                                                           */
632 /*    Given a module that uses the DSBT model, return the identity of the    */
633 /*    DSBT slot that was assigned to it by the client. This function can     */
634 /*    only be called after the client has assigned DSBT indices to all       */
635 /*    loaded object modules that use the DSBT model. The implementation of   */
636 /*    this function will check that a proper DSBT index has been assigned to */
637 /*    the specified module and an invalid index (-1) if there is a problem.  */
638 /*                                                                           */
639 /*---------------------------------------------------------------------------*/
640 int32_t  DLIF_get_dsbt_index(int32_t file_handle);
642 /*---------------------------------------------------------------------------*/
643 /* DLIF_update_all_dsbts()                                                   */
644 /*                                                                           */
645 /*    Populate the client's model of the master DSBT with the static base    */
646 /*    for each assigned slot in the DSBT, then write a copy of the master    */
647 /*    DSBT to each module's DSBT location. The implementation of this        */
648 /*    function must check the size of each module's DSBT to make sure that   */
649 /*    it is large enough to hold a copy of the master DSBT. The function     */
650 /*    will return FALSE if there is a problem.                               */
651 /*                                                                           */
652 /*---------------------------------------------------------------------------*/
653 BOOL     DLIF_update_all_dsbts(void);
655 #endif