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_get_base_lib ======== 104 * Purpose: 105 * Get handle to the base image DBL library. 106 * Parameters: 107 * cod_mgr_obj: handle of manager to be deleted 108 * plib: location to store library handle on output. 109 * Returns: 110 * 0: Success. 111 * Requires: 112 * COD module initialized. 113 * valid cod_mgr_obj. 114 * plib != NULL. 115 * Ensures: 116 */ 117 extern int cod_get_base_lib(struct cod_manager *cod_mgr_obj, 118 struct dbll_library_obj **plib); 119 120 /* 121 * ======== cod_get_base_name ======== 122 * Purpose: 123 * Get the name of the base image DBL library. 124 * Parameters: 125 * cod_mgr_obj: handle of manager to be deleted 126 * sz_name: location to store library name on output. 127 * usize: size of name buffer. 128 * Returns: 129 * 0: Success. 130 * -EPERM: Buffer too small. 131 * Requires: 132 * COD module initialized. 133 * valid cod_mgr_obj. 134 * sz_name != NULL. 135 * Ensures: 136 */ 137 extern int cod_get_base_name(struct cod_manager *cod_mgr_obj, 138 char *sz_name, u32 usize); 139 140 /* 141 * ======== cod_get_entry ======== 142 * Purpose: 143 * Retrieve the entry point of a loaded DSP program image 144 * Parameters: 145 * cod_mgr_obj: handle of manager to be deleted 146 * entry_pt: pointer to location for entry point 147 * Returns: 148 * 0: Success. 149 * Requires: 150 * COD module initialized. 151 * valid cod_mgr_obj. 152 * entry_pt != NULL. 153 * Ensures: 154 */ 155 extern int cod_get_entry(struct cod_manager *cod_mgr_obj, 156 u32 *entry_pt); 157 158 /* 159 * ======== cod_get_loader ======== 160 * Purpose: 161 * Get handle to the DBL loader. 162 * Parameters: 163 * cod_mgr_obj: handle of manager to be deleted 164 * loader: location to store loader handle on output. 165 * Returns: 166 * 0: Success. 167 * Requires: 168 * COD module initialized. 169 * valid cod_mgr_obj. 170 * loader != NULL. 171 * Ensures: 172 */ 173 extern int cod_get_loader(struct cod_manager *cod_mgr_obj, 174 struct dbll_tar_obj **loader); 175 176 /* 177 * ======== cod_get_section ======== 178 * Purpose: 179 * Retrieve the starting address and length of a section in the COFF file 180 * given the section name. 181 * Parameters: 182 * lib Library handle returned from cod_open(). 183 * str_sect: name of the section, with or without leading "." 184 * addr: Location to store address. 185 * len: Location to store length. 186 * Returns: 187 * 0: Success 188 * -ESPIPE: Symbols could not be found or have not been loaded onto 189 * the board. 190 * Requires: 191 * COD module initialized. 192 * valid cod_mgr_obj. 193 * str_sect != NULL; 194 * addr != NULL; 195 * len != NULL; 196 * Ensures: 197 * 0: *addr and *len contain the address and length of the 198 * section. 199 * else: *addr == 0 and *len == 0; 200 * 201 */ 202 extern int cod_get_section(struct cod_libraryobj *lib, 203 char *str_sect, 204 u32 *addr, u32 *len); 205 206 /* 207 * ======== cod_get_sym_value ======== 208 * Purpose: 209 * Retrieve the value for the specified symbol. The symbol is first 210 * searched for literally and then, if not found, searched for as a 211 * C symbol. 212 * Parameters: 213 * lib: library handle returned from cod_open(). 214 * pstrSymbol: name of the symbol 215 * value: value of the symbol 216 * Returns: 217 * 0: Success. 218 * -ESPIPE: Symbols could not be found or have not been loaded onto 219 * the board. 220 * Requires: 221 * COD module initialized. 222 * Valid cod_mgr_obj. 223 * str_sym != NULL. 224 * pul_value != NULL. 225 * Ensures: 226 */ 227 extern int cod_get_sym_value(struct cod_manager *cod_mgr_obj, 228 char *str_sym, u32 * pul_value); 229 230 /* 231 * ======== cod_load_base ======== 232 * Purpose: 233 * Load the initial program image, optionally with command-line arguments, 234 * on the DSP system managed by the supplied handle. The program to be 235 * loaded must be the first element of the args array and must be a fully 236 * qualified pathname. 237 * Parameters: 238 * hmgr: manager to load the code with 239 * num_argc: number of arguments in the args array 240 * args: array of strings for arguments to DSP program 241 * write_fxn: board-specific function to write data to DSP system 242 * arb: arbitrary pointer to be passed as first arg to write_fxn 243 * envp: array of environment strings for DSP exec. 244 * Returns: 245 * 0: Success. 246 * -EBADF: Failed to open target code. 247 * Requires: 248 * COD module initialized. 249 * hmgr is valid. 250 * num_argc > 0. 251 * args != NULL. 252 * args[0] != NULL. 253 * pfn_write != NULL. 254 * Ensures: 255 */ 256 extern int cod_load_base(struct cod_manager *cod_mgr_obj, 257 u32 num_argc, char *args[], 258 cod_writefxn pfn_write, void *arb, 259 char *envp[]); 260 261 /* 262 * ======== cod_open ======== 263 * Purpose: 264 * Open a library for reading sections. Does not load or set the base. 265 * Parameters: 266 * hmgr: manager to load the code with 267 * sz_coff_path: Coff file to open. 268 * flags: COD_NOLOAD (don't load symbols) or COD_SYMB (load 269 * symbols). 270 * lib_obj: Handle returned that can be used in calls to cod_close 271 * and cod_get_section. 272 * Returns: 273 * S_OK: Success. 274 * -EBADF: Failed to open target code. 275 * Requires: 276 * COD module initialized. 277 * hmgr is valid. 278 * flags == COD_NOLOAD || flags == COD_SYMB. 279 * sz_coff_path != NULL. 280 * Ensures: 281 */ 282 extern int cod_open(struct cod_manager *hmgr, 283 char *sz_coff_path, 284 u32 flags, struct cod_libraryobj **lib_obj); 285 286 /* 287 * ======== cod_open_base ======== 288 * Purpose: 289 * Open base image for reading sections. Does not load the base. 290 * Parameters: 291 * hmgr: manager to load the code with 292 * sz_coff_path: Coff file to open. 293 * flags: Specifies whether to load symbols. 294 * Returns: 295 * 0: Success. 296 * -EBADF: Failed to open target code. 297 * Requires: 298 * COD module initialized. 299 * hmgr is valid. 300 * sz_coff_path != NULL. 301 * Ensures: 302 */ 303 extern int cod_open_base(struct cod_manager *hmgr, char *sz_coff_path, 304 dbll_flags flags); 305 306 /* 307 * ======== cod_read_section ======== 308 * Purpose: 309 * Retrieve the content of a code section given the section name. 310 * Parameters: 311 * cod_mgr_obj - manager in which to search for the symbol 312 * str_sect - name of the section, with or without leading "." 313 * str_content - buffer to store content of the section. 314 * Returns: 315 * 0: on success, error code on failure 316 * -ESPIPE: Symbols have not been loaded onto the board. 317 * Requires: 318 * COD module initialized. 319 * valid cod_mgr_obj. 320 * str_sect != NULL; 321 * str_content != NULL; 322 * Ensures: 323 * 0: *str_content stores the content of the named section. 324 */ 325 extern int cod_read_section(struct cod_libraryobj *lib, 326 char *str_sect, 327 char *str_content, u32 content_size); 328 329 #endif /* COD_ */ 330