drivers/staging/tidspbridge/include/dspbridge/dynamic_loader.h

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