Update QNX IPC loader to RIDL 2.1.0
[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-2015 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>
51 #include "util.h"
53 /* extern int debugging_on; */
55 /*****************************************************************************/
56 /* Specification of Loader File Descriptor.  If client side of the loader    */
57 /* supports virtual memory, this may need to be updated to facilitate the    */
58 /* use of mmap().                                                            */
59 /*****************************************************************************/
60 typedef FILE LOADER_FILE_DESC;
62 static const int LOADER_SEEK_SET = SEEK_SET;
63 static const int LOADER_SEEK_CUR = SEEK_CUR;
64 static const int LOADER_SEEK_END = SEEK_END;
66 /*****************************************************************************/
67 /* TARGET_ADDRESS - type suitable for storing target memory address values.  */
68 /*****************************************************************************/
69 typedef uint32_t TARGET_ADDRESS;
71 /*****************************************************************************/
72 /* Define DLOAD Object Handle                                                */
73 /*****************************************************************************/
74 typedef void * DLOAD_HANDLE;
76 /*****************************************************************************/
77 /* Core Loader Provided API Functions (Core Loader Entry Points)             */
78 /*****************************************************************************/
80 /*---------------------------------------------------------------------------*/
81 /* DLOAD_version()                                                           */
82 /*                                                                           */
83 /*    Return a string constant representation for the version ID of the      */
84 /*    dynamic loader's core loader source code.                              */
85 /*                                                                           */
86 /*---------------------------------------------------------------------------*/
87 #include "version.h"
88 #define DLOAD_version() VERSION
90 /*---------------------------------------------------------------------------*/
91 /* DLOAD_create()                                                            */
92 /*                                                                           */
93 /*    Construct and initialize the dynamic loader core's handle.             */
94 /*                                                                           */
95 /*---------------------------------------------------------------------------*/
96 DLOAD_HANDLE  DLOAD_create(void * client_handle);
98 /*---------------------------------------------------------------------------*/
99 /* DLOAD_destroy()                                                           */
100 /*                                                                           */
101 /*    Destroy and finalize the dynamic loader core's handle.                 */
102 /*                                                                           */
103 /*---------------------------------------------------------------------------*/
104 void     DLOAD_destroy(DLOAD_HANDLE handle);
106 /*---------------------------------------------------------------------------*/
107 /* DLOAD_initialize()                                                        */
108 /*                                                                           */
109 /*    Construct and initialize data structures internal to the dynamic       */
110 /*    loader core.                                                           */
111 /*                                                                           */
112 /*---------------------------------------------------------------------------*/
113 void     DLOAD_initialize(DLOAD_HANDLE handle);
115 /*---------------------------------------------------------------------------*/
116 /* DLOAD_finalize()                                                          */
117 /*                                                                           */
118 /*    Destroy and finalize data structures internal to the dynamic           */
119 /*    loader core.                                                           */
120 /*                                                                           */
121 /*---------------------------------------------------------------------------*/
122 void     DLOAD_finalize(DLOAD_HANDLE handle);
124 /*---------------------------------------------------------------------------*/
125 /* DLOAD_load_symbols()                                                      */
126 /*                                                                           */
127 /*    Load externally visible symbols from the specified file so that they   */
128 /*    can be linked against when another object file is subsequntly loaded.  */
129 /*    External symbols will be made available for global symbol linkage.     */
130 /*                                                                           */
131 /*---------------------------------------------------------------------------*/
132 int32_t  DLOAD_load_symbols(DLOAD_HANDLE handle, LOADER_FILE_DESC* fp);
134 /*---------------------------------------------------------------------------*/
135 /* DLOAD_load()                                                              */
136 /*                                                                           */
137 /*    Dynamically load the specified file and return a file handle for the   */
138 /*    loaded file.  If the load fails, this function will return a value     */
139 /*    zero (0).                                                              */
140 /*                                                                           */
141 /*    The core loader must have read access to the file pointed by fp.       */
142 /*                                                                           */
143 /*---------------------------------------------------------------------------*/
144 int      DLOAD_load(DLOAD_HANDLE handle, LOADER_FILE_DESC* fp);
146 /*---------------------------------------------------------------------------*/
147 /* DLOAD_unload()                                                            */
148 /*                                                                           */
149 /*    Given a file handle ID, unload all object segments associated with     */
150 /*    the identified file and any of its dependents that are not still in    */
151 /*    use.                                                                   */
152 /*                                                                           */
153 /*---------------------------------------------------------------------------*/
154 BOOL     DLOAD_unload(DLOAD_HANDLE handle, uint32_t pseudopid);
156 /*---------------------------------------------------------------------------*/
157 /* DLOAD_get_entry_names_info()                                              */
158 /*                                                                           */
159 /*    Given a file handle, return the number entry points that are           */
160 /*    available in the specified file as well as the max name length.  This  */
161 /*    can then be used by the client to allocate the appropriate amount of   */
162 /*    memory needed to call DLOAD_get_entry_names()                          */
163 /*                                                                           */
164 /*---------------------------------------------------------------------------*/
165 BOOL     DLOAD_get_entry_names_info(DLOAD_HANDLE handle, uint32_t file_handle,
166                                     int32_t *entry_pt_cnt,
167                                     int32_t *entry_pt_max_name_len);
169 /*---------------------------------------------------------------------------*/
170 /* DLOAD_get_entry_names()                                                   */
171 /*                                                                           */
172 /*    Given a file handle, build a list of entry point names that are        */
173 /*    available in the specified file.  This can be used when querying       */
174 /*    the list of global functions available in a shared library.            */
175 /*                                                                           */
176 /*---------------------------------------------------------------------------*/
177 BOOL     DLOAD_get_entry_names(DLOAD_HANDLE handle, uint32_t file_handle,
178                                int32_t* entry_pt_cnt, char*** entry_pt_names);
180 /*---------------------------------------------------------------------------*/
181 /* DLOAD_query_symbol()                                                      */
182 /*                                                                           */
183 /*    Query the value of a symbol that is defined by an object file that     */
184 /*    has previously been loaded.  Boolean return value will be false if     */
185 /*    the symbol is not found.                                               */
186 /*                                                                           */
187 /*---------------------------------------------------------------------------*/
188 BOOL     DLOAD_query_symbol(DLOAD_HANDLE handle, uint32_t file_handle,
189                             const char *sym_name, TARGET_ADDRESS *sym_val);
191 /*---------------------------------------------------------------------------*/
192 /* DLOAD_get_section_info()                                                  */
193 /*                                                                           */
194 /*    Query the value of a section that is defined by an object file that    */
195 /*    has previously been loaded.  Boolean return value will be false if     */
196 /*    the symbol is not found.                                               */
197 /*                                                                           */
198 /*---------------------------------------------------------------------------*/
199 BOOL     DLOAD_get_section_info(DLOAD_HANDLE handle, uint32_t file_handle,
200                                 const char *sect_name,
201                                 TARGET_ADDRESS *sect_val, uint32_t *sect_size);
203 /*---------------------------------------------------------------------------*/
204 /* DLOAD_get_section_offset()                                                  */
205 /*                                                                           */
206 /*    Query the value of a section that is defined by an object file that    */
207 /*    has previously been loaded.  Boolean return value will be false if     */
208 /*    the symbol is not found.                                               */
209 /*                                                                           */
210 /*---------------------------------------------------------------------------*/
211 BOOL     DLOAD_get_section_offset(LOADER_FILE_DESC *fd, char * sect_name,
212                                   uint32_t *sect_offs, uint32_t *sect_size,
213                                   uint32_t *sect_addr);
215 /*---------------------------------------------------------------------------*/
216 /* DLOAD_get_entry_point()                                                   */
217 /*                                                                           */
218 /*    Given a file handle, return the entry point target address associated  */
219 /*    with that object file.  The entry point address value is written to    */
220 /*    *sym_val.  The return value of the function indicates whether the      */
221 /*    file with the specified handle was found or not.                       */
222 /*                                                                           */
223 /*---------------------------------------------------------------------------*/
224 BOOL     DLOAD_get_entry_point(DLOAD_HANDLE handle, uint32_t file_handle,
225                                TARGET_ADDRESS *sym_val);
227 /*---------------------------------------------------------------------------*/
228 /* DLOAD_load_arguments()                                                    */
229 /*                                                                           */
230 /*    Given a file handle, find the object file associated with that handle  */
231 /*    and copy the argc/argv information from the client into that object    */
232 /*    file's .args section. The return value indicates whether the operation */
233 /*    was successful. If there are no loaded object files which match the    */
234 /*    handle or if there is insufficient space in the .args section to hold  */
235 /*    the specified argc/argv information, the function will return false.   */
236 /*                                                                           */
237 /*---------------------------------------------------------------------------*/
238 BOOL DLOAD_load_arguments(DLOAD_HANDLE handle, uint32_t file_handle,
239                            int argc, char** argv);
241 /*---------------------------------------------------------------------------*/
242 /* DLOAD_prepare_for_execution()                                             */
243 /*                                                                           */
244 /*    Given a file handle, prepare for execution :                           */
245 /*     - Return entry point associated with that module in the *sym_val      */
246 /*       output parameter.                                                   */
247 /*     - Write out the given arguments to the .args section contained in the */
248 /*       same module.                                                        */
249 /*     - As a test (for the Reference implementation) read the arguments     */
250 /*       using the DLIF_read_arguments() function and set global argc,argv.  */
251 /*                                                                           */
252 /*    The return value of the function indicates whether the file with the   */
253 /*    specified handle was found or not.                                     */
254 /*                                                                           */
255 /*---------------------------------------------------------------------------*/
256 BOOL     DLOAD_prepare_for_execution(DLOAD_HANDLE handle, uint32_t file_handle,
257                                TARGET_ADDRESS *sym_val,
258                                int argc, char** argv);
261 /*****************************************************************************/
262 /* Client Provided API Functions                                             */
263 /*****************************************************************************/
265 /*---------------------------------------------------------------------------*/
266 /* File I/O                                                                  */
267 /*                                                                           */
268 /*    The client side of the dynamic loader must provide basic file I/O      */
269 /*    capabilities so that the core loader has random access into any        */
270 /*    object file that it is asked to load.                                  */
271 /*                                                                           */
272 /*    The client side of the dynamic loader must provide a definition of     */
273 /*    the LOADER_FILE_DESC in dload_filedefs.h.  This allows the core loader */
274 /*    to be independent of how the client accesses raw data in an object     */
275 /*    file.                                                                  */
276 /*                                                                           */
277 /*---------------------------------------------------------------------------*/
279 /*---------------------------------------------------------------------------*/
280 /* DLIF_fseek()                                                              */
281 /*                                                                           */
282 /*    Seek to a position in a file (accessed via 'stream') based on the      */
283 /*    values for offset and origin.                                          */
284 /*                                                                           */
285 /*---------------------------------------------------------------------------*/
286 int      DLIF_fseek(LOADER_FILE_DESC *stream, int32_t offset, int origin);
288 /*---------------------------------------------------------------------------*/
289 /* DLIF_ftell()                                                              */
290 /*                                                                           */
291 /*    Return the current file position in the file identified in the         */
292 /*    LOADER_FILE_DESC pointed to by 'stream'.                               */
293 /*                                                                           */
294 /*---------------------------------------------------------------------------*/
295 int32_t  DLIF_ftell(LOADER_FILE_DESC *stream);
297 /*---------------------------------------------------------------------------*/
298 /* DLIF_fread()                                                              */
299 /*                                                                           */
300 /*    Read 'size' * 'nmemb' bytes of data from the file identified in the    */
301 /*    LOADER_FILE_DESC object pointed to by 'stream', and write that data    */
302 /*    into the memory accessed via 'ptr'.                                    */
303 /*                                                                           */
304 /*---------------------------------------------------------------------------*/
305 size_t   DLIF_fread(void *ptr, size_t size, size_t nmemb,
306                     LOADER_FILE_DESC *stream);
308 /*---------------------------------------------------------------------------*/
309 /* DLIF_fclose()                                                             */
310 /*                                                                           */
311 /*    Close a file that was opened on behalf of the core loader. Ownership   */
312 /*    of the file pointer in question belongs to the core loader, but the    */
313 /*    client has exclusive access to the file system.                        */
314 /*                                                                           */
315 /*---------------------------------------------------------------------------*/
316 int      DLIF_fclose(LOADER_FILE_DESC *fd);
318 /*---------------------------------------------------------------------------*/
319 /* Host Memory Management                                                    */
320 /*                                                                           */
321 /*    Allocate and free host memory as needed for the dynamic loader's       */
322 /*    internal data structures.  If the dynamic loader resides on the        */
323 /*    target architecture, then this memory is allocated from a target       */
324 /*    memory heap that must be managed separately from memory that is        */
325 /*    allocated for a dynamically loaded object file.                        */
326 /*                                                                           */
327 /*---------------------------------------------------------------------------*/
329 /*---------------------------------------------------------------------------*/
330 /* DLIF_malloc()                                                             */
331 /*                                                                           */
332 /*    Allocate 'size' bytes of memory space that is usable as scratch space  */
333 /*    (appropriate for the loader's internal data structures) by the dynamic */
334 /*    loader.                                                                */
335 /*                                                                           */
336 /*    If allocation fails, this function must not return.                    */
337 /*                                                                           */
338 /*---------------------------------------------------------------------------*/
339 void*    DLIF_malloc(size_t size);
341 /*---------------------------------------------------------------------------*/
342 /* DLIF_free()                                                               */
343 /*                                                                           */
344 /*    Free memory space that was previously allocated by DLIF_malloc().      */
345 /*                                                                           */
346 /*---------------------------------------------------------------------------*/
347 void     DLIF_free(void* ptr);
349 /*---------------------------------------------------------------------------*/
350 /* Target Memory Allocator Interface                                         */
351 /*                                                                           */
352 /*    The client side of the dynamic loader must create and maintain an      */
353 /*    infrastructure to manage target memory.  The client must keep track    */
354 /*    of what target memory is associated with each object segment,          */
355 /*    allocating target memory for newly loaded objects and release target   */
356 /*    memory that is associated with objects that are being unloaded from    */
357 /*    the target architecture.                                               */
358 /*                                                                           */
359 /*    The two client-supplied functions, DLIF_allocate() and DLIF_release(), */
360 /*    are used by the core loader to interface into the client side's        */
361 /*    target memory allocator infrastructure.                                */
362 /*                                                                           */
363 /*---------------------------------------------------------------------------*/
365 /*---------------------------------------------------------------------------*/
366 /* DLOAD_SEGMENT_FLAGS - segment characteristics.                            */
367 /*---------------------------------------------------------------------------*/
368 typedef uint32_t DLOAD_SEGMENT_FLAGS;
369 static const int DLOAD_SF_executable = 0x1;  /* Memory must be executable    */
370 static const int DLOAD_SF_relocatable = 0x2; /* Segment must be relocatable  */
372 /*---------------------------------------------------------------------------*/
373 /* DLOAD_MEMORY_SEGMENT - Define structure to represent placement and size   */
374 /*      details of a segment to be loaded.                                   */
375 /*---------------------------------------------------------------------------*/
376 struct DLOAD_MEMORY_SEGMENT
378    uint32_t       target_page;          /* requested/returned memory page    */
379    TARGET_ADDRESS target_address;       /* requested/returned address        */
380    uint32_t       objsz_in_bytes;       /* size of init'd part of segment    */
381    uint32_t       memsz_in_bytes;       /* size of memory block for segment  */
382 //   DLOAD_SEGMENT_FLAGS flags;           /* allocation request flags          */
383 };
385 /*---------------------------------------------------------------------------*/
386 /* DLOAD_MEMORY_REQUEST - Define structure to represent a target memory      */
387 /*      request made by the core loader on behalf of a segment that the      */
388 /*      loader needs to relocate and write into target memory.               */
389 /*---------------------------------------------------------------------------*/
390 struct DLOAD_MEMORY_REQUEST
392    LOADER_FILE_DESC            *fp;           /* file being loaded           */
393    struct DLOAD_MEMORY_SEGMENT *segment;      /* obj for req/ret alloc       */
394    void                        *host_address; /* ret hst ptr from DLIF_copy()*/
395    BOOL                         is_loaded;    /* returned as true if segment */
396                                               /* is already in target memory */
397    uint32_t                     offset;       /* file offset of segment's    */
398                                               /* raw data                    */
399    uint32_t                     flip_endian;  /* endianness of trg opp host  */
400    DLOAD_SEGMENT_FLAGS          flags;        /* allocation request flags    */
401    uint32_t                     align;        /* align of trg memory block   */
402 };
404 /*---------------------------------------------------------------------------*/
405 /* DLIF_initMem()                                                            */
406 /*                                                                           */
407 /*    Given an address and size, initialize the memory used to load the      */
408 /*    dynamic segments.  This should be called by the client before          */
409 /*    beginning dynamic loading.                                             */
410 /*                                                                           */
411 /*---------------------------------------------------------------------------*/
412 BOOL     DLIF_initMem(void* client_handle, uint32_t dynMemAddr, uint32_t size);
414 /*---------------------------------------------------------------------------*/
415 /* DLIF_deinitMem()                                                          */
416 /*                                                                           */
417 /*    De-initialize the memory used to load the dynamic segments.            */
418 /*                                                                           */
419 /*---------------------------------------------------------------------------*/
420 BOOL     DLIF_deinitMem(void* client_handle);
422 /*---------------------------------------------------------------------------*/
423 /* DLIF_allocate()                                                           */
424 /*                                                                           */
425 /*    Given a DLOAD_MEMORY_REQUEST created by the core loader, allocate      */
426 /*    target memory to fulfill the request using the target memory           */
427 /*    management infrastrucutre on the client side of the dynamic loader.    */
428 /*    The contents of the DLOAD_MEMORY_REQUEST will be updated per the       */
429 /*    details of a successful allocation.  The allocated page and address    */
430 /*    can be found in the DLOAD_MEMORY_SEGMENT attached to the request.      */
431 /*    The boolean return value reflects whether the allocation was           */
432 /*    successful or not.                                                     */
433 /*                                                                           */
434 /*---------------------------------------------------------------------------*/
435 BOOL     DLIF_allocate(void * client_handle, struct DLOAD_MEMORY_REQUEST *req);
437 /*---------------------------------------------------------------------------*/
438 /* DLIF_release()                                                            */
439 /*                                                                           */
440 /*    Given a DLOAD_MEMORY_SEGMENT description, free the target memory       */
441 /*    associated with the segment using the target memory management         */
442 /*    infrastructure on the client side of the dynamic loader.               */
443 /*                                                                           */
444 /*---------------------------------------------------------------------------*/
445 BOOL     DLIF_release(void* client_handle, struct DLOAD_MEMORY_SEGMENT* ptr);
447 /*---------------------------------------------------------------------------*/
448 /* Target Memory Access / Write Services                                     */
449 /*                                                                           */
450 /*    The client side's target memory allocator infrastructure communicates  */
451 /*    with the core loader through the DLOAD_MEMORY_REQUEST and              */
452 /*    DLOAD_MEMORY_SEGMENT data structures defined above.  To complete the   */
453 /*    loading of an object segment, the segment may need to be relocated     */
454 /*    before it is actually written to target memory in the space that was   */
455 /*    allocated for it by DLIF_allocate().                                   */
456 /*                                                                           */
457 /*    The client side of the dynamic loader provides two functions to help   */
458 /*    complete the process of loading an object segment, DLIF_copy() and     */
459 /*    DLIF_write().                                                          */
460 /*                                                                           */
461 /*    These functions help to make the core loader truly independent of      */
462 /*    whether it is running on the host or target architecture and how the   */
463 /*    client provides for reading/writing from/to target memory.             */
464 /*                                                                           */
465 /*---------------------------------------------------------------------------*/
466 /*---------------------------------------------------------------------------*/
467 /* DLIF_copy()                                                               */
468 /*                                                                           */
469 /*    Copy segment data from the object file described in the 'fp' and       */
470 /*    'offset' of the DLOAD_MEMORY_REQUEST into host accessible memory so    */
471 /*    that it can relocated or otherwise manipulated by the core loader.     */
472 /*                                                                           */
473 /*---------------------------------------------------------------------------*/
474 BOOL     DLIF_copy(void* client_handle, struct DLOAD_MEMORY_REQUEST* req);
476 /*---------------------------------------------------------------------------*/
477 /* DLIF_write()                                                              */
478 /*                                                                           */
479 /*    Once the segment data described in the DLOAD_MEMORY_REQUEST is ready   */
480 /*    (relocated, if needed), write the segment contents to the target       */
481 /*    memory identified in the DLOAD_MEMORY_SEGMENT attached to the request. */
482 /*                                                                           */
483 /*    After the segment contents have been written to target memory, the     */
484 /*    core loader should discard the DLOAD_MEMORY_REQUEST object, but retain */
485 /*    the DLOAD_MEMORY_SEGMENT object so that the target memory associated   */
486 /*    with the segment can be releases when the segment is unloaded.         */
487 /*                                                                           */
488 /*---------------------------------------------------------------------------*/
489 BOOL     DLIF_write(void* client_handle, struct DLOAD_MEMORY_REQUEST* req);
491 /*---------------------------------------------------------------------------*/
492 /* DLIF_read()                                                               */
493 /*                                                                           */
494 /*    Given a host accessible buffer, read content of indicated target       */
495 /*    memory address into the buffer.                                        */
496 /*---------------------------------------------------------------------------*/
497 BOOL     DLIF_read(void* client_handle,
498                    void *ptr, size_t size, size_t nmemb, TARGET_ADDRESS src);
500 /*---------------------------------------------------------------------------*/
501 /* DLIF_memcpy()                                                             */
502 /*                                                                           */
503 /*    Given a host accessible buffer, copy content from specified buffer     */
504 /*    into target memory.                                                    */
505 /*---------------------------------------------------------------------------*/
506 BOOL     DLIF_memcpy(void* client_handle, void *to, void *from, size_t size);
508 /*---------------------------------------------------------------------------*/
509 /* DLIF_execute()                                                            */
510 /*                                                                           */
511 /*    Start execution on the target architecture from given 'exec_addr'.     */
512 /*    If the dynamic loader is running on the target architecture, this can  */
513 /*    be effected as a simple function call.                                 */
514 /*                                                                           */
515 /*---------------------------------------------------------------------------*/
516 int32_t  DLIF_execute(void* client_handle, TARGET_ADDRESS exec_addr);
518 /*---------------------------------------------------------------------------*/
519 /* Loading and Unloading of Dependent Files                                  */
520 /*                                                                           */
521 /*    The dynamic loader core loader must coordinate loading and unloading   */
522 /*    dependent object files with the client side of the dynamic loader.     */
523 /*    This allows the client to keep its bookkeeping information up to date  */
524 /*    with what is currently loaded on the target architecture.              */
525 /*                                                                           */
526 /*    For instance, the client may need to interact with a file system or    */
527 /*    registry.  The client may also need to update debug information in     */
528 /*    synch with the loading and unloading of shared objects.                */
529 /*                                                                           */
530 /*---------------------------------------------------------------------------*/
531 /*---------------------------------------------------------------------------*/
532 /* DLIF_load_dependent()                                                     */
533 /*                                                                           */
534 /*    Ask client to find and open a dependent file identified by the         */
535 /*    'so_name' parameter, then, if necessary, initiate a DLOAD_load()       */
536 /*    call to actually load the shared object onto the target.  A            */
537 /*    successful load will return a file handle ID that the client can       */
538 /*    associate with the newly loaded file.                                  */
539 /*                                                                           */
540 /*---------------------------------------------------------------------------*/
541 int      DLIF_load_dependent(void* client_handle, const char* so_name);
543 /*---------------------------------------------------------------------------*/
544 /* DLIF_unload_dependent()                                                   */
545 /*                                                                           */
546 /*    Ask client to unload a dependent file identified by the 'file_handle'  */
547 /*    parameter.  Initiate a call to DLOAD_unload() to actually free up      */
548 /*    the target memory that was occupied by the object file.                */
549 /*                                                                           */
550 /*---------------------------------------------------------------------------*/
551 void     DLIF_unload_dependent(void* client_handle, uint32_t file_handle);
553 /*---------------------------------------------------------------------------*/
554 /* Error/Warning Registration Functions                                      */
555 /*                                                                           */
556 /*    The client will maintain an error/warning log.  This will allow the    */
557 /*    core loader to register errors and warnings in the load during a       */
558 /*    given dynamic load.  The client is required to check the log after     */
559 /*    each load attempt to report any problems.                              */
560 /*                                                                           */
561 /*---------------------------------------------------------------------------*/
564 /*---------------------------------------------------------------------------*/
565 /* Loader Warning Types                                                      */
566 /*---------------------------------------------------------------------------*/
567 typedef enum {
568     DLWT_MISC = 0,              /* Miscellaneous warning                     */
569     DLWT_FILE                   /* Warning missing/invalid file information  */
570 } LOADER_WARNING_TYPE;
572 /*---------------------------------------------------------------------------*/
573 /* DLIF_warning()                                                            */
574 /*                                                                           */
575 /*    Log a warning message with the client's error/warning handling         */
576 /*    infrastructure.                                                        */
577 /*                                                                           */
578 /*---------------------------------------------------------------------------*/
579 void     DLIF_warning(LOADER_WARNING_TYPE wtype, const char *fmt, ...);
581 /*---------------------------------------------------------------------------*/
582 /* Loader Error Types                                                        */
583 /*---------------------------------------------------------------------------*/
584 typedef enum {
585     DLET_MISC = 0,              /* Miscellaneous error                       */
586     DLET_FILE,                  /* Error reading/processing file             */
587     DLET_SYMBOL,                /* Symbol resolution error                   */
588     DLET_RELOC,                 /* Relocation error                          */
589     DLET_MEMORY,                /* Host memory allocation/free error         */
590     DLET_TRGMEM,                /* Target memory allocation/free error       */
591     DLET_DEBUG                  /* Shared object or DLL debug error          */
592 } LOADER_ERROR_TYPE;
594 /*---------------------------------------------------------------------------*/
595 /* DLIF_error()                                                              */
596 /*                                                                           */
597 /*    Log an error message with the client's error/warning handling          */
598 /*    infrastructure.                                                        */
599 /*                                                                           */
600 /*---------------------------------------------------------------------------*/
601 void     DLIF_error(LOADER_ERROR_TYPE etype, const char *fmt, ...);
603 /*---------------------------------------------------------------------------*/
604 /* DLIF_exit()                                                               */
605 /*                                                                           */
606 /*    Abort the loader following a fatal error.                              */
607 /*                                                                           */
608 /*---------------------------------------------------------------------------*/
609 void     DLIF_exit(int code);
611 /*---------------------------------------------------------------------------*/
612 /* DLIF_trace()                                                              */
613 /*                                                                           */
614 /*    Log a message with the client's trace handling infrastructure.         */
615 /*                                                                           */
616 /*---------------------------------------------------------------------------*/
617 void     DLIF_trace(const char *fmt, ...);
619 /*---------------------------------------------------------------------------*/
620 /* Dynamic Static Base Table (DSBT) Support Functions                        */
621 /*---------------------------------------------------------------------------*/
622 #define DSBT_INDEX_INVALID        -1
623 #define DSBT_DSBT_BASE_INVALID     0
624 #define DSBT_STATIC_BASE_INVALID   0
626 /*****************************************************************************/
627 /* Core Loader Side of DSBT Support                                          */
628 /*****************************************************************************/
630 /*---------------------------------------------------------------------------*/
631 /* DLOAD_get_dsbt_size()                                                     */
632 /*                                                                           */
633 /*    Query the size of the DSBT associated with a specified file. The       */
634 /*    client will check the size of a module's DSBT before it writes a copy  */
635 /*    of the master DSBT to the module's DSBT. If the module's DSBT is not   */
636 /*    big enough, an error will be emitted and the load will fail.           */
637 /*                                                                           */
638 /*---------------------------------------------------------------------------*/
639 uint32_t  DLOAD_get_dsbt_size(DLOAD_HANDLE handle, int32_t file_handle);
641 /*---------------------------------------------------------------------------*/
642 /* DLOAD_get_dsbt_base()                                                     */
643 /*                                                                           */
644 /*    Find DSBT address for specified file. The client will query for this   */
645 /*    address after allocation and symbol relocation has been completed.     */
646 /*    The client will write a copy of the master DSBT to the returned DSBT   */
647 /*    address if the module's DSBT size is big enough.                       */
648 /*                                                                           */
649 /*---------------------------------------------------------------------------*/
650 BOOL     DLOAD_get_dsbt_base(DLOAD_HANDLE handle, int32_t file_handle,
651                              TARGET_ADDRESS *dsbt_base);
653 /*---------------------------------------------------------------------------*/
654 /* DLOAD_get_static_base()                                                   */
655 /*                                                                           */
656 /*    Find static base for a specified file. The client will query for this  */
657 /*    address after allocation and symbol relocation has been completed.     */
658 /*    The client will use the returned static base value to fill the slot    */
659 /*    in the master DSBT that is associated with this module.                */
660 /*                                                                           */
661 /*---------------------------------------------------------------------------*/
662 BOOL     DLOAD_get_static_base(DLOAD_HANDLE handle, int32_t file_handle,
663                                TARGET_ADDRESS *static_base);
666 /*****************************************************************************/
667 /* Client Side of DSBT Support                                               */
668 /*****************************************************************************/
670 /*---------------------------------------------------------------------------*/
671 /* DLIF_register_dsbt_index_request()                                        */
672 /*                                                                           */
673 /*    Register a request for a DSBT index with the client. A module can      */
674 /*    make a specific DSBT index request or it can allow the client to       */
675 /*    assign a DSBT index on its behalf (requested_dsbt_index == -1). The    */
676 /*    client implementation of this function must check that a specific DSBT */
677 /*    index request does not conflict with a previous specific DSBT index    */
678 /*    request.                                                               */
679 /*                                                                           */
680 /*---------------------------------------------------------------------------*/
681 BOOL     DLIF_register_dsbt_index_request(DLOAD_HANDLE handle,
682                                           const char * requestor_name,
683                                           int32_t      requestor_file_handle,
684                                           int32_t      requested_dsbt_index);
686 /*---------------------------------------------------------------------------*/
687 /* DLIF_assign_dsbt_indices()                                                */
688 /*                                                                           */
689 /*    Bind each module that registered a request for a DSBT index to a       */
690 /*    specific slot in the DSBT. Specific requests for DSBT indices will be  */
691 /*    honored first. Any general requests that remain will be assigned to    */
692 /*    the first available slot in the DSBT.                                  */
693 /*                                                                           */
694 /*---------------------------------------------------------------------------*/
695 void     DLIF_assign_dsbt_indices(void);
697 /*---------------------------------------------------------------------------*/
698 /* DLIF_get_dsbt_index()                                                     */
699 /*                                                                           */
700 /*    Given a module that uses the DSBT model, return the identity of the    */
701 /*    DSBT slot that was assigned to it by the client. This function can     */
702 /*    only be called after the client has assigned DSBT indices to all       */
703 /*    loaded object modules that use the DSBT model. The implementation of   */
704 /*    this function will check that a proper DSBT index has been assigned to */
705 /*    the specified module and an invalid index (-1) if there is a problem.  */
706 /*                                                                           */
707 /*---------------------------------------------------------------------------*/
708 int32_t  DLIF_get_dsbt_index(int32_t file_handle);
710 /*---------------------------------------------------------------------------*/
711 /* DLIF_update_all_dsbts()                                                   */
712 /*                                                                           */
713 /*    Populate the client's model of the master DSBT with the static base    */
714 /*    for each assigned slot in the DSBT, then write a copy of the master    */
715 /*    DSBT to each module's DSBT location. The implementation of this        */
716 /*    function must check the size of each module's DSBT to make sure that   */
717 /*    it is large enough to hold a copy of the master DSBT. The function     */
718 /*    will return FALSE if there is a problem.                               */
719 /*                                                                           */
720 /*---------------------------------------------------------------------------*/
721 BOOL     DLIF_update_all_dsbts(void);
723 #endif