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
