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

   1 /*
   2  * cod.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * Code management module for DSPs. This module provides an interface
   7  * interface for loading both static and dynamic code objects onto DSP
   8  * systems.
   9  *
  10  * Copyright (C) 2005-2006 Texas Instruments, Inc.
  11  *
  12  * This package is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License version 2 as
  14  * published by the Free Software Foundation.
  15  *
  16  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  17  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  18  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  19  */
  20
  21 #ifndef COD_
  22 #define COD_
  23
  24 #include <dspbridge/dblldefs.h>
  25
  26 #define COD_MAXPATHLENGTH       255
  27 #define COD_TRACEBEG            "SYS_PUTCBEG"
  28 #define COD_TRACEEND            "SYS_PUTCEND"
  29 #define COD_TRACECURPOS "BRIDGE_SYS_PUTC_current"
  30 #define COD_TRACESECT           "trace"
  31 #define COD_TRACEBEGOLD         "PUTCBEG"
  32 #define COD_TRACEENDOLD         "PUTCEND"
  33
  34 #define COD_NOLOAD              DBLL_NOLOAD
  35 #define COD_SYMB                DBLL_SYMB
  36
  37 /* COD code manager handle */
  38 struct cod_manager;
  39
  40 /* COD library handle */
  41 struct cod_libraryobj;
  42
  43 /* COD attributes */
  44 struct cod_attrs {
  45         u32 ul_reserved;
  46 };
  47
  48 /*
  49  *  Function prototypes for writing memory to a DSP system, allocating
  50  *  and freeing DSP memory.
  51  */
  52 typedef u32(*cod_writefxn) (void *priv_ref, u32 dsp_add,
  53                             void *pbuf, u32 ul_num_bytes, u32 mem_space);
  54
  55 /*
  56  *  ======== cod_close ========
  57  *  Purpose:
  58  *      Close a library opened with cod_open().
  59  *  Parameters:
  60  *      lib             - Library handle returned by cod_open().
  61  *  Returns:
  62  *      None.
  63  *  Requires:
  64  *      COD module initialized.
  65  *      valid lib.
  66  *  Ensures:
  67  *
  68  */
  69 extern void cod_close(struct cod_libraryobj *lib);
  70
  71 /*
  72  *  ======== cod_create ========
  73  *  Purpose:
  74  *      Create an object to manage code on a DSP system. This object can be
  75  *      used to load an initial program image with arguments that can later
  76  *      be expanded with dynamically loaded object files.
  77  *      Symbol table information is managed by this object and can be retrieved
  78  *      using the cod_get_sym_value() function.
  79  *  Parameters:
  80  *      manager:        created manager object
  81  *      str_zl_file:    ZL DLL filename, of length < COD_MAXPATHLENGTH.
  82  *      attrs:          attributes to be used by this object. A NULL value
  83  *                      will cause default attrs to be used.
  84  *  Returns:
  85  *      0:                Success.
  86  *      -ESPIPE:   ZL_Create failed.
  87  *      -ENOSYS:           attrs was not NULL.  We don't yet support
  88  *                              non default values of attrs.
  89  *  Requires:
  90  *      COD module initialized.
  91  *      str_zl_file != NULL
  92  *  Ensures:
  93  */
  94 extern int cod_create(struct cod_manager **mgr,
  95                              char *str_zl_file,
  96                              const struct cod_attrs *attrs);
  97
  98 /*
  99  *  ======== cod_delete ========
 100  *  Purpose:
 101  *      Delete a code manager object.
 102  *  Parameters:
 103  *      cod_mgr_obj:   handle of manager to be deleted
 104  *  Returns:
 105  *      None.
 106  *  Requires:
 107  *      COD module initialized.
 108  *      valid cod_mgr_obj.
 109  *  Ensures:
 110  */
 111 extern void cod_delete(struct cod_manager *cod_mgr_obj);
 112
 113 /*
 114  *  ======== cod_exit ========
 115  *  Purpose:
 116  *      Discontinue usage of the COD module.
 117  *  Parameters:
 118  *      None.
 119  *  Returns:
 120  *      None.
 121  *  Requires:
 122  *      COD initialized.
 123  *  Ensures:
 124  *      Resources acquired in cod_init(void) are freed.
 125  */
 126 extern void cod_exit(void);
 127
 128 /*
 129  *  ======== cod_get_base_lib ========
 130  *  Purpose:
 131  *      Get handle to the base image DBL library.
 132  *  Parameters:
 133  *      cod_mgr_obj:   handle of manager to be deleted
 134  *      plib:       location to store library handle on output.
 135  *  Returns:
 136  *      0:    Success.
 137  *  Requires:
 138  *      COD module initialized.
 139  *      valid cod_mgr_obj.
 140  *      plib != NULL.
 141  *  Ensures:
 142  */
 143 extern int cod_get_base_lib(struct cod_manager *cod_mgr_obj,
 144                                    struct dbll_library_obj **plib);
 145
 146 /*
 147  *  ======== cod_get_base_name ========
 148  *  Purpose:
 149  *      Get the name of the base image DBL library.
 150  *  Parameters:
 151  *      cod_mgr_obj:   handle of manager to be deleted
 152  *      sz_name:    location to store library name on output.
 153  *      usize:       size of name buffer.
 154  *  Returns:
 155  *      0:    Success.
 156  *      -EPERM:  Buffer too small.
 157  *  Requires:
 158  *      COD module initialized.
 159  *      valid cod_mgr_obj.
 160  *      sz_name != NULL.
 161  *  Ensures:
 162  */
 163 extern int cod_get_base_name(struct cod_manager *cod_mgr_obj,
 164                                     char *sz_name, u32 usize);
 165
 166 /*
 167  *  ======== cod_get_entry ========
 168  *  Purpose:
 169  *      Retrieve the entry point of a loaded DSP program image
 170  *  Parameters:
 171  *      cod_mgr_obj:   handle of manager to be deleted
 172  *      entry_pt:   pointer to location for entry point
 173  *  Returns:
 174  *      0:       Success.
 175  *  Requires:
 176  *      COD module initialized.
 177  *      valid cod_mgr_obj.
 178  *      entry_pt != NULL.
 179  *  Ensures:
 180  */
 181 extern int cod_get_entry(struct cod_manager *cod_mgr_obj,
 182                                 u32 *entry_pt);
 183
 184 /*
 185  *  ======== cod_get_loader ========
 186  *  Purpose:
 187  *      Get handle to the DBL loader.
 188  *  Parameters:
 189  *      cod_mgr_obj:   handle of manager to be deleted
 190  *      loader:     location to store loader handle on output.
 191  *  Returns:
 192  *      0:    Success.
 193  *  Requires:
 194  *      COD module initialized.
 195  *      valid cod_mgr_obj.
 196  *      loader != NULL.
 197  *  Ensures:
 198  */
 199 extern int cod_get_loader(struct cod_manager *cod_mgr_obj,
 200                                  struct dbll_tar_obj **loader);
 201
 202 /*
 203  *  ======== cod_get_section ========
 204  *  Purpose:
 205  *      Retrieve the starting address and length of a section in the COFF file
 206  *      given the section name.
 207  *  Parameters:
 208  *      lib         Library handle returned from cod_open().
 209  *      str_sect:   name of the section, with or without leading "."
 210  *      addr:       Location to store address.
 211  *      len:        Location to store length.
 212  *  Returns:
 213  *      0:                Success
 214  *      -ESPIPE:  Symbols could not be found or have not been loaded onto
 215  *                the board.
 216  *  Requires:
 217  *      COD module initialized.
 218  *      valid cod_mgr_obj.
 219  *      str_sect != NULL;
 220  *      addr != NULL;
 221  *      len != NULL;
 222  *  Ensures:
 223  *      0:  *addr and *len contain the address and length of the
 224  *                 section.
 225  *      else:  *addr == 0 and *len == 0;
 226  *
 227  */
 228 extern int cod_get_section(struct cod_libraryobj *lib,
 229                                   char *str_sect,
 230                                   u32 *addr, u32 *len);
 231
 232 /*
 233  *  ======== cod_get_sym_value ========
 234  *  Purpose:
 235  *      Retrieve the value for the specified symbol. The symbol is first
 236  *      searched for literally and then, if not found, searched for as a
 237  *      C symbol.
 238  *  Parameters:
 239  *      lib:        library handle returned from cod_open().
 240  *      pstrSymbol: name of the symbol
 241  *      value:      value of the symbol
 242  *  Returns:
 243  *      0:                Success.
 244  *      -ESPIPE:  Symbols could not be found or have not been loaded onto
 245  *                the board.
 246  *  Requires:
 247  *      COD module initialized.
 248  *      Valid cod_mgr_obj.
 249  *      str_sym != NULL.
 250  *      pul_value != NULL.
 251  *  Ensures:
 252  */
 253 extern int cod_get_sym_value(struct cod_manager *cod_mgr_obj,
 254                                     char *str_sym, u32 * pul_value);
 255
 256 /*
 257  *  ======== cod_init ========
 258  *  Purpose:
 259  *      Initialize the COD module's private state.
 260  *  Parameters:
 261  *      None.
 262  *  Returns:
 263  *      TRUE if initialized; FALSE if error occured.
 264  *  Requires:
 265  *  Ensures:
 266  *      A requirement for each of the other public COD functions.
 267  */
 268 extern bool cod_init(void);
 269
 270 /*
 271  *  ======== cod_load_base ========
 272  *  Purpose:
 273  *      Load the initial program image, optionally with command-line arguments,
 274  *      on the DSP system managed by the supplied handle. The program to be
 275  *      loaded must be the first element of the args array and must be a fully
 276  *      qualified pathname.
 277  *  Parameters:
 278  *      hmgr:       manager to load the code with
 279  *      num_argc:   number of arguments in the args array
 280  *      args:       array of strings for arguments to DSP program
 281  *      write_fxn:   board-specific function to write data to DSP system
 282  *      arb:       arbitrary pointer to be passed as first arg to write_fxn
 283  *      envp:       array of environment strings for DSP exec.
 284  *  Returns:
 285  *      0:                   Success.
 286  *      -EBADF:       Failed to open target code.
 287  *  Requires:
 288  *      COD module initialized.
 289  *      hmgr is valid.
 290  *      num_argc > 0.
 291  *      args != NULL.
 292  *      args[0] != NULL.
 293  *      pfn_write != NULL.
 294  *  Ensures:
 295  */
 296 extern int cod_load_base(struct cod_manager *cod_mgr_obj,
 297                                 u32 num_argc, char *args[],
 298                                 cod_writefxn pfn_write, void *arb,
 299                                 char *envp[]);
 300
 301 /*
 302  *  ======== cod_open ========
 303  *  Purpose:
 304  *      Open a library for reading sections. Does not load or set the base.
 305  *  Parameters:
 306  *      hmgr:           manager to load the code with
 307  *      sz_coff_path:   Coff file to open.
 308  *      flags:          COD_NOLOAD (don't load symbols) or COD_SYMB (load
 309  *                      symbols).
 310  *      lib_obj:        Handle returned that can be used in calls to cod_close
 311  *                      and cod_get_section.
 312  *  Returns:
 313  *      S_OK:                   Success.
 314  *      -EBADF:       Failed to open target code.
 315  *  Requires:
 316  *      COD module initialized.
 317  *      hmgr is valid.
 318  *      flags == COD_NOLOAD || flags == COD_SYMB.
 319  *      sz_coff_path != NULL.
 320  *  Ensures:
 321  */
 322 extern int cod_open(struct cod_manager *hmgr,
 323                            char *sz_coff_path,
 324                            u32 flags, struct cod_libraryobj **lib_obj);
 325
 326 /*
 327  *  ======== cod_open_base ========
 328  *  Purpose:
 329  *      Open base image for reading sections. Does not load the base.
 330  *  Parameters:
 331  *      hmgr:           manager to load the code with
 332  *      sz_coff_path:   Coff file to open.
 333  *      flags:          Specifies whether to load symbols.
 334  *  Returns:
 335  *      0:            Success.
 336  *      -EBADF:   Failed to open target code.
 337  *  Requires:
 338  *      COD module initialized.
 339  *      hmgr is valid.
 340  *      sz_coff_path != NULL.
 341  *  Ensures:
 342  */
 343 extern int cod_open_base(struct cod_manager *hmgr, char *sz_coff_path,
 344                                 dbll_flags flags);
 345
 346 /*
 347  *  ======== cod_read_section ========
 348  *  Purpose:
 349  *      Retrieve the content of a code section given the section name.
 350  *  Parameters:
 351  *      cod_mgr_obj    - manager in which to search for the symbol
 352  *      str_sect    - name of the section, with or without leading "."
 353  *      str_content - buffer to store content of the section.
 354  *  Returns:
 355  *      0: on success, error code on failure
 356  *      -ESPIPE:  Symbols have not been loaded onto the board.
 357  *  Requires:
 358  *      COD module initialized.
 359  *      valid cod_mgr_obj.
 360  *      str_sect != NULL;
 361  *      str_content != NULL;
 362  *  Ensures:
 363  *      0:  *str_content stores the content of the named section.
 364  */
 365 extern int cod_read_section(struct cod_libraryobj *lib,
 366                                    char *str_sect,
 367                                    char *str_content, u32 content_size);
 368
 369 #endif /* COD_ */