4 * DSP-BIOS Bridge driver support functions for TI OMAP processors.
6 * Code management module for DSPs. This module provides an interface
7 * interface for loading both static and dynamic code objects onto DSP
10 * Copyright (C) 2005-2006 Texas Instruments, Inc.
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.
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.
24 #include <dspbridge/dblldefs.h>
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"
34 #define COD_NOLOAD DBLL_NOLOAD
35 #define COD_SYMB DBLL_SYMB
37 /* COD code manager handle */
40 /* COD library handle */
41 struct cod_libraryobj;
49 * Function prototypes for writing memory to a DSP system, allocating
50 * and freeing DSP memory.
52 typedef u32(*cod_writefxn) (void *priv_ref, u32 dsp_add,
53 void *pbuf, u32 ul_num_bytes, u32 mem_space);
56 * ======== cod_close ========
58 * Close a library opened with cod_open().
60 * lib - Library handle returned by cod_open().
64 * COD module initialized.
69 extern void cod_close(struct cod_libraryobj *lib);
72 * ======== cod_create ========
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.
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.
86 * -ESPIPE: ZL_Create failed.
87 * -ENOSYS: attrs was not NULL. We don't yet support
88 * non default values of attrs.
90 * COD module initialized.
94 extern int cod_create(struct cod_manager **mgr,
96 const struct cod_attrs *attrs);
99 * ======== cod_delete ========
101 * Delete a code manager object.
103 * cod_mgr_obj: handle of manager to be deleted
107 * COD module initialized.
111 extern void cod_delete(struct cod_manager *cod_mgr_obj);
114 * ======== cod_exit ========
116 * Discontinue usage of the COD module.
124 * Resources acquired in cod_init(void) are freed.
126 extern void cod_exit(void);
129 * ======== cod_get_base_lib ========
131 * Get handle to the base image DBL library.
133 * cod_mgr_obj: handle of manager to be deleted
134 * plib: location to store library handle on output.
138 * COD module initialized.
143 extern int cod_get_base_lib(struct cod_manager *cod_mgr_obj,
144 struct dbll_library_obj **plib);
147 * ======== cod_get_base_name ========
149 * Get the name of the base image DBL library.
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.
156 * -EPERM: Buffer too small.
158 * COD module initialized.
163 extern int cod_get_base_name(struct cod_manager *cod_mgr_obj,
164 char *sz_name, u32 usize);
167 * ======== cod_get_entry ========
169 * Retrieve the entry point of a loaded DSP program image
171 * cod_mgr_obj: handle of manager to be deleted
172 * entry_pt: pointer to location for entry point
176 * COD module initialized.
181 extern int cod_get_entry(struct cod_manager *cod_mgr_obj,
185 * ======== cod_get_loader ========
187 * Get handle to the DBL loader.
189 * cod_mgr_obj: handle of manager to be deleted
190 * loader: location to store loader handle on output.
194 * COD module initialized.
199 extern int cod_get_loader(struct cod_manager *cod_mgr_obj,
200 struct dbll_tar_obj **loader);
203 * ======== cod_get_section ========
205 * Retrieve the starting address and length of a section in the COFF file
206 * given the section name.
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.
214 * -ESPIPE: Symbols could not be found or have not been loaded onto
217 * COD module initialized.
223 * 0: *addr and *len contain the address and length of the
225 * else: *addr == 0 and *len == 0;
228 extern int cod_get_section(struct cod_libraryobj *lib,
230 u32 *addr, u32 *len);
233 * ======== cod_get_sym_value ========
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
239 * lib: library handle returned from cod_open().
240 * pstrSymbol: name of the symbol
241 * value: value of the symbol
244 * -ESPIPE: Symbols could not be found or have not been loaded onto
247 * COD module initialized.
253 extern int cod_get_sym_value(struct cod_manager *cod_mgr_obj,
254 char *str_sym, u32 * pul_value);
257 * ======== cod_init ========
259 * Initialize the COD module's private state.
263 * TRUE if initialized; FALSE if error occured.
266 * A requirement for each of the other public COD functions.
268 extern bool cod_init(void);
271 * ======== cod_load_base ========
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.
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.
286 * -EBADF: Failed to open target code.
288 * COD module initialized.
296 extern int cod_load_base(struct cod_manager *cod_mgr_obj,
297 u32 num_argc, char *args[],
298 cod_writefxn pfn_write, void *arb,
302 * ======== cod_open ========
304 * Open a library for reading sections. Does not load or set the base.
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
310 * lib_obj: Handle returned that can be used in calls to cod_close
311 * and cod_get_section.
314 * -EBADF: Failed to open target code.
316 * COD module initialized.
318 * flags == COD_NOLOAD || flags == COD_SYMB.
319 * sz_coff_path != NULL.
322 extern int cod_open(struct cod_manager *hmgr,
324 u32 flags, struct cod_libraryobj **lib_obj);
327 * ======== cod_open_base ========
329 * Open base image for reading sections. Does not load the base.
331 * hmgr: manager to load the code with
332 * sz_coff_path: Coff file to open.
333 * flags: Specifies whether to load symbols.
336 * -EBADF: Failed to open target code.
338 * COD module initialized.
340 * sz_coff_path != NULL.
343 extern int cod_open_base(struct cod_manager *hmgr, char *sz_coff_path,
347 * ======== cod_read_section ========
349 * Retrieve the content of a code section given the section name.
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.
355 * 0: on success, error code on failure
356 * -ESPIPE: Symbols have not been loaded onto the board.
358 * COD module initialized.
361 * str_content != NULL;
363 * 0: *str_content stores the content of the named section.
365 extern int cod_read_section(struct cod_libraryobj *lib,
367 char *str_content, u32 content_size);