dspbridge/inc/dynamic_loader.h - platform/hardware/ti/omap3 - Git at Google

 /*
  *  Copyright 2001-2008 Texas Instruments - http://www.ti.com/
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
  *  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  *  Unless required by applicable law or agreed to in writing, software
  *  distributed under the License is distributed on an "AS IS" BASIS,
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */


 #ifndef _DYNAMIC_LOADER_H_
 #define _DYNAMIC_LOADER_H_
 #include <stdarg.h>
 #ifndef __KERNEL__
 #include <stdint.h>
 #else
 #include <linux/types.h>
 #endif

 #ifdef __cplusplus
 extern "C" {			/* C-only version */
 #endif

 /* Optional optimization defines */
 #define OPT_ELIMINATE_EXTRA_DLOAD 1
 /* #define OPT_ZERO_COPY_LOADER 1 */


 /*
  * Dynamic Loader
  *
  * The function of the dynamic loader is to load a "module" containing
  * instructions
  * for a "target" processor into that processor.  In the process it assigns
  * memory
  * for the module, resolves symbol references made by the module, and remembers
  * symbols defined by the module.
  *
  * The dynamic loader is parameterized for a particular system by 4 classes
  * that supply
  * the module and system specific functions it requires
  */
 	/* The read functions for the module image to be loaded */
 	struct Dynamic_Loader_Stream;
 	/*typedef struct Dynamic_Loader_Stream Dynamic_Loader_Stream;*/

 	/* This class defines "host" symbol and support functions */
 	struct Dynamic_Loader_Sym;
 	/*typedef struct Dynamic_Loader_Sym Dynamic_Loader_Sym;*/

 	/* This class defines the allocator for "target" memory */
 	struct Dynamic_Loader_Allocate;
 	/*typedef struct Dynamic_Loader_Allocate Dynamic_Loader_Allocate;*/

 	/* This class defines the copy-into-target-memory functions */
 	struct Dynamic_Loader_Initialize;
 	/*typedef struct Dynamic_Loader_Initialize Dynamic_Loader_Initialize;*/

 /*
  * Option flags to modify the behavior of module loading
  */
 #define DLOAD_INITBSS 0x1	/* initialize BSS sections to zero */
 #define DLOAD_BIGEND 0x2	/* require big-endian load module */
 #define DLOAD_LITTLE 0x4	/* require little-endian load module */

 	typedef void *DLOAD_mhandle;	/* module handle for loaded modules */

 /*****************************************************************************
  * Procedure Dynamic_Load_Module
  *
  * Parameters:
  *  module  The input stream that supplies the module image
  *  syms    Host-side symbol table and malloc/free functions
  *  alloc   Target-side memory allocation
  *  init    Target-side memory initialization, or NULL for symbol read only
  *  options Option flags DLOAD_*
  *  mhandle A module handle for use with Dynamic_Unload
  *
  * Effect:
  *  The module image is read using *module.  Target storage for the new image is
  * obtained from *alloc.  Symbols defined and referenced by the module are
  * managed using *syms.  The image is then relocated and references resolved
  * as necessary, and the resulting executable bits are placed into target memory
  * using *init.
  *
  * Returns:
  *  On a successful load, a module handle is placed in *mhandle, and zero is
  * returned.  On error, the number of errors detected is returned.  Individual
  * errors are reported during the load process using syms->Error_Report().
  *****************************************************************************/
 	extern int Dynamic_Load_Module(
 					/* the source for the module image*/
 					struct Dynamic_Loader_Stream * module,
 					   /* host support for symbols and storage*/
 				       struct Dynamic_Loader_Sym * syms,
 					   /* the target memory allocator*/
 				       struct Dynamic_Loader_Allocate * alloc,
 					   /* the target memory initializer*/
 				       struct Dynamic_Loader_Initialize * init,
 				       unsigned options,	/* option flags*/
 				       DLOAD_mhandle * mhandle	/* the returned module handle*/
 	    );

 #ifdef OPT_ELIMINATE_EXTRA_DLOAD
 /*****************************************************************************
  * Procedure Dynamic_Open_Module
  *
  * Parameters:
  *  module  The input stream that supplies the module image
  *  syms    Host-side symbol table and malloc/free functions
  *  alloc   Target-side memory allocation
  *  init    Target-side memory initialization, or NULL for symbol read only
  *  options Option flags DLOAD_*
  *  mhandle A module handle for use with Dynamic_Unload
  *
  * Effect:
  *  The module image is read using *module.  Target storage for the new image is
  * obtained from *alloc.  Symbols defined and referenced by the module are
  * managed using *syms.  The image is then relocated and references resolved
  * as necessary, and the resulting executable bits are placed into target memory
  * using *init.
  *
  * Returns:
  *  On a successful load, a module handle is placed in *mhandle, and zero is
  * returned.  On error, the number of errors detected is returned.  Individual
  * errors are reported during the load process using syms->Error_Report().
  *****************************************************************************/
         extern int Dynamic_Open_Module(struct Dynamic_Loader_Stream * module,  // the source for the module image
                                        struct Dynamic_Loader_Sym * syms,       // host support for symbols and storage
                                        struct Dynamic_Loader_Allocate * alloc, // the target memory allocator
                                        struct Dynamic_Loader_Initialize * init,        // the target memory initializer
                                        unsigned options,        // option flags
                                        DLOAD_mhandle * mhandle  // the returned module handle
             );
 #endif

 /*****************************************************************************
  * Procedure Dynamic_Unload_Module
  *
  * Parameters:
  *  mhandle A module handle from Dynamic_Load_Module
  *  syms    Host-side symbol table and malloc/free functions
  *  alloc   Target-side memory allocation
  *
  * Effect:
  *  The module specified by mhandle is unloaded.  Unloading causes all
  * target memory to be deallocated, all symbols defined by the module to
  * be purged, and any host-side storage used by the dynamic loader for
  * this module to be released.
  *
  * Returns:
  *  Zero for success. On error, the number of errors detected is returned.
  * Individual errors are reported using syms->Error_Report().
  *****************************************************************************/
 	extern int Dynamic_Unload_Module(DLOAD_mhandle mhandle,	/* the module
 															   handle*/
 					 /* host support for symbols and storage*/
 					 struct Dynamic_Loader_Sym * syms,
 					 /* the target memory allocator*/
 					 struct Dynamic_Loader_Allocate * alloc,
 					 /* the target memory initializer*/
 					 struct Dynamic_Loader_Initialize * init
 	    );

 /*****************************************************************************
  *****************************************************************************
  * A class used by the dynamic loader for input of the module image
  *****************************************************************************
  *****************************************************************************/
 	struct Dynamic_Loader_Stream {
 /* public: */
     /*************************************************************************
      * read_buffer
      *
      * PARAMETERS :
      *  buffer  Pointer to the buffer to fill
      *  bufsiz  Amount of data desired in sizeof() units
      *
      * EFFECT :
      *  Reads the specified amount of data from the module input stream
      * into the specified buffer.  Returns the amount of data read in sizeof()
      * units (which if less than the specification, represents an error).
      *
      * NOTES:
      *  In release 1 increments the file position by the number of bytes read
      *
      *************************************************************************/
 		int (*read_buffer) (struct Dynamic_Loader_Stream * thisptr,
 				    void *buffer, unsigned bufsiz);

     /*************************************************************************
      * set_file_posn (release 1 only)
      *
      * PARAMETERS :
      *  posn  Desired file position relative to start of file in sizeof() units.
      *
      * EFFECT :
      *  Adjusts the internal state of the stream object so that the next
      * read_buffer call will begin to read at the specified offset from
      * the beginning of the input module.  Returns 0 for success, non-zero
      * for failure.
      *
      *************************************************************************/
 		int (*set_file_posn) (struct Dynamic_Loader_Stream * thisptr,
 					unsigned int posn);	/* to be eliminated in release 2*/

 	};

 /*****************************************************************************
  *****************************************************************************
  * A class used by the dynamic loader for symbol table support and
  * miscellaneous host-side functions
  *****************************************************************************
  *****************************************************************************/
 #ifndef __KERNEL__
 	typedef uint32_t LDR_ADDR;
 #else
 	typedef u32 LDR_ADDR;
 #endif

 /*
  * the structure of a symbol known to the dynamic loader
  */
 	struct dynload_symbol {
 		LDR_ADDR value;
 	} ;

 	struct Dynamic_Loader_Sym {
 /* public: */
     /*************************************************************************
      * Find_Matching_Symbol
      *
      * PARAMETERS :
      *  name    The name of the desired symbol
      *
      * EFFECT :
      *  Locates a symbol matching the name specified.  A pointer to the
      * symbol is returned if it exists; 0 is returned if no such symbol is
      * found.
      *
      *************************************************************************/
 		struct dynload_symbol *(*Find_Matching_Symbol)
 			(struct Dynamic_Loader_Sym *
 							 thisptr,
 							 const char *name);

     /*************************************************************************
      * Add_To_Symbol_Table
      *
      * PARAMETERS :
      *  nname       Pointer to the name of the new symbol
      *  moduleid    An opaque module id assigned by the dynamic loader
      *
      * EFFECT :
      *  The new symbol is added to the table.  A pointer to the symbol is
      * returned, or NULL is returned for failure.
      *
      * NOTES:
      *  It is permissible for this function to return NULL; the effect is that
      * the named symbol will not be available to resolve references in
      * subsequent loads.  Returning NULL will not cause the current load
      * to fail.
      *************************************************************************/
 		struct dynload_symbol *(*Add_To_Symbol_Table)
 						(struct Dynamic_Loader_Sym *
 							thisptr,
 							const char *nname,
 							unsigned moduleid);

     /*************************************************************************
      * Purge_Symbol_Table
      *
      * PARAMETERS :
      *  moduleid    An opaque module id assigned by the dynamic loader
      *
      * EFFECT :
      *  Each symbol in the symbol table whose moduleid matches the argument
      * is removed from the table.
      *************************************************************************/
 		void (*Purge_Symbol_Table) (struct Dynamic_Loader_Sym * thisptr,
 					    unsigned moduleid);

     /*************************************************************************
      * Allocate
      *
      * PARAMETERS :
      *  memsiz  size of desired memory in sizeof() units
      *
      * EFFECT :
      *  Returns a pointer to some "host" memory for use by the dynamic
      * loader, or NULL for failure.
      * This function is serves as a replaceable form of "malloc" to
      * allow the user to configure the memory usage of the dynamic loader.
      *************************************************************************/
 		void *(*Allocate) (struct Dynamic_Loader_Sym * thisptr,
 				   unsigned memsiz);

     /*************************************************************************
      * Deallocate
      *
      * PARAMETERS :
      *  memptr  pointer to previously allocated memory
      *
      * EFFECT :
      *  Releases the previously allocated "host" memory.
      *************************************************************************/
 		void (*Deallocate) (struct Dynamic_Loader_Sym * thisptr, void *memptr);

     /*************************************************************************
      * Error_Report
      *
      * PARAMETERS :
      *  errstr  pointer to an error string
      *  args    additional arguments
      *
      * EFFECT :
      *  This function provides an error reporting interface for the dynamic
      * loader.  The error string and arguments are designed as for the
      * library function vprintf.
      *************************************************************************/
 		void (*Error_Report) (struct Dynamic_Loader_Sym * thisptr,
 				      const char *errstr, va_list args);

 	};			/* class Dynamic_Loader_Sym */

 /*****************************************************************************
  *****************************************************************************
  * A class used by the dynamic loader to allocate and deallocate target memory.
  *****************************************************************************
  *****************************************************************************/

 	struct LDR_SECTION_INFO {
 		/* Name of the memory section assigned at build time */
 		const char *name;
 		LDR_ADDR run_addr;	/* execution address of the section */
 		LDR_ADDR load_addr;	/* load address of the section */
 		LDR_ADDR size;	/* size of the section in addressable units */
 /* #ifndef _BIG_ENDIAN *//* _BIG_ENDIAN Not defined by bridge driver */
 #ifdef __KERNEL__
 		u16 page;	/* memory page or view */
 		u16 type;	/* one of the section types below */
 #else
 		uint16_t page;	/* memory page or view */
 		uint16_t type;	/* one of the section types below */
 #endif
 /*#else
 #ifdef __KERNEL__
 		u16 type;*/	/* one of the section types below */
 /*		u16 page;*/	/* memory page or view */
 /*#else
 		uint16_t type;*//* one of the section types below */
 /*		uint16_t page;*//* memory page or view */
 /*#endif
 #endif*//* _BIG_ENDIAN Not defined by bridge driver */
 		/* a context field for use by Dynamic_Loader_Allocate;
 					   ignored but maintained by the dynamic loader */
 #ifdef __KERNEL__
 		u32 context;
 #else
 		uintptr_t context;
 #endif
 	} ;

 /* use this macro to extract type of section from LDR_SECTION_INFO.type field */
 #define DLOAD_SECTION_TYPE(typeinfo) (typeinfo & 0xF)

 /* type of section to be allocated */
 #define DLOAD_TEXT 0
 #define DLOAD_DATA 1
 #define DLOAD_BSS 2
 	/* internal use only, run-time cinit will be of type DLOAD_DATA */
 #define DLOAD_CINIT 3

 	struct Dynamic_Loader_Allocate {
 /* public: */

     /*************************************************************************
     * Function allocate
     *
     * Parameters:
     *   info        A pointer to an information block for the section
     *   align       The alignment of the storage in target AUs
     *
     * Effect:
     *   Allocates target memory for the specified section and fills in the
     * load_addr and run_addr fields of the section info structure. Returns TRUE
     * for success, FALSE for failure.
     *
     * Notes:
     *   Frequently load_addr and run_addr are the same, but if they are not
     * load_addr is used with Dynamic_Loader_Initialize, and run_addr is
     * used for almost all relocations.  This function should always initialize
     * both fields.
     *************************************************************************/
 		int (*Allocate) (struct Dynamic_Loader_Allocate * thisptr,
 				 struct LDR_SECTION_INFO * info, unsigned align);

     /*************************************************************************
     * Function deallocate
     *
     * Parameters:
     *   info        A pointer to an information block for the section
     *
     * Effect:
     *   Releases the target memory previously allocated.
     *
     * Notes:
     * The content of the info->name field is undefined on call to this function.
     *************************************************************************/
 		void (*Deallocate) (struct Dynamic_Loader_Allocate * thisptr,
 				    struct LDR_SECTION_INFO * info);

 	};			/* class Dynamic_Loader_Allocate */

 /*****************************************************************************
  *****************************************************************************
  * A class used by the dynamic loader to load data into a target.  This class
  * provides the interface-specific functions needed to load data.
  *****************************************************************************
  *****************************************************************************/

 	struct Dynamic_Loader_Initialize {
 /* public: */
     /*************************************************************************
     * Function connect
     *
     * Parameters:
     *   none
     *
     * Effect:
     *   Connect to the initialization interface. Returns TRUE for success,
     * FALSE for failure.
     *
     * Notes:
     *   This function is called prior to use of any other functions in
     * this interface.
     *************************************************************************/
 		int (*connect) (struct Dynamic_Loader_Initialize * thisptr);

     /*************************************************************************
     * Function readmem
     *
     * Parameters:
     *   bufr        Pointer to a word-aligned buffer for the result
     *   locn        Target address of first data element
     *   info        Section info for the section in which the address resides
     *   bytsiz      Size of the data to be read in sizeof() units
     *
     * Effect:
     *   Fills the specified buffer with data from the target.  Returns TRUE for
     * success, FALSE for failure.
     *************************************************************************/
 		int (*readmem) (struct Dynamic_Loader_Initialize * thisptr, void *bufr,
 				LDR_ADDR locn, struct LDR_SECTION_INFO * info,
 				unsigned bytsiz);

     /*************************************************************************
     * Function writemem
     *
     * Parameters:
     *   bufr        Pointer to a word-aligned buffer of data
     *   locn        Target address of first data element to be written
     *   info        Section info for the section in which the address resides
     *   bytsiz      Size of the data to be written in sizeof() units
     *
     * Effect:
     *   Writes the specified buffer to the target.  Returns TRUE for success,
     * FALSE for failure.
     *************************************************************************/
 		int (*writemem) (struct Dynamic_Loader_Initialize * thisptr,
 				 void *bufr, LDR_ADDR locn,
 				 struct LDR_SECTION_INFO * info, unsigned bytsiz);

     /*************************************************************************
     * Function fillmem
     *
     * Parameters:
     *   locn        Target address of first data element to be written
     *   info        Section info for the section in which the address resides
     *   bytsiz      Size of the data to be written in sizeof() units
     *   val         Value to be written in each byte
     * Effect:
     *   Fills the specified area of target memory.  Returns TRUE for success,
     * FALSE for failure.
     *************************************************************************/
 		int (*fillmem) (struct Dynamic_Loader_Initialize * thisptr,
 				LDR_ADDR locn, struct LDR_SECTION_INFO * info,
 				unsigned bytsiz, unsigned val);

     /*************************************************************************
     * Function execute
     *
     * Parameters:
     *   start       Starting address
     *
     * Effect:
     *   The target code at the specified starting address is executed.
     *
     * Notes:
     *   This function is called at the end of the dynamic load process
     * if the input module has specified a starting address.
     *************************************************************************/
 		int (*execute) (struct Dynamic_Loader_Initialize * thisptr,
 				LDR_ADDR start);

     /*************************************************************************
     * Function release
     *
     * Parameters:
     *   none
     *
     * Effect:
     *   Releases the connection to the load interface.
     *
     * Notes:
     *   This function is called at the end of the dynamic load process.
     *************************************************************************/
 		void (*release) (struct Dynamic_Loader_Initialize * thisptr);

 	};			/* class Dynamic_Loader_Initialize */
 #ifdef __cplusplus
 }
 #endif
 #endif				/* _DYNAMIC_LOADER_H_ */
	/*
	* Copyright 2001-2008 Texas Instruments - http://www.ti.com/
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/



	#ifndef _DYNAMIC_LOADER_H_
	#define _DYNAMIC_LOADER_H_
	#include <stdarg.h>
	#ifndef __KERNEL__
	#include <stdint.h>
	#else
	#include <linux/types.h>
	#endif

	#ifdef __cplusplus
	extern "C" { /* C-only version */
	#endif

	/* Optional optimization defines */
	#define OPT_ELIMINATE_EXTRA_DLOAD 1
	/* #define OPT_ZERO_COPY_LOADER 1 */


	/*
	* Dynamic Loader
	*
	* The function of the dynamic loader is to load a "module" containing
	* instructions
	* for a "target" processor into that processor. In the process it assigns
	* memory
	* for the module, resolves symbol references made by the module, and remembers
	* symbols defined by the module.
	*
	* The dynamic loader is parameterized for a particular system by 4 classes
	* that supply
	* the module and system specific functions it requires
	*/
	/* The read functions for the module image to be loaded */
	struct Dynamic_Loader_Stream;
	/typedef struct Dynamic_Loader_Stream Dynamic_Loader_Stream;/

	/* This class defines "host" symbol and support functions */
	struct Dynamic_Loader_Sym;
	/typedef struct Dynamic_Loader_Sym Dynamic_Loader_Sym;/

	/* This class defines the allocator for "target" memory */
	struct Dynamic_Loader_Allocate;
	/typedef struct Dynamic_Loader_Allocate Dynamic_Loader_Allocate;/

	/* This class defines the copy-into-target-memory functions */
	struct Dynamic_Loader_Initialize;
	/typedef struct Dynamic_Loader_Initialize Dynamic_Loader_Initialize;/

	/*
	* Option flags to modify the behavior of module loading
	*/
	#define DLOAD_INITBSS 0x1 /* initialize BSS sections to zero */
	#define DLOAD_BIGEND 0x2 /* require big-endian load module */
	#define DLOAD_LITTLE 0x4 /* require little-endian load module */

	typedef void DLOAD_mhandle; / module handle for loaded modules */

	/*****************************************************************************
	* Procedure Dynamic_Load_Module
	*
	* Parameters:
	* module The input stream that supplies the module image
	* syms Host-side symbol table and malloc/free functions
	* alloc Target-side memory allocation
	* init Target-side memory initialization, or NULL for symbol read only
	* options Option flags DLOAD_*
	* mhandle A module handle for use with Dynamic_Unload
	*
	* Effect:
	* The module image is read using *module. Target storage for the new image is
	* obtained from *alloc. Symbols defined and referenced by the module are
	* managed using *syms. The image is then relocated and references resolved
	* as necessary, and the resulting executable bits are placed into target memory
	* using *init.
	*
	* Returns:
	* On a successful load, a module handle is placed in *mhandle, and zero is
	* returned. On error, the number of errors detected is returned. Individual
	* errors are reported during the load process using syms->Error_Report().
	*****************************************************************************/
	extern int Dynamic_Load_Module(
	/* the source for the module image*/
	struct Dynamic_Loader_Stream * module,
	/* host support for symbols and storage*/
	struct Dynamic_Loader_Sym * syms,
	/* the target memory allocator*/
	struct Dynamic_Loader_Allocate * alloc,
	/* the target memory initializer*/
	struct Dynamic_Loader_Initialize * init,
	unsigned options, /* option flags*/
	DLOAD_mhandle * mhandle /* the returned module handle*/
	);

	#ifdef OPT_ELIMINATE_EXTRA_DLOAD
	/*****************************************************************************
	* Procedure Dynamic_Open_Module
	*
	* Parameters:
	* module The input stream that supplies the module image
	* syms Host-side symbol table and malloc/free functions
	* alloc Target-side memory allocation
	* init Target-side memory initialization, or NULL for symbol read only
	* options Option flags DLOAD_*
	* mhandle A module handle for use with Dynamic_Unload
	*
	* Effect:
	* The module image is read using *module. Target storage for the new image is
	* obtained from *alloc. Symbols defined and referenced by the module are
	* managed using *syms. The image is then relocated and references resolved
	* as necessary, and the resulting executable bits are placed into target memory
	* using *init.
	*
	* Returns:
	* On a successful load, a module handle is placed in *mhandle, and zero is
	* returned. On error, the number of errors detected is returned. Individual
	* errors are reported during the load process using syms->Error_Report().
	*****************************************************************************/
	extern int Dynamic_Open_Module(struct Dynamic_Loader_Stream * module, // the source for the module image
	struct Dynamic_Loader_Sym * syms, // host support for symbols and storage
	struct Dynamic_Loader_Allocate * alloc, // the target memory allocator
	struct Dynamic_Loader_Initialize * init, // the target memory initializer
	unsigned options, // option flags
	DLOAD_mhandle * mhandle // the returned module handle
	);
	#endif

	/*****************************************************************************
	* Procedure Dynamic_Unload_Module
	*
	* Parameters:
	* mhandle A module handle from Dynamic_Load_Module
	* syms Host-side symbol table and malloc/free functions
	* alloc Target-side memory allocation
	*
	* Effect:
	* The module specified by mhandle is unloaded. Unloading causes all
	* target memory to be deallocated, all symbols defined by the module to
	* be purged, and any host-side storage used by the dynamic loader for
	* this module to be released.
	*
	* Returns:
	* Zero for success. On error, the number of errors detected is returned.
	* Individual errors are reported using syms->Error_Report().
	*****************************************************************************/
	extern int Dynamic_Unload_Module(DLOAD_mhandle mhandle, /* the module
	handle*/
	/* host support for symbols and storage*/
	struct Dynamic_Loader_Sym * syms,
	/* the target memory allocator*/
	struct Dynamic_Loader_Allocate * alloc,
	/* the target memory initializer*/
	struct Dynamic_Loader_Initialize * init
	);

	/*****************************************************************************
	*****************************************************************************
	* A class used by the dynamic loader for input of the module image
	*****************************************************************************
	*****************************************************************************/
	struct Dynamic_Loader_Stream {
	/* public: */
	/*************************************************************************
	* read_buffer
	*
	* PARAMETERS :
	* buffer Pointer to the buffer to fill
	* bufsiz Amount of data desired in sizeof() units
	*
	* EFFECT :
	* Reads the specified amount of data from the module input stream
	* into the specified buffer. Returns the amount of data read in sizeof()
	* units (which if less than the specification, represents an error).
	*
	* NOTES:
	* In release 1 increments the file position by the number of bytes read
	*
	*************************************************************************/
	int (read_buffer) (struct Dynamic_Loader_Stream thisptr,
	void *buffer, unsigned bufsiz);

	/*************************************************************************
	* set_file_posn (release 1 only)
	*
	* PARAMETERS :
	* posn Desired file position relative to start of file in sizeof() units.
	*
	* EFFECT :
	* Adjusts the internal state of the stream object so that the next
	* read_buffer call will begin to read at the specified offset from
	* the beginning of the input module. Returns 0 for success, non-zero
	* for failure.
	*
	*************************************************************************/
	int (set_file_posn) (struct Dynamic_Loader_Stream thisptr,
	unsigned int posn); /* to be eliminated in release 2*/

	};

	/*****************************************************************************
	*****************************************************************************
	* A class used by the dynamic loader for symbol table support and
	* miscellaneous host-side functions
	*****************************************************************************
	*****************************************************************************/
	#ifndef __KERNEL__
	typedef uint32_t LDR_ADDR;
	#else
	typedef u32 LDR_ADDR;
	#endif

	/*
	* the structure of a symbol known to the dynamic loader
	*/
	struct dynload_symbol {
	LDR_ADDR value;
	} ;

	struct Dynamic_Loader_Sym {
	/* public: */
	/*************************************************************************
	* Find_Matching_Symbol
	*
	* PARAMETERS :
	* name The name of the desired symbol
	*
	* EFFECT :
	* Locates a symbol matching the name specified. A pointer to the
	* symbol is returned if it exists; 0 is returned if no such symbol is
	* found.
	*
	*************************************************************************/
	struct dynload_symbol (Find_Matching_Symbol)
	(struct Dynamic_Loader_Sym *
	thisptr,
	const char *name);

	/*************************************************************************
	* Add_To_Symbol_Table
	*
	* PARAMETERS :
	* nname Pointer to the name of the new symbol
	* moduleid An opaque module id assigned by the dynamic loader
	*
	* EFFECT :
	* The new symbol is added to the table. A pointer to the symbol is
	* returned, or NULL is returned for failure.
	*
	* NOTES:
	* It is permissible for this function to return NULL; the effect is that
	* the named symbol will not be available to resolve references in
	* subsequent loads. Returning NULL will not cause the current load
	* to fail.
	*************************************************************************/
	struct dynload_symbol (Add_To_Symbol_Table)
	(struct Dynamic_Loader_Sym *
	thisptr,
	const char *nname,
	unsigned moduleid);

	/*************************************************************************
	* Purge_Symbol_Table
	*
	* PARAMETERS :
	* moduleid An opaque module id assigned by the dynamic loader
	*
	* EFFECT :
	* Each symbol in the symbol table whose moduleid matches the argument
	* is removed from the table.
	*************************************************************************/
	void (Purge_Symbol_Table) (struct Dynamic_Loader_Sym thisptr,
	unsigned moduleid);

	/*************************************************************************
	* Allocate
	*
	* PARAMETERS :
	* memsiz size of desired memory in sizeof() units
	*
	* EFFECT :
	* Returns a pointer to some "host" memory for use by the dynamic
	* loader, or NULL for failure.
	* This function is serves as a replaceable form of "malloc" to
	* allow the user to configure the memory usage of the dynamic loader.
	*************************************************************************/
	void (Allocate) (struct Dynamic_Loader_Sym * thisptr,
	unsigned memsiz);

	/*************************************************************************
	* Deallocate
	*
	* PARAMETERS :
	* memptr pointer to previously allocated memory
	*
	* EFFECT :
	* Releases the previously allocated "host" memory.
	*************************************************************************/
	void (Deallocate) (struct Dynamic_Loader_Sym thisptr, void *memptr);

	/*************************************************************************
	* Error_Report
	*
	* PARAMETERS :
	* errstr pointer to an error string
	* args additional arguments
	*
	* EFFECT :
	* This function provides an error reporting interface for the dynamic
	* loader. The error string and arguments are designed as for the
	* library function vprintf.
	*************************************************************************/
	void (Error_Report) (struct Dynamic_Loader_Sym thisptr,
	const char *errstr, va_list args);

	}; /* class Dynamic_Loader_Sym */

	/*****************************************************************************
	*****************************************************************************
	* A class used by the dynamic loader to allocate and deallocate target memory.
	*****************************************************************************
	*****************************************************************************/

	struct LDR_SECTION_INFO {
	/* Name of the memory section assigned at build time */
	const char *name;
	LDR_ADDR run_addr; /* execution address of the section */
	LDR_ADDR load_addr; /* load address of the section */
	LDR_ADDR size; /* size of the section in addressable units */
	/* #ifndef _BIG_ENDIAN // _BIG_ENDIAN Not defined by bridge driver */
	#ifdef __KERNEL__
	u16 page; /* memory page or view */
	u16 type; /* one of the section types below */
	#else
	uint16_t page; /* memory page or view */
	uint16_t type; /* one of the section types below */
	#endif
	/*#else
	#ifdef __KERNEL__
	u16 type;/ / one of the section types below */
	/* u16 page;/ / memory page or view */
	/*#else
	uint16_t type;// one of the section types below */
	/* uint16_t page;// memory page or view */
	/*#endif
	#endif// _BIG_ENDIAN Not defined by bridge driver */
	/* a context field for use by Dynamic_Loader_Allocate;
	ignored but maintained by the dynamic loader */
	#ifdef __KERNEL__
	u32 context;
	#else
	uintptr_t context;
	#endif
	} ;

	/* use this macro to extract type of section from LDR_SECTION_INFO.type field */
	#define DLOAD_SECTION_TYPE(typeinfo) (typeinfo & 0xF)

	/* type of section to be allocated */
	#define DLOAD_TEXT 0
	#define DLOAD_DATA 1
	#define DLOAD_BSS 2
	/* internal use only, run-time cinit will be of type DLOAD_DATA */
	#define DLOAD_CINIT 3

	struct Dynamic_Loader_Allocate {
	/* public: */

	/*************************************************************************
	* Function allocate
	*
	* Parameters:
	* info A pointer to an information block for the section
	* align The alignment of the storage in target AUs
	*
	* Effect:
	* Allocates target memory for the specified section and fills in the
	* load_addr and run_addr fields of the section info structure. Returns TRUE
	* for success, FALSE for failure.
	*
	* Notes:
	* Frequently load_addr and run_addr are the same, but if they are not
	* load_addr is used with Dynamic_Loader_Initialize, and run_addr is
	* used for almost all relocations. This function should always initialize
	* both fields.
	*************************************************************************/
	int (Allocate) (struct Dynamic_Loader_Allocate thisptr,
	struct LDR_SECTION_INFO * info, unsigned align);

	/*************************************************************************
	* Function deallocate
	*
	* Parameters:
	* info A pointer to an information block for the section
	*
	* Effect:
	* Releases the target memory previously allocated.
	*
	* Notes:
	* The content of the info->name field is undefined on call to this function.
	*************************************************************************/
	void (Deallocate) (struct Dynamic_Loader_Allocate thisptr,
	struct LDR_SECTION_INFO * info);

	}; /* class Dynamic_Loader_Allocate */

	/*****************************************************************************
	*****************************************************************************
	* A class used by the dynamic loader to load data into a target. This class
	* provides the interface-specific functions needed to load data.
	*****************************************************************************
	*****************************************************************************/

	struct Dynamic_Loader_Initialize {
	/* public: */
	/*************************************************************************
	* Function connect
	*
	* Parameters:
	* none
	*
	* Effect:
	* Connect to the initialization interface. Returns TRUE for success,
	* FALSE for failure.
	*
	* Notes:
	* This function is called prior to use of any other functions in
	* this interface.
	*************************************************************************/
	int (connect) (struct Dynamic_Loader_Initialize thisptr);

	/*************************************************************************
	* Function readmem
	*
	* Parameters:
	* bufr Pointer to a word-aligned buffer for the result
	* locn Target address of first data element
	* info Section info for the section in which the address resides
	* bytsiz Size of the data to be read in sizeof() units
	*
	* Effect:
	* Fills the specified buffer with data from the target. Returns TRUE for
	* success, FALSE for failure.
	*************************************************************************/
	int (readmem) (struct Dynamic_Loader_Initialize thisptr, void *bufr,
	LDR_ADDR locn, struct LDR_SECTION_INFO * info,
	unsigned bytsiz);

	/*************************************************************************
	* Function writemem
	*
	* Parameters:
	* bufr Pointer to a word-aligned buffer of data
	* locn Target address of first data element to be written
	* info Section info for the section in which the address resides
	* bytsiz Size of the data to be written in sizeof() units
	*
	* Effect:
	* Writes the specified buffer to the target. Returns TRUE for success,
	* FALSE for failure.
	*************************************************************************/
	int (writemem) (struct Dynamic_Loader_Initialize thisptr,
	void *bufr, LDR_ADDR locn,
	struct LDR_SECTION_INFO * info, unsigned bytsiz);

	/*************************************************************************
	* Function fillmem
	*
	* Parameters:
	* locn Target address of first data element to be written
	* info Section info for the section in which the address resides
	* bytsiz Size of the data to be written in sizeof() units
	* val Value to be written in each byte
	* Effect:
	* Fills the specified area of target memory. Returns TRUE for success,
	* FALSE for failure.
	*************************************************************************/
	int (fillmem) (struct Dynamic_Loader_Initialize thisptr,
	LDR_ADDR locn, struct LDR_SECTION_INFO * info,
	unsigned bytsiz, unsigned val);

	/*************************************************************************
	* Function execute
	*
	* Parameters:
	* start Starting address
	*
	* Effect:
	* The target code at the specified starting address is executed.
	*
	* Notes:
	* This function is called at the end of the dynamic load process
	* if the input module has specified a starting address.
	*************************************************************************/
	int (execute) (struct Dynamic_Loader_Initialize thisptr,
	LDR_ADDR start);

	/*************************************************************************
	* Function release
	*
	* Parameters:
	* none
	*
	* Effect:
	* Releases the connection to the load interface.
	*
	* Notes:
	* This function is called at the end of the dynamic load process.
	*************************************************************************/
	void (release) (struct Dynamic_Loader_Initialize thisptr);

	}; /* class Dynamic_Loader_Initialize */
	#ifdef __cplusplus
	}
	#endif
	#endif /* _DYNAMIC_LOADER_H_ */