Commit | Line | Data |
---|---|---|
6280238c ORL |
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" | |
6280238c ORL |
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 | ||
6280238c ORL |
40 | /* |
41 | * Function prototypes for writing memory to a DSP system, allocating | |
42 | * and freeing DSP memory. | |
43 | */ | |
5e2eae57 | 44 | typedef u32(*cod_writefxn) (void *priv_ref, u32 dsp_add, |
95870a88 | 45 | void *pbuf, u32 ul_num_bytes, u32 mem_space); |
6280238c ORL |
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: | |
e436d07d | 72 | * manager: created manager object |
383b8345 | 73 | * str_zl_file: ZL DLL filename, of length < COD_MAXPATHLENGTH. |
6280238c ORL |
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. | |
383b8345 | 81 | * str_zl_file != NULL |
6280238c ORL |
82 | * Ensures: |
83 | */ | |
e6bf74f0 | 84 | extern int cod_create(struct cod_manager **mgr, |
5db9e2bf | 85 | char *str_zl_file); |
6280238c ORL |
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 | |
383b8345 | 141 | * sz_name: location to store library name on output. |
6280238c ORL |
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. | |
383b8345 | 149 | * sz_name != NULL. |
6280238c ORL |
150 | * Ensures: |
151 | */ | |
152 | extern int cod_get_base_name(struct cod_manager *cod_mgr_obj, | |
383b8345 | 153 | char *sz_name, u32 usize); |
6280238c ORL |
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 | |
318b5df9 | 161 | * entry_pt: pointer to location for entry point |
6280238c ORL |
162 | * Returns: |
163 | * 0: Success. | |
164 | * Requires: | |
165 | * COD module initialized. | |
166 | * valid cod_mgr_obj. | |
318b5df9 | 167 | * entry_pt != NULL. |
6280238c ORL |
168 | * Ensures: |
169 | */ | |
170 | extern int cod_get_entry(struct cod_manager *cod_mgr_obj, | |
318b5df9 | 171 | u32 *entry_pt); |
6280238c ORL |
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 | |
e436d07d | 179 | * loader: location to store loader handle on output. |
6280238c ORL |
180 | * Returns: |
181 | * 0: Success. | |
182 | * Requires: | |
183 | * COD module initialized. | |
184 | * valid cod_mgr_obj. | |
e436d07d | 185 | * loader != NULL. |
6280238c ORL |
186 | * Ensures: |
187 | */ | |
188 | extern int cod_get_loader(struct cod_manager *cod_mgr_obj, | |
e436d07d | 189 | struct dbll_tar_obj **loader); |
6280238c ORL |
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(). | |
383b8345 RS |
198 | * str_sect: name of the section, with or without leading "." |
199 | * addr: Location to store address. | |
318b5df9 | 200 | * len: Location to store length. |
6280238c ORL |
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. | |
383b8345 RS |
208 | * str_sect != NULL; |
209 | * addr != NULL; | |
318b5df9 | 210 | * len != NULL; |
6280238c | 211 | * Ensures: |
318b5df9 | 212 | * 0: *addr and *len contain the address and length of the |
6280238c | 213 | * section. |
318b5df9 | 214 | * else: *addr == 0 and *len == 0; |
6280238c ORL |
215 | * |
216 | */ | |
217 | extern int cod_get_section(struct cod_libraryobj *lib, | |
9d7d0a52 | 218 | char *str_sect, |
e6bf74f0 | 219 | u32 *addr, u32 *len); |
6280238c ORL |
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. | |
383b8345 | 238 | * str_sym != NULL. |
6280238c ORL |
239 | * pul_value != NULL. |
240 | * Ensures: | |
241 | */ | |
242 | extern int cod_get_sym_value(struct cod_manager *cod_mgr_obj, | |
e6bf74f0 | 243 | char *str_sym, u32 * pul_value); |
6280238c ORL |
244 | |
245 | /* | |
246 | * ======== cod_init ======== | |
247 | * Purpose: | |
248 | * Initialize the COD module's private state. | |
249 | * Parameters: | |
250 | * None. | |
251 | * Returns: | |
25985edc | 252 | * TRUE if initialized; FALSE if error occurred. |
6280238c ORL |
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 | |
95870a88 | 268 | * num_argc: number of arguments in the args array |
6280238c ORL |
269 | * args: array of strings for arguments to DSP program |
270 | * write_fxn: board-specific function to write data to DSP system | |
aa09b091 | 271 | * arb: arbitrary pointer to be passed as first arg to write_fxn |
6280238c ORL |
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. | |
95870a88 | 279 | * num_argc > 0. |
a6bff488 RS |
280 | * args != NULL. |
281 | * args[0] != NULL. | |
6280238c ORL |
282 | * pfn_write != NULL. |
283 | * Ensures: | |
284 | */ | |
285 | extern int cod_load_base(struct cod_manager *cod_mgr_obj, | |
95870a88 | 286 | u32 num_argc, char *args[], |
aa09b091 | 287 | cod_writefxn pfn_write, void *arb, |
6280238c ORL |
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 | |
383b8345 | 296 | * sz_coff_path: Coff file to open. |
6280238c ORL |
297 | * flags: COD_NOLOAD (don't load symbols) or COD_SYMB (load |
298 | * symbols). | |
daa89e6c | 299 | * lib_obj: Handle returned that can be used in calls to cod_close |
6280238c ORL |
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. | |
383b8345 | 308 | * sz_coff_path != NULL. |
6280238c ORL |
309 | * Ensures: |
310 | */ | |
311 | extern int cod_open(struct cod_manager *hmgr, | |
9d7d0a52 | 312 | char *sz_coff_path, |
e6bf74f0 | 313 | u32 flags, struct cod_libraryobj **lib_obj); |
6280238c ORL |
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 | |
383b8345 | 321 | * sz_coff_path: Coff file to open. |
6280238c ORL |
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. | |
383b8345 | 329 | * sz_coff_path != NULL. |
6280238c ORL |
330 | * Ensures: |
331 | */ | |
9d7d0a52 | 332 | extern int cod_open_base(struct cod_manager *hmgr, char *sz_coff_path, |
6280238c ORL |
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 | |
383b8345 | 341 | * str_sect - name of the section, with or without leading "." |
13b18c29 | 342 | * str_content - buffer to store content of the section. |
6280238c ORL |
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. | |
383b8345 | 349 | * str_sect != NULL; |
13b18c29 | 350 | * str_content != NULL; |
6280238c | 351 | * Ensures: |
13b18c29 | 352 | * 0: *str_content stores the content of the named section. |
6280238c ORL |
353 | */ |
354 | extern int cod_read_section(struct cod_libraryobj *lib, | |
9d7d0a52 | 355 | char *str_sect, |
e6bf74f0 | 356 | char *str_content, u32 content_size); |
6280238c ORL |
357 | |
358 | #endif /* COD_ */ |