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 occurred. 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_ */ 359