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

   1 /*
   2  * dblldefs.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * Copyright (C) 2005-2006 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 DBLLDEFS_
  18 #define DBLLDEFS_
  19
  20 /*
  21  *  Bit masks for dbl_flags.
  22  */
  23 #define DBLL_NOLOAD   0x0       /* Don't load symbols, code, or data */
  24 #define DBLL_SYMB     0x1       /* load symbols */
  25 #define DBLL_CODE     0x2       /* load code */
  26 #define DBLL_DATA     0x4       /* load data */
  27 #define DBLL_DYNAMIC  0x8       /* dynamic load */
  28 #define DBLL_BSS      0x20      /* Unitialized section */
  29
  30 #define DBLL_MAXPATHLENGTH       255
  31
  32 /*
  33  *  ======== DBLL_Target ========
  34  *
  35  */
  36 struct dbll_tar_obj;
  37
  38 /*
  39  *  ======== dbll_flags ========
  40  *  Specifies whether to load code, data, or symbols
  41  */
  42 typedef s32 dbll_flags;
  43
  44 /*
  45  *  ======== DBLL_Library ========
  46  *
  47  */
  48 struct dbll_library_obj;
  49
  50 /*
  51  *  ======== dbll_sect_info ========
  52  *  For collecting info on overlay sections
  53  */
  54 struct dbll_sect_info {
  55         const char *name;       /* name of section */
  56         u32 sect_run_addr;      /* run address of section */
  57         u32 sect_load_addr;     /* load address of section */
  58         u32 size;               /* size of section (target MAUs) */
  59         dbll_flags type;        /* Code, data, or BSS */
  60 };
  61
  62 /*
  63  *  ======== dbll_sym_val ========
  64  *  (Needed for dynamic load library)
  65  */
  66 struct dbll_sym_val {
  67         u32 value;
  68 };
  69
  70 /*
  71  *  ======== dbll_alloc_fxn ========
  72  *  Allocate memory function.  Allocate or reserve (if reserved == TRUE)
  73  *  "size" bytes of memory from segment "space" and return the address in
  74  *  *dsp_address (or starting at *dsp_address if reserve == TRUE). Returns 0 on
  75  *  success, or an error code on failure.
  76  */
  77 typedef s32(*dbll_alloc_fxn) (void *hdl, s32 space, u32 size, u32 align,
  78                               u32 *dsp_address, s32 seg_id, s32 req,
  79                               bool reserved);
  80
  81 /*
  82  *  ======== dbll_close_fxn ========
  83  */
  84 typedef s32(*dbll_f_close_fxn) (void *);
  85
  86 /*
  87  *  ======== dbll_free_fxn ========
  88  *  Free memory function.  Free, or unreserve (if reserved == TRUE) "size"
  89  *  bytes of memory from segment "space"
  90  */
  91 typedef bool(*dbll_free_fxn) (void *hdl, u32 addr, s32 space, u32 size,
  92                               bool reserved);
  93
  94 /*
  95  *  ======== dbll_f_open_fxn ========
  96  */
  97 typedef void *(*dbll_f_open_fxn) (const char *, const char *);
  98
  99 /*
 100  *  ======== dbll_log_write_fxn ========
 101  *  Function to call when writing data from a section, to log the info.
 102  *  Can be NULL if no logging is required.
 103  */
 104 typedef int(*dbll_log_write_fxn) (void *handle,
 105                                          struct dbll_sect_info *sect, u32 addr,
 106                                          u32 bytes);
 107
 108 /*
 109  *  ======== dbll_read_fxn ========
 110  */
 111 typedef s32(*dbll_read_fxn) (void *, size_t, size_t, void *);
 112
 113 /*
 114  *  ======== dbll_seek_fxn ========
 115  */
 116 typedef s32(*dbll_seek_fxn) (void *, long, int);
 117
 118 /*
 119  *  ======== dbll_sym_lookup ========
 120  *  Symbol lookup function - Find the symbol name and return its value.
 121  *
 122  *  Parameters:
 123  *      handle          - Opaque handle
 124  *      parg            - Opaque argument.
 125  *      name            - Name of symbol to lookup.
 126  *      sym             - Location to store address of symbol structure.
 127  *
 128  *  Returns:
 129  *      TRUE:           Success (symbol was found).
 130  *      FALSE:          Failed to find symbol.
 131  */
 132 typedef bool(*dbll_sym_lookup) (void *handle, void *parg, void *rmm_handle,
 133                                 const char *name, struct dbll_sym_val ** sym);
 134
 135 /*
 136  *  ======== dbll_tell_fxn ========
 137  */
 138 typedef s32(*dbll_tell_fxn) (void *);
 139
 140 /*
 141  *  ======== dbll_write_fxn ========
 142  *  Write memory function.  Write "n" HOST bytes of memory to segment "mtype"
 143  *  starting at address "dsp_address" from the buffer "buf".  The buffer is
 144  *  formatted as an array of words appropriate for the DSP.
 145  */
 146 typedef s32(*dbll_write_fxn) (void *hdl, u32 dsp_address, void *buf,
 147                               u32 n, s32 mtype);
 148
 149 /*
 150  *  ======== dbll_attrs ========
 151  */
 152 struct dbll_attrs {
 153         dbll_alloc_fxn alloc;
 154         dbll_free_fxn free;
 155         void *rmm_handle;       /* Handle to pass to alloc, free functions */
 156         dbll_write_fxn write;
 157         void *input_params;     /* Handle to pass to write, cinit function */
 158         bool base_image;
 159         dbll_log_write_fxn log_write;
 160         void *log_write_handle;
 161
 162         /* Symbol matching function and handle to pass to it */
 163         dbll_sym_lookup sym_lookup;
 164         void *sym_handle;
 165         void *sym_arg;
 166
 167         /*
 168          *  These file manipulation functions should be compatible with the
 169          *  "C" run time library functions of the same name.
 170          */
 171          s32(*fread) (void *, size_t, size_t, void *);
 172          s32(*fseek) (void *, long, int);
 173          s32(*ftell) (void *);
 174          s32(*fclose) (void *);
 175         void *(*fopen) (const char *, const char *);
 176 };
 177
 178 /*
 179  *  ======== dbll_close ========
 180  *  Close library opened with dbll_open.
 181  *  Parameters:
 182  *      lib             - Handle returned from dbll_open().
 183  *  Returns:
 184  *  Requires:
 185  *      DBL initialized.
 186  *      Valid lib.
 187  *  Ensures:
 188  */
 189 typedef void (*dbll_close_fxn) (struct dbll_library_obj *library);
 190
 191 /*
 192  *  ======== dbll_create ========
 193  *  Create a target object, specifying the alloc, free, and write functions.
 194  *  Parameters:
 195  *      target_obj         - Location to store target handle on output.
 196  *      pattrs          - Attributes.
 197  *  Returns:
 198  *      0:        Success.
 199  *      -ENOMEM:    Memory allocation failed.
 200  *  Requires:
 201  *      DBL initialized.
 202  *      pattrs != NULL.
 203  *      target_obj != NULL;
 204  *  Ensures:
 205  *      Success:        *target_obj != NULL.
 206  *      Failure:        *target_obj == NULL.
 207  */
 208 typedef int(*dbll_create_fxn) (struct dbll_tar_obj **target_obj,
 209                                       struct dbll_attrs *attrs);
 210
 211 /*
 212  *  ======== dbll_delete ========
 213  *  Delete target object and free resources for any loaded libraries.
 214  *  Parameters:
 215  *      target          - Handle returned from DBLL_Create().
 216  *  Returns:
 217  *  Requires:
 218  *      DBL initialized.
 219  *      Valid target.
 220  *  Ensures:
 221  */
 222 typedef void (*dbll_delete_fxn) (struct dbll_tar_obj *target);
 223
 224 /*
 225  *  ======== dbll_exit ========
 226  *  Discontinue use of DBL module.
 227  *  Parameters:
 228  *  Returns:
 229  *  Requires:
 230  *      refs > 0.
 231  *  Ensures:
 232  *      refs >= 0.
 233  */
 234 typedef void (*dbll_exit_fxn) (void);
 235
 236 /*
 237  *  ======== dbll_get_addr ========
 238  *  Get address of name in the specified library.
 239  *  Parameters:
 240  *      lib             - Handle returned from dbll_open().
 241  *      name            - Name of symbol
 242  *      sym_val         - Location to store symbol address on output.
 243  *  Returns:
 244  *      TRUE:           Success.
 245  *      FALSE:          Symbol not found.
 246  *  Requires:
 247  *      DBL initialized.
 248  *      Valid library.
 249  *      name != NULL.
 250  *      sym_val != NULL.
 251  *  Ensures:
 252  */
 253 typedef bool(*dbll_get_addr_fxn) (struct dbll_library_obj *lib, char *name,
 254                                   struct dbll_sym_val **sym_val);
 255
 256 /*
 257  *  ======== dbll_get_attrs ========
 258  *  Retrieve the attributes of the target.
 259  *  Parameters:
 260  *      target          - Handle returned from DBLL_Create().
 261  *      pattrs          - Location to store attributes on output.
 262  *  Returns:
 263  *  Requires:
 264  *      DBL initialized.
 265  *      Valid target.
 266  *      pattrs != NULL.
 267  *  Ensures:
 268  */
 269 typedef void (*dbll_get_attrs_fxn) (struct dbll_tar_obj *target,
 270                                     struct dbll_attrs *attrs);
 271
 272 /*
 273  *  ======== dbll_get_c_addr ========
 274  *  Get address of "C" name on the specified library.
 275  *  Parameters:
 276  *      lib             - Handle returned from dbll_open().
 277  *      name            - Name of symbol
 278  *      sym_val         - Location to store symbol address on output.
 279  *  Returns:
 280  *      TRUE:           Success.
 281  *      FALSE:          Symbol not found.
 282  *  Requires:
 283  *      DBL initialized.
 284  *      Valid target.
 285  *      name != NULL.
 286  *      sym_val != NULL.
 287  *  Ensures:
 288  */
 289 typedef bool(*dbll_get_c_addr_fxn) (struct dbll_library_obj *lib, char *name,
 290                                     struct dbll_sym_val **sym_val);
 291
 292 /*
 293  *  ======== dbll_get_sect ========
 294  *  Get address and size of a named section.
 295  *  Parameters:
 296  *      lib             - Library handle returned from dbll_open().
 297  *      name            - Name of section.
 298  *      paddr           - Location to store section address on output.
 299  *      psize           - Location to store section size on output.
 300  *  Returns:
 301  *      0:        Success.
 302  *      -ENXIO:    Section not found.
 303  *  Requires:
 304  *      DBL initialized.
 305  *      Valid lib.
 306  *      name != NULL.
 307  *      paddr != NULL;
 308  *      psize != NULL.
 309  *  Ensures:
 310  */
 311 typedef int(*dbll_get_sect_fxn) (struct dbll_library_obj *lib,
 312                                         char *name, u32 * addr, u32 * size);
 313
 314 /*
 315  *  ======== dbll_init ========
 316  *  Initialize DBL module.
 317  *  Parameters:
 318  *  Returns:
 319  *      TRUE:           Success.
 320  *      FALSE:          Failure.
 321  *  Requires:
 322  *      refs >= 0.
 323  *  Ensures:
 324  *      Success:        refs > 0.
 325  *      Failure:        refs >= 0.
 326  */
 327 typedef bool(*dbll_init_fxn) (void);
 328
 329 /*
 330  *  ======== dbll_load ========
 331  *  Load library onto the target.
 332  *
 333  *  Parameters:
 334  *      lib             - Library handle returned from dbll_open().
 335  *      flags           - Load code, data and/or symbols.
 336  *      attrs           - May contain alloc, free, and write function.
 337  *      entry_pt        - Location to store program entry on output.
 338  *  Returns:
 339  *      0:        Success.
 340  *      -EBADF:     File read failed.
 341  *      -EILSEQ:   Failure in dynamic loader library.
 342  *  Requires:
 343  *      DBL initialized.
 344  *      Valid lib.
 345  *      entry != NULL.
 346  *  Ensures:
 347  */
 348 typedef int(*dbll_load_fxn) (struct dbll_library_obj *lib,
 349                                     dbll_flags flags,
 350                                     struct dbll_attrs *attrs, u32 *entry);
 351
 352 /*
 353  *  ======== dbll_load_sect ========
 354  *  Load a named section from an library (for overlay support).
 355  *  Parameters:
 356  *      lib             - Handle returned from dbll_open().
 357  *      sec_name        - Name of section to load.
 358  *      attrs           - Contains write function and handle to pass to it.
 359  *  Returns:
 360  *      0:        Success.
 361  *      -ENXIO:    Section not found.
 362  *      -ENOSYS:   Function not implemented.
 363  *  Requires:
 364  *      Valid lib.
 365  *      sec_name != NULL.
 366  *      attrs != NULL.
 367  *      attrs->write != NULL.
 368  *  Ensures:
 369  */
 370 typedef int(*dbll_load_sect_fxn) (struct dbll_library_obj *lib,
 371                                          char *sz_sect_name,
 372                                          struct dbll_attrs *attrs);
 373
 374 /*
 375  *  ======== dbll_open ========
 376  *  dbll_open() returns a library handle that can be used to load/unload
 377  *  the symbols/code/data via dbll_load()/dbll_unload().
 378  *  Parameters:
 379  *      target          - Handle returned from dbll_create().
 380  *      file            - Name of file to open.
 381  *      flags           - If flags & DBLL_SYMB, load symbols.
 382  *      lib_obj         - Location to store library handle on output.
 383  *  Returns:
 384  *      0:            Success.
 385  *      -ENOMEM:        Memory allocation failure.
 386  *      -EBADF:         File open/read failure.
 387  *                      Unable to determine target type.
 388  *  Requires:
 389  *      DBL initialized.
 390  *      Valid target.
 391  *      file != NULL.
 392  *      lib_obj != NULL.
 393  *      dbll_attrs fopen function non-NULL.
 394  *  Ensures:
 395  *      Success:        Valid *lib_obj.
 396  *      Failure:        *lib_obj == NULL.
 397  */
 398 typedef int(*dbll_open_fxn) (struct dbll_tar_obj *target, char *file,
 399                                     dbll_flags flags,
 400                                     struct dbll_library_obj **lib_obj);
 401
 402 /*
 403  *  ======== dbll_read_sect ========
 404  *  Read COFF section into a character buffer.
 405  *  Parameters:
 406  *      lib             - Library handle returned from dbll_open().
 407  *      name            - Name of section.
 408  *      pbuf            - Buffer to write section contents into.
 409  *      size            - Buffer size
 410  *  Returns:
 411  *      0:        Success.
 412  *      -ENXIO:    Named section does not exists.
 413  *  Requires:
 414  *      DBL initialized.
 415  *      Valid lib.
 416  *      name != NULL.
 417  *      pbuf != NULL.
 418  *      size != 0.
 419  *  Ensures:
 420  */
 421 typedef int(*dbll_read_sect_fxn) (struct dbll_library_obj *lib,
 422                                          char *name, char *content,
 423                                          u32 cont_size);
 424
 425 /*
 426  *  ======== dbll_set_attrs ========
 427  *  Set the attributes of the target.
 428  *  Parameters:
 429  *      target          - Handle returned from dbll_create().
 430  *      pattrs          - New attributes.
 431  *  Returns:
 432  *  Requires:
 433  *      DBL initialized.
 434  *      Valid target.
 435  *      pattrs != NULL.
 436  *  Ensures:
 437  */
 438 typedef void (*dbll_set_attrs_fxn) (struct dbll_tar_obj *target,
 439                                     struct dbll_attrs *attrs);
 440
 441 /*
 442  *  ======== dbll_unload ========
 443  *  Unload library loaded with dbll_load().
 444  *  Parameters:
 445  *      lib             - Handle returned from dbll_open().
 446  *      attrs           - Contains free() function and handle to pass to it.
 447  *  Returns:
 448  *  Requires:
 449  *      DBL initialized.
 450  *      Valid lib.
 451  *  Ensures:
 452  */
 453 typedef void (*dbll_unload_fxn) (struct dbll_library_obj *library,
 454                                  struct dbll_attrs *attrs);
 455
 456 /*
 457  *  ======== dbll_unload_sect ========
 458  *  Unload a named section from an library (for overlay support).
 459  *  Parameters:
 460  *      lib             - Handle returned from dbll_open().
 461  *      sec_name        - Name of section to load.
 462  *      attrs           - Contains free() function and handle to pass to it.
 463  *  Returns:
 464  *      0:        Success.
 465  *      -ENXIO:    Named section not found.
 466  *      -ENOSYS
 467  *  Requires:
 468  *      DBL initialized.
 469  *      Valid lib.
 470  *      sec_name != NULL.
 471  *  Ensures:
 472  */
 473 typedef int(*dbll_unload_sect_fxn) (struct dbll_library_obj *lib,
 474                                            char *sz_sect_name,
 475                                            struct dbll_attrs *attrs);
 476
 477 struct dbll_fxns {
 478         dbll_close_fxn close_fxn;
 479         dbll_create_fxn create_fxn;
 480         dbll_delete_fxn delete_fxn;
 481         dbll_exit_fxn exit_fxn;
 482         dbll_get_attrs_fxn get_attrs_fxn;
 483         dbll_get_addr_fxn get_addr_fxn;
 484         dbll_get_c_addr_fxn get_c_addr_fxn;
 485         dbll_get_sect_fxn get_sect_fxn;
 486         dbll_init_fxn init_fxn;
 487         dbll_load_fxn load_fxn;
 488         dbll_load_sect_fxn load_sect_fxn;
 489         dbll_open_fxn open_fxn;
 490         dbll_read_sect_fxn read_sect_fxn;
 491         dbll_set_attrs_fxn set_attrs_fxn;
 492         dbll_unload_fxn unload_fxn;
 493         dbll_unload_sect_fxn unload_sect_fxn;
 494 };
 495
 496 #endif /* DBLDEFS_ */