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