1 /*
2  *  Copyright 2001-2008 Texas Instruments - http://www.ti.com/
3  *
4  *  Licensed under the Apache License, Version 2.0 (the "License");
5  *  you may not use this file except in compliance with the License.
6  *  You may obtain a copy of the License at
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  *  Unless required by applicable law or agreed to in writing, software
11  *  distributed under the License is distributed on an "AS IS" BASIS,
12  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  *  See the License for the specific language governing permissions and
14  *  limitations under the License.
15  */
16 
17 
18 
19 #ifndef _DYNAMIC_LOADER_H_
20 #define _DYNAMIC_LOADER_H_
21 #include <stdarg.h>
22 #ifndef __KERNEL__
23 #include <stdint.h>
24 #else
25 #include <linux/types.h>
26 #endif
27 
28 #ifdef __cplusplus
29 extern "C" {			/* C-only version */
30 #endif
31 
32 /* Optional optimization defines */
33 #define OPT_ELIMINATE_EXTRA_DLOAD 1
34 /* #define OPT_ZERO_COPY_LOADER 1 */
35 
36 
37 /*
38  * Dynamic Loader
39  *
40  * The function of the dynamic loader is to load a "module" containing
41  * instructions
42  * for a "target" processor into that processor.  In the process it assigns
43  * memory
44  * for the module, resolves symbol references made by the module, and remembers
45  * symbols defined by the module.
46  *
47  * The dynamic loader is parameterized for a particular system by 4 classes
48  * that supply
49  * the module and system specific functions it requires
50  */
51 	/* The read functions for the module image to be loaded */
52 	struct Dynamic_Loader_Stream;
53 	/*typedef struct Dynamic_Loader_Stream Dynamic_Loader_Stream;*/
54 
55 	/* This class defines "host" symbol and support functions */
56 	struct Dynamic_Loader_Sym;
57 	/*typedef struct Dynamic_Loader_Sym Dynamic_Loader_Sym;*/
58 
59 	/* This class defines the allocator for "target" memory */
60 	struct Dynamic_Loader_Allocate;
61 	/*typedef struct Dynamic_Loader_Allocate Dynamic_Loader_Allocate;*/
62 
63 	/* This class defines the copy-into-target-memory functions */
64 	struct Dynamic_Loader_Initialize;
65 	/*typedef struct Dynamic_Loader_Initialize Dynamic_Loader_Initialize;*/
66 
67 /*
68  * Option flags to modify the behavior of module loading
69  */
70 #define DLOAD_INITBSS 0x1	/* initialize BSS sections to zero */
71 #define DLOAD_BIGEND 0x2	/* require big-endian load module */
72 #define DLOAD_LITTLE 0x4	/* require little-endian load module */
73 
74 	typedef void *DLOAD_mhandle;	/* module handle for loaded modules */
75 
76 /*****************************************************************************
77  * Procedure Dynamic_Load_Module
78  *
79  * Parameters:
80  *  module  The input stream that supplies the module image
81  *  syms    Host-side symbol table and malloc/free functions
82  *  alloc   Target-side memory allocation
83  *  init    Target-side memory initialization, or NULL for symbol read only
84  *  options Option flags DLOAD_*
85  *  mhandle A module handle for use with Dynamic_Unload
86  *
87  * Effect:
88  *  The module image is read using *module.  Target storage for the new image is
89  * obtained from *alloc.  Symbols defined and referenced by the module are
90  * managed using *syms.  The image is then relocated and references resolved
91  * as necessary, and the resulting executable bits are placed into target memory
92  * using *init.
93  *
94  * Returns:
95  *  On a successful load, a module handle is placed in *mhandle, and zero is
96  * returned.  On error, the number of errors detected is returned.  Individual
97  * errors are reported during the load process using syms->Error_Report().
98  *****************************************************************************/
99 	extern int Dynamic_Load_Module(
100 					/* the source for the module image*/
101 					struct Dynamic_Loader_Stream * module,
102 					   /* host support for symbols and storage*/
103 				       struct Dynamic_Loader_Sym * syms,
104 					   /* the target memory allocator*/
105 				       struct Dynamic_Loader_Allocate * alloc,
106 					   /* the target memory initializer*/
107 				       struct Dynamic_Loader_Initialize * init,
108 				       unsigned options,	/* option flags*/
109 				       DLOAD_mhandle * mhandle	/* the returned module handle*/
110 	    );
111 
112 #ifdef OPT_ELIMINATE_EXTRA_DLOAD
113 /*****************************************************************************
114  * Procedure Dynamic_Open_Module
115  *
116  * Parameters:
117  *  module  The input stream that supplies the module image
118  *  syms    Host-side symbol table and malloc/free functions
119  *  alloc   Target-side memory allocation
120  *  init    Target-side memory initialization, or NULL for symbol read only
121  *  options Option flags DLOAD_*
122  *  mhandle A module handle for use with Dynamic_Unload
123  *
124  * Effect:
125  *  The module image is read using *module.  Target storage for the new image is
126  * obtained from *alloc.  Symbols defined and referenced by the module are
127  * managed using *syms.  The image is then relocated and references resolved
128  * as necessary, and the resulting executable bits are placed into target memory
129  * using *init.
130  *
131  * Returns:
132  *  On a successful load, a module handle is placed in *mhandle, and zero is
133  * returned.  On error, the number of errors detected is returned.  Individual
134  * errors are reported during the load process using syms->Error_Report().
135  *****************************************************************************/
136         extern int Dynamic_Open_Module(struct Dynamic_Loader_Stream * module,  // the source for the module image
137                                        struct Dynamic_Loader_Sym * syms,       // host support for symbols and storage
138                                        struct Dynamic_Loader_Allocate * alloc, // the target memory allocator
139                                        struct Dynamic_Loader_Initialize * init,        // the target memory initializer
140                                        unsigned options,        // option flags
141                                        DLOAD_mhandle * mhandle  // the returned module handle
142             );
143 #endif
144 
145 /*****************************************************************************
146  * Procedure Dynamic_Unload_Module
147  *
148  * Parameters:
149  *  mhandle A module handle from Dynamic_Load_Module
150  *  syms    Host-side symbol table and malloc/free functions
151  *  alloc   Target-side memory allocation
152  *
153  * Effect:
154  *  The module specified by mhandle is unloaded.  Unloading causes all
155  * target memory to be deallocated, all symbols defined by the module to
156  * be purged, and any host-side storage used by the dynamic loader for
157  * this module to be released.
158  *
159  * Returns:
160  *  Zero for success. On error, the number of errors detected is returned.
161  * Individual errors are reported using syms->Error_Report().
162  *****************************************************************************/
163 	extern int Dynamic_Unload_Module(DLOAD_mhandle mhandle,	/* the module
164 															   handle*/
165 					 /* host support for symbols and storage*/
166 					 struct Dynamic_Loader_Sym * syms,
167 					 /* the target memory allocator*/
168 					 struct Dynamic_Loader_Allocate * alloc,
169 					 /* the target memory initializer*/
170 					 struct Dynamic_Loader_Initialize * init
171 	    );
172 
173 /*****************************************************************************
174  *****************************************************************************
175  * A class used by the dynamic loader for input of the module image
176  *****************************************************************************
177  *****************************************************************************/
178 	struct Dynamic_Loader_Stream {
179 /* public: */
180     /*************************************************************************
181      * read_buffer
182      *
183      * PARAMETERS :
184      *  buffer  Pointer to the buffer to fill
185      *  bufsiz  Amount of data desired in sizeof() units
186      *
187      * EFFECT :
188      *  Reads the specified amount of data from the module input stream
189      * into the specified buffer.  Returns the amount of data read in sizeof()
190      * units (which if less than the specification, represents an error).
191      *
192      * NOTES:
193      *  In release 1 increments the file position by the number of bytes read
194      *
195      *************************************************************************/
196 		int (*read_buffer) (struct Dynamic_Loader_Stream * thisptr,
197 				    void *buffer, unsigned bufsiz);
198 
199     /*************************************************************************
200      * set_file_posn (release 1 only)
201      *
202      * PARAMETERS :
203      *  posn  Desired file position relative to start of file in sizeof() units.
204      *
205      * EFFECT :
206      *  Adjusts the internal state of the stream object so that the next
207      * read_buffer call will begin to read at the specified offset from
208      * the beginning of the input module.  Returns 0 for success, non-zero
209      * for failure.
210      *
211      *************************************************************************/
212 		int (*set_file_posn) (struct Dynamic_Loader_Stream * thisptr,
213 					unsigned int posn);	/* to be eliminated in release 2*/
214 
215 	};
216 
217 /*****************************************************************************
218  *****************************************************************************
219  * A class used by the dynamic loader for symbol table support and
220  * miscellaneous host-side functions
221  *****************************************************************************
222  *****************************************************************************/
223 #ifndef __KERNEL__
224 	typedef uint32_t LDR_ADDR;
225 #else
226 	typedef u32 LDR_ADDR;
227 #endif
228 
229 /*
230  * the structure of a symbol known to the dynamic loader
231  */
232 	struct dynload_symbol {
233 		LDR_ADDR value;
234 	} ;
235 
236 	struct Dynamic_Loader_Sym {
237 /* public: */
238     /*************************************************************************
239      * Find_Matching_Symbol
240      *
241      * PARAMETERS :
242      *  name    The name of the desired symbol
243      *
244      * EFFECT :
245      *  Locates a symbol matching the name specified.  A pointer to the
246      * symbol is returned if it exists; 0 is returned if no such symbol is
247      * found.
248      *
249      *************************************************************************/
250 		struct dynload_symbol *(*Find_Matching_Symbol)
251 			(struct Dynamic_Loader_Sym *
252 							 thisptr,
253 							 const char *name);
254 
255     /*************************************************************************
256      * Add_To_Symbol_Table
257      *
258      * PARAMETERS :
259      *  nname       Pointer to the name of the new symbol
260      *  moduleid    An opaque module id assigned by the dynamic loader
261      *
262      * EFFECT :
263      *  The new symbol is added to the table.  A pointer to the symbol is
264      * returned, or NULL is returned for failure.
265      *
266      * NOTES:
267      *  It is permissible for this function to return NULL; the effect is that
268      * the named symbol will not be available to resolve references in
269      * subsequent loads.  Returning NULL will not cause the current load
270      * to fail.
271      *************************************************************************/
272 		struct dynload_symbol *(*Add_To_Symbol_Table)
273 						(struct Dynamic_Loader_Sym *
274 							thisptr,
275 							const char *nname,
276 							unsigned moduleid);
277 
278     /*************************************************************************
279      * Purge_Symbol_Table
280      *
281      * PARAMETERS :
282      *  moduleid    An opaque module id assigned by the dynamic loader
283      *
284      * EFFECT :
285      *  Each symbol in the symbol table whose moduleid matches the argument
286      * is removed from the table.
287      *************************************************************************/
288 		void (*Purge_Symbol_Table) (struct Dynamic_Loader_Sym * thisptr,
289 					    unsigned moduleid);
290 
291     /*************************************************************************
292      * Allocate
293      *
294      * PARAMETERS :
295      *  memsiz  size of desired memory in sizeof() units
296      *
297      * EFFECT :
298      *  Returns a pointer to some "host" memory for use by the dynamic
299      * loader, or NULL for failure.
300      * This function is serves as a replaceable form of "malloc" to
301      * allow the user to configure the memory usage of the dynamic loader.
302      *************************************************************************/
303 		void *(*Allocate) (struct Dynamic_Loader_Sym * thisptr,
304 				   unsigned memsiz);
305 
306     /*************************************************************************
307      * Deallocate
308      *
309      * PARAMETERS :
310      *  memptr  pointer to previously allocated memory
311      *
312      * EFFECT :
313      *  Releases the previously allocated "host" memory.
314      *************************************************************************/
315 		void (*Deallocate) (struct Dynamic_Loader_Sym * thisptr, void *memptr);
316 
317     /*************************************************************************
318      * Error_Report
319      *
320      * PARAMETERS :
321      *  errstr  pointer to an error string
322      *  args    additional arguments
323      *
324      * EFFECT :
325      *  This function provides an error reporting interface for the dynamic
326      * loader.  The error string and arguments are designed as for the
327      * library function vprintf.
328      *************************************************************************/
329 		void (*Error_Report) (struct Dynamic_Loader_Sym * thisptr,
330 				      const char *errstr, va_list args);
331 
332 	};			/* class Dynamic_Loader_Sym */
333 
334 /*****************************************************************************
335  *****************************************************************************
336  * A class used by the dynamic loader to allocate and deallocate target memory.
337  *****************************************************************************
338  *****************************************************************************/
339 
340 	struct LDR_SECTION_INFO {
341 		/* Name of the memory section assigned at build time */
342 		const char *name;
343 		LDR_ADDR run_addr;	/* execution address of the section */
344 		LDR_ADDR load_addr;	/* load address of the section */
345 		LDR_ADDR size;	/* size of the section in addressable units */
346 /* #ifndef _BIG_ENDIAN *//* _BIG_ENDIAN Not defined by bridge driver */
347 #ifdef __KERNEL__
348 		u16 page;	/* memory page or view */
349 		u16 type;	/* one of the section types below */
350 #else
351 		uint16_t page;	/* memory page or view */
352 		uint16_t type;	/* one of the section types below */
353 #endif
354 /*#else
355 #ifdef __KERNEL__
356 		u16 type;*/	/* one of the section types below */
357 /*		u16 page;*/	/* memory page or view */
358 /*#else
359 		uint16_t type;*//* one of the section types below */
360 /*		uint16_t page;*//* memory page or view */
361 /*#endif
362 #endif*//* _BIG_ENDIAN Not defined by bridge driver */
363 		/* a context field for use by Dynamic_Loader_Allocate;
364 					   ignored but maintained by the dynamic loader */
365 #ifdef __KERNEL__
366 		u32 context;
367 #else
368 		uintptr_t context;
369 #endif
370 	} ;
371 
372 /* use this macro to extract type of section from LDR_SECTION_INFO.type field */
373 #define DLOAD_SECTION_TYPE(typeinfo) (typeinfo & 0xF)
374 
375 /* type of section to be allocated */
376 #define DLOAD_TEXT 0
377 #define DLOAD_DATA 1
378 #define DLOAD_BSS 2
379 	/* internal use only, run-time cinit will be of type DLOAD_DATA */
380 #define DLOAD_CINIT 3
381 
382 	struct Dynamic_Loader_Allocate {
383 /* public: */
384 
385     /*************************************************************************
386     * Function allocate
387     *
388     * Parameters:
389     *   info        A pointer to an information block for the section
390     *   align       The alignment of the storage in target AUs
391     *
392     * Effect:
393     *   Allocates target memory for the specified section and fills in the
394     * load_addr and run_addr fields of the section info structure. Returns TRUE
395     * for success, FALSE for failure.
396     *
397     * Notes:
398     *   Frequently load_addr and run_addr are the same, but if they are not
399     * load_addr is used with Dynamic_Loader_Initialize, and run_addr is
400     * used for almost all relocations.  This function should always initialize
401     * both fields.
402     *************************************************************************/
403 		int (*Allocate) (struct Dynamic_Loader_Allocate * thisptr,
404 				 struct LDR_SECTION_INFO * info, unsigned align);
405 
406     /*************************************************************************
407     * Function deallocate
408     *
409     * Parameters:
410     *   info        A pointer to an information block for the section
411     *
412     * Effect:
413     *   Releases the target memory previously allocated.
414     *
415     * Notes:
416     * The content of the info->name field is undefined on call to this function.
417     *************************************************************************/
418 		void (*Deallocate) (struct Dynamic_Loader_Allocate * thisptr,
419 				    struct LDR_SECTION_INFO * info);
420 
421 	};			/* class Dynamic_Loader_Allocate */
422 
423 /*****************************************************************************
424  *****************************************************************************
425  * A class used by the dynamic loader to load data into a target.  This class
426  * provides the interface-specific functions needed to load data.
427  *****************************************************************************
428  *****************************************************************************/
429 
430 	struct Dynamic_Loader_Initialize {
431 /* public: */
432     /*************************************************************************
433     * Function connect
434     *
435     * Parameters:
436     *   none
437     *
438     * Effect:
439     *   Connect to the initialization interface. Returns TRUE for success,
440     * FALSE for failure.
441     *
442     * Notes:
443     *   This function is called prior to use of any other functions in
444     * this interface.
445     *************************************************************************/
446 		int (*connect) (struct Dynamic_Loader_Initialize * thisptr);
447 
448     /*************************************************************************
449     * Function readmem
450     *
451     * Parameters:
452     *   bufr        Pointer to a word-aligned buffer for the result
453     *   locn        Target address of first data element
454     *   info        Section info for the section in which the address resides
455     *   bytsiz      Size of the data to be read in sizeof() units
456     *
457     * Effect:
458     *   Fills the specified buffer with data from the target.  Returns TRUE for
459     * success, FALSE for failure.
460     *************************************************************************/
461 		int (*readmem) (struct Dynamic_Loader_Initialize * thisptr, void *bufr,
462 				LDR_ADDR locn, struct LDR_SECTION_INFO * info,
463 				unsigned bytsiz);
464 
465     /*************************************************************************
466     * Function writemem
467     *
468     * Parameters:
469     *   bufr        Pointer to a word-aligned buffer of data
470     *   locn        Target address of first data element to be written
471     *   info        Section info for the section in which the address resides
472     *   bytsiz      Size of the data to be written in sizeof() units
473     *
474     * Effect:
475     *   Writes the specified buffer to the target.  Returns TRUE for success,
476     * FALSE for failure.
477     *************************************************************************/
478 		int (*writemem) (struct Dynamic_Loader_Initialize * thisptr,
479 				 void *bufr, LDR_ADDR locn,
480 				 struct LDR_SECTION_INFO * info, unsigned bytsiz);
481 
482     /*************************************************************************
483     * Function fillmem
484     *
485     * Parameters:
486     *   locn        Target address of first data element to be written
487     *   info        Section info for the section in which the address resides
488     *   bytsiz      Size of the data to be written in sizeof() units
489     *   val         Value to be written in each byte
490     * Effect:
491     *   Fills the specified area of target memory.  Returns TRUE for success,
492     * FALSE for failure.
493     *************************************************************************/
494 		int (*fillmem) (struct Dynamic_Loader_Initialize * thisptr,
495 				LDR_ADDR locn, struct LDR_SECTION_INFO * info,
496 				unsigned bytsiz, unsigned val);
497 
498     /*************************************************************************
499     * Function execute
500     *
501     * Parameters:
502     *   start       Starting address
503     *
504     * Effect:
505     *   The target code at the specified starting address is executed.
506     *
507     * Notes:
508     *   This function is called at the end of the dynamic load process
509     * if the input module has specified a starting address.
510     *************************************************************************/
511 		int (*execute) (struct Dynamic_Loader_Initialize * thisptr,
512 				LDR_ADDR start);
513 
514     /*************************************************************************
515     * Function release
516     *
517     * Parameters:
518     *   none
519     *
520     * Effect:
521     *   Releases the connection to the load interface.
522     *
523     * Notes:
524     *   This function is called at the end of the dynamic load process.
525     *************************************************************************/
526 		void (*release) (struct Dynamic_Loader_Initialize * thisptr);
527 
528 	};			/* class Dynamic_Loader_Initialize */
529 #ifdef __cplusplus
530 }
531 #endif
532 #endif				/* _DYNAMIC_LOADER_H_ */
533 
534