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 */ 38struct cod_manager; 39 40/* COD library handle */ 41struct cod_libraryobj; 42 43/* COD attributes */ 44struct 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 */ 52typedef 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 */ 69extern 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 */ 94extern 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 */ 111extern 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 */ 126extern 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 */ 143extern 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 */ 163extern 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 */ 181extern 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 */ 199extern 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 */ 228extern 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 */ 253extern 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 */ 268extern 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 */ 296extern 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 */ 322extern 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 */ 343extern 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 */ 365extern int cod_read_section(struct cod_libraryobj *lib, 366 char *str_sect, 367 char *str_content, u32 content_size); 368 369#endif /* COD_ */ 370