1 /* 2 * dblldefs.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Copyright (C) 2005-2006 Texas Instruments, Inc. 7 * 8 * This package is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License version 2 as 10 * published by the Free Software Foundation. 11 * 12 * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 13 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED 14 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 15 */ 16 17 #ifndef DBLLDEFS_ 18 #define DBLLDEFS_ 19 20 /* 21 * Bit masks for dbl_flags. 22 */ 23 #define DBLL_NOLOAD 0x0 /* Don't load symbols, code, or data */ 24 #define DBLL_SYMB 0x1 /* load symbols */ 25 #define DBLL_CODE 0x2 /* load code */ 26 #define DBLL_DATA 0x4 /* load data */ 27 #define DBLL_DYNAMIC 0x8 /* dynamic load */ 28 #define DBLL_BSS 0x20 /* Unitialized section */ 29 30 #define DBLL_MAXPATHLENGTH 255 31 32 /* 33 * ======== DBLL_Target ======== 34 * 35 */ 36 struct dbll_tar_obj; 37 38 /* 39 * ======== dbll_flags ======== 40 * Specifies whether to load code, data, or symbols 41 */ 42 typedef s32 dbll_flags; 43 44 /* 45 * ======== DBLL_Library ======== 46 * 47 */ 48 struct dbll_library_obj; 49 50 /* 51 * ======== dbll_sect_info ======== 52 * For collecting info on overlay sections 53 */ 54 struct dbll_sect_info { 55 const char *name; /* name of section */ 56 u32 sect_run_addr; /* run address of section */ 57 u32 sect_load_addr; /* load address of section */ 58 u32 size; /* size of section (target MAUs) */ 59 dbll_flags type; /* Code, data, or BSS */ 60 }; 61 62 /* 63 * ======== dbll_sym_val ======== 64 * (Needed for dynamic load library) 65 */ 66 struct dbll_sym_val { 67 u32 value; 68 }; 69 70 /* 71 * ======== dbll_alloc_fxn ======== 72 * Allocate memory function. Allocate or reserve (if reserved == TRUE) 73 * "size" bytes of memory from segment "space" and return the address in 74 * *dsp_address (or starting at *dsp_address if reserve == TRUE). Returns 0 on 75 * success, or an error code on failure. 76 */ 77 typedef s32(*dbll_alloc_fxn) (void *hdl, s32 space, u32 size, u32 align, 78 u32 *dsp_address, s32 seg_id, s32 req, 79 bool reserved); 80 81 /* 82 * ======== dbll_close_fxn ======== 83 */ 84 typedef s32(*dbll_f_close_fxn) (void *); 85 86 /* 87 * ======== dbll_free_fxn ======== 88 * Free memory function. Free, or unreserve (if reserved == TRUE) "size" 89 * bytes of memory from segment "space" 90 */ 91 typedef bool(*dbll_free_fxn) (void *hdl, u32 addr, s32 space, u32 size, 92 bool reserved); 93 94 /* 95 * ======== dbll_f_open_fxn ======== 96 */ 97 typedef void *(*dbll_f_open_fxn) (const char *, const char *); 98 99 /* 100 * ======== dbll_log_write_fxn ======== 101 * Function to call when writing data from a section, to log the info. 102 * Can be NULL if no logging is required. 103 */ 104 typedef int(*dbll_log_write_fxn) (void *handle, 105 struct dbll_sect_info *sect, u32 addr, 106 u32 bytes); 107 108 /* 109 * ======== dbll_read_fxn ======== 110 */ 111 typedef s32(*dbll_read_fxn) (void *, size_t, size_t, void *); 112 113 /* 114 * ======== dbll_seek_fxn ======== 115 */ 116 typedef s32(*dbll_seek_fxn) (void *, long, int); 117 118 /* 119 * ======== dbll_sym_lookup ======== 120 * Symbol lookup function - Find the symbol name and return its value. 121 * 122 * Parameters: 123 * handle - Opaque handle 124 * parg - Opaque argument. 125 * name - Name of symbol to lookup. 126 * sym - Location to store address of symbol structure. 127 * 128 * Returns: 129 * TRUE: Success (symbol was found). 130 * FALSE: Failed to find symbol. 131 */ 132 typedef bool(*dbll_sym_lookup) (void *handle, void *parg, void *rmm_handle, 133 const char *name, struct dbll_sym_val ** sym); 134 135 /* 136 * ======== dbll_tell_fxn ======== 137 */ 138 typedef s32(*dbll_tell_fxn) (void *); 139 140 /* 141 * ======== dbll_write_fxn ======== 142 * Write memory function. Write "n" HOST bytes of memory to segment "mtype" 143 * starting at address "dsp_address" from the buffer "buf". The buffer is 144 * formatted as an array of words appropriate for the DSP. 145 */ 146 typedef s32(*dbll_write_fxn) (void *hdl, u32 dsp_address, void *buf, 147 u32 n, s32 mtype); 148 149 /* 150 * ======== dbll_attrs ======== 151 */ 152 struct dbll_attrs { 153 dbll_alloc_fxn alloc; 154 dbll_free_fxn free; 155 void *rmm_handle; /* Handle to pass to alloc, free functions */ 156 dbll_write_fxn write; 157 void *input_params; /* Handle to pass to write, cinit function */ 158 bool base_image; 159 dbll_log_write_fxn log_write; 160 void *log_write_handle; 161 162 /* Symbol matching function and handle to pass to it */ 163 dbll_sym_lookup sym_lookup; 164 void *sym_handle; 165 void *sym_arg; 166 167 /* 168 * These file manipulation functions should be compatible with the 169 * "C" run time library functions of the same name. 170 */ 171 s32(*fread) (void *, size_t, size_t, void *); 172 s32(*fseek) (void *, long, int); 173 s32(*ftell) (void *); 174 s32(*fclose) (void *); 175 void *(*fopen) (const char *, const char *); 176 }; 177 178 /* 179 * ======== dbll_close ======== 180 * Close library opened with dbll_open. 181 * Parameters: 182 * lib - Handle returned from dbll_open(). 183 * Returns: 184 * Requires: 185 * DBL initialized. 186 * Valid lib. 187 * Ensures: 188 */ 189 typedef void (*dbll_close_fxn) (struct dbll_library_obj *library); 190 191 /* 192 * ======== dbll_create ======== 193 * Create a target object, specifying the alloc, free, and write functions. 194 * Parameters: 195 * target_obj - Location to store target handle on output. 196 * pattrs - Attributes. 197 * Returns: 198 * 0: Success. 199 * -ENOMEM: Memory allocation failed. 200 * Requires: 201 * DBL initialized. 202 * pattrs != NULL. 203 * target_obj != NULL; 204 * Ensures: 205 * Success: *target_obj != NULL. 206 * Failure: *target_obj == NULL. 207 */ 208 typedef int(*dbll_create_fxn) (struct dbll_tar_obj **target_obj, 209 struct dbll_attrs *attrs); 210 211 /* 212 * ======== dbll_delete ======== 213 * Delete target object and free resources for any loaded libraries. 214 * Parameters: 215 * target - Handle returned from DBLL_Create(). 216 * Returns: 217 * Requires: 218 * DBL initialized. 219 * Valid target. 220 * Ensures: 221 */ 222 typedef void (*dbll_delete_fxn) (struct dbll_tar_obj *target); 223 224 /* 225 * ======== dbll_exit ======== 226 * Discontinue use of DBL module. 227 * Parameters: 228 * Returns: 229 * Requires: 230 * refs > 0. 231 * Ensures: 232 * refs >= 0. 233 */ 234 typedef void (*dbll_exit_fxn) (void); 235 236 /* 237 * ======== dbll_get_addr ======== 238 * Get address of name in the specified library. 239 * Parameters: 240 * lib - Handle returned from dbll_open(). 241 * name - Name of symbol 242 * sym_val - Location to store symbol address on output. 243 * Returns: 244 * TRUE: Success. 245 * FALSE: Symbol not found. 246 * Requires: 247 * DBL initialized. 248 * Valid library. 249 * name != NULL. 250 * sym_val != NULL. 251 * Ensures: 252 */ 253 typedef bool(*dbll_get_addr_fxn) (struct dbll_library_obj *lib, char *name, 254 struct dbll_sym_val **sym_val); 255 256 /* 257 * ======== dbll_get_attrs ======== 258 * Retrieve the attributes of the target. 259 * Parameters: 260 * target - Handle returned from DBLL_Create(). 261 * pattrs - Location to store attributes on output. 262 * Returns: 263 * Requires: 264 * DBL initialized. 265 * Valid target. 266 * pattrs != NULL. 267 * Ensures: 268 */ 269 typedef void (*dbll_get_attrs_fxn) (struct dbll_tar_obj *target, 270 struct dbll_attrs *attrs); 271 272 /* 273 * ======== dbll_get_c_addr ======== 274 * Get address of "C" name on the specified library. 275 * Parameters: 276 * lib - Handle returned from dbll_open(). 277 * name - Name of symbol 278 * sym_val - Location to store symbol address on output. 279 * Returns: 280 * TRUE: Success. 281 * FALSE: Symbol not found. 282 * Requires: 283 * DBL initialized. 284 * Valid target. 285 * name != NULL. 286 * sym_val != NULL. 287 * Ensures: 288 */ 289 typedef bool(*dbll_get_c_addr_fxn) (struct dbll_library_obj *lib, char *name, 290 struct dbll_sym_val **sym_val); 291 292 /* 293 * ======== dbll_get_sect ======== 294 * Get address and size of a named section. 295 * Parameters: 296 * lib - Library handle returned from dbll_open(). 297 * name - Name of section. 298 * paddr - Location to store section address on output. 299 * psize - Location to store section size on output. 300 * Returns: 301 * 0: Success. 302 * -ENXIO: Section not found. 303 * Requires: 304 * DBL initialized. 305 * Valid lib. 306 * name != NULL. 307 * paddr != NULL; 308 * psize != NULL. 309 * Ensures: 310 */ 311 typedef int(*dbll_get_sect_fxn) (struct dbll_library_obj *lib, 312 char *name, u32 * addr, u32 * size); 313 314 /* 315 * ======== dbll_init ======== 316 * Initialize DBL module. 317 * Parameters: 318 * Returns: 319 * TRUE: Success. 320 * FALSE: Failure. 321 * Requires: 322 * refs >= 0. 323 * Ensures: 324 * Success: refs > 0. 325 * Failure: refs >= 0. 326 */ 327 typedef bool(*dbll_init_fxn) (void); 328 329 /* 330 * ======== dbll_load ======== 331 * Load library onto the target. 332 * 333 * Parameters: 334 * lib - Library handle returned from dbll_open(). 335 * flags - Load code, data and/or symbols. 336 * attrs - May contain alloc, free, and write function. 337 * entry_pt - Location to store program entry on output. 338 * Returns: 339 * 0: Success. 340 * -EBADF: File read failed. 341 * -EILSEQ: Failure in dynamic loader library. 342 * Requires: 343 * DBL initialized. 344 * Valid lib. 345 * entry != NULL. 346 * Ensures: 347 */ 348 typedef int(*dbll_load_fxn) (struct dbll_library_obj *lib, 349 dbll_flags flags, 350 struct dbll_attrs *attrs, u32 *entry); 351 /* 352 * ======== dbll_open ======== 353 * dbll_open() returns a library handle that can be used to load/unload 354 * the symbols/code/data via dbll_load()/dbll_unload(). 355 * Parameters: 356 * target - Handle returned from dbll_create(). 357 * file - Name of file to open. 358 * flags - If flags & DBLL_SYMB, load symbols. 359 * lib_obj - Location to store library handle on output. 360 * Returns: 361 * 0: Success. 362 * -ENOMEM: Memory allocation failure. 363 * -EBADF: File open/read failure. 364 * Unable to determine target type. 365 * Requires: 366 * DBL initialized. 367 * Valid target. 368 * file != NULL. 369 * lib_obj != NULL. 370 * dbll_attrs fopen function non-NULL. 371 * Ensures: 372 * Success: Valid *lib_obj. 373 * Failure: *lib_obj == NULL. 374 */ 375 typedef int(*dbll_open_fxn) (struct dbll_tar_obj *target, char *file, 376 dbll_flags flags, 377 struct dbll_library_obj **lib_obj); 378 379 /* 380 * ======== dbll_read_sect ======== 381 * Read COFF section into a character buffer. 382 * Parameters: 383 * lib - Library handle returned from dbll_open(). 384 * name - Name of section. 385 * pbuf - Buffer to write section contents into. 386 * size - Buffer size 387 * Returns: 388 * 0: Success. 389 * -ENXIO: Named section does not exists. 390 * Requires: 391 * DBL initialized. 392 * Valid lib. 393 * name != NULL. 394 * pbuf != NULL. 395 * size != 0. 396 * Ensures: 397 */ 398 typedef int(*dbll_read_sect_fxn) (struct dbll_library_obj *lib, 399 char *name, char *content, 400 u32 cont_size); 401 /* 402 * ======== dbll_unload ======== 403 * Unload library loaded with dbll_load(). 404 * Parameters: 405 * lib - Handle returned from dbll_open(). 406 * attrs - Contains free() function and handle to pass to it. 407 * Returns: 408 * Requires: 409 * DBL initialized. 410 * Valid lib. 411 * Ensures: 412 */ 413 typedef void (*dbll_unload_fxn) (struct dbll_library_obj *library, 414 struct dbll_attrs *attrs); 415 struct dbll_fxns { 416 dbll_close_fxn close_fxn; 417 dbll_create_fxn create_fxn; 418 dbll_delete_fxn delete_fxn; 419 dbll_exit_fxn exit_fxn; 420 dbll_get_attrs_fxn get_attrs_fxn; 421 dbll_get_addr_fxn get_addr_fxn; 422 dbll_get_c_addr_fxn get_c_addr_fxn; 423 dbll_get_sect_fxn get_sect_fxn; 424 dbll_init_fxn init_fxn; 425 dbll_load_fxn load_fxn; 426 dbll_open_fxn open_fxn; 427 dbll_read_sect_fxn read_sect_fxn; 428 dbll_unload_fxn unload_fxn; 429 }; 430 431 #endif /* DBLDEFS_ */ 432