1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
|
/*
* cod.h
*
* DSP-BIOS Bridge driver support functions for TI OMAP processors.
*
* Code management module for DSPs. This module provides an interface
* interface for loading both static and dynamic code objects onto DSP
* systems.
*
* Copyright (C) 2005-2006 Texas Instruments, Inc.
*
* This package is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*
* THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
* WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
*/
#ifndef COD_
#define COD_
#include <dspbridge/dblldefs.h>
#define COD_MAXPATHLENGTH 255
#define COD_TRACEBEG "SYS_PUTCBEG"
#define COD_TRACEEND "SYS_PUTCEND"
#define COD_TRACECURPOS "BRIDGE_SYS_PUTC_current"
#define COD_NOLOAD DBLL_NOLOAD
#define COD_SYMB DBLL_SYMB
/* COD code manager handle */
struct cod_manager;
/* COD library handle */
struct cod_libraryobj;
/*
* Function prototypes for writing memory to a DSP system, allocating
* and freeing DSP memory.
*/
typedef u32(*cod_writefxn) (void *priv_ref, u32 dsp_add,
void *pbuf, u32 ul_num_bytes, u32 mem_space);
/*
* ======== cod_close ========
* Purpose:
* Close a library opened with cod_open().
* Parameters:
* lib - Library handle returned by cod_open().
* Returns:
* None.
* Requires:
* COD module initialized.
* valid lib.
* Ensures:
*
*/
extern void cod_close(struct cod_libraryobj *lib);
/*
* ======== cod_create ========
* Purpose:
* Create an object to manage code on a DSP system. This object can be
* used to load an initial program image with arguments that can later
* be expanded with dynamically loaded object files.
* Symbol table information is managed by this object and can be retrieved
* using the cod_get_sym_value() function.
* Parameters:
* manager: created manager object
* str_zl_file: ZL DLL filename, of length < COD_MAXPATHLENGTH.
* Returns:
* 0: Success.
* -ESPIPE: ZL_Create failed.
* -ENOSYS: attrs was not NULL. We don't yet support
* non default values of attrs.
* Requires:
* COD module initialized.
* str_zl_file != NULL
* Ensures:
*/
extern int cod_create(struct cod_manager **mgr,
char *str_zl_file);
/*
* ======== cod_delete ========
* Purpose:
* Delete a code manager object.
* Parameters:
* cod_mgr_obj: handle of manager to be deleted
* Returns:
* None.
* Requires:
* COD module initialized.
* valid cod_mgr_obj.
* Ensures:
*/
extern void cod_delete(struct cod_manager *cod_mgr_obj);
/*
* ======== cod_exit ========
* Purpose:
* Discontinue usage of the COD module.
* Parameters:
* None.
* Returns:
* None.
* Requires:
* COD initialized.
* Ensures:
* Resources acquired in cod_init(void) are freed.
*/
extern void cod_exit(void);
/*
* ======== cod_get_base_lib ========
* Purpose:
* Get handle to the base image DBL library.
* Parameters:
* cod_mgr_obj: handle of manager to be deleted
* plib: location to store library handle on output.
* Returns:
* 0: Success.
* Requires:
* COD module initialized.
* valid cod_mgr_obj.
* plib != NULL.
* Ensures:
*/
extern int cod_get_base_lib(struct cod_manager *cod_mgr_obj,
struct dbll_library_obj **plib);
/*
* ======== cod_get_base_name ========
* Purpose:
* Get the name of the base image DBL library.
* Parameters:
* cod_mgr_obj: handle of manager to be deleted
* sz_name: location to store library name on output.
* usize: size of name buffer.
* Returns:
* 0: Success.
* -EPERM: Buffer too small.
* Requires:
* COD module initialized.
* valid cod_mgr_obj.
* sz_name != NULL.
* Ensures:
*/
extern int cod_get_base_name(struct cod_manager *cod_mgr_obj,
char *sz_name, u32 usize);
/*
* ======== cod_get_entry ========
* Purpose:
* Retrieve the entry point of a loaded DSP program image
* Parameters:
* cod_mgr_obj: handle of manager to be deleted
* entry_pt: pointer to location for entry point
* Returns:
* 0: Success.
* Requires:
* COD module initialized.
* valid cod_mgr_obj.
* entry_pt != NULL.
* Ensures:
*/
extern int cod_get_entry(struct cod_manager *cod_mgr_obj,
u32 *entry_pt);
/*
* ======== cod_get_loader ========
* Purpose:
* Get handle to the DBL loader.
* Parameters:
* cod_mgr_obj: handle of manager to be deleted
* loader: location to store loader handle on output.
* Returns:
* 0: Success.
* Requires:
* COD module initialized.
* valid cod_mgr_obj.
* loader != NULL.
* Ensures:
*/
extern int cod_get_loader(struct cod_manager *cod_mgr_obj,
struct dbll_tar_obj **loader);
/*
* ======== cod_get_section ========
* Purpose:
* Retrieve the starting address and length of a section in the COFF file
* given the section name.
* Parameters:
* lib Library handle returned from cod_open().
* str_sect: name of the section, with or without leading "."
* addr: Location to store address.
* len: Location to store length.
* Returns:
* 0: Success
* -ESPIPE: Symbols could not be found or have not been loaded onto
* the board.
* Requires:
* COD module initialized.
* valid cod_mgr_obj.
* str_sect != NULL;
* addr != NULL;
* len != NULL;
* Ensures:
* 0: *addr and *len contain the address and length of the
* section.
* else: *addr == 0 and *len == 0;
*
*/
extern int cod_get_section(struct cod_libraryobj *lib,
char *str_sect,
u32 *addr, u32 *len);
/*
* ======== cod_get_sym_value ========
* Purpose:
* Retrieve the value for the specified symbol. The symbol is first
* searched for literally and then, if not found, searched for as a
* C symbol.
* Parameters:
* lib: library handle returned from cod_open().
* pstrSymbol: name of the symbol
* value: value of the symbol
* Returns:
* 0: Success.
* -ESPIPE: Symbols could not be found or have not been loaded onto
* the board.
* Requires:
* COD module initialized.
* Valid cod_mgr_obj.
* str_sym != NULL.
* pul_value != NULL.
* Ensures:
*/
extern int cod_get_sym_value(struct cod_manager *cod_mgr_obj,
char *str_sym, u32 * pul_value);
/*
* ======== cod_init ========
* Purpose:
* Initialize the COD module's private state.
* Parameters:
* None.
* Returns:
* TRUE if initialized; FALSE if error occured.
* Requires:
* Ensures:
* A requirement for each of the other public COD functions.
*/
extern bool cod_init(void);
/*
* ======== cod_load_base ========
* Purpose:
* Load the initial program image, optionally with command-line arguments,
* on the DSP system managed by the supplied handle. The program to be
* loaded must be the first element of the args array and must be a fully
* qualified pathname.
* Parameters:
* hmgr: manager to load the code with
* num_argc: number of arguments in the args array
* args: array of strings for arguments to DSP program
* write_fxn: board-specific function to write data to DSP system
* arb: arbitrary pointer to be passed as first arg to write_fxn
* envp: array of environment strings for DSP exec.
* Returns:
* 0: Success.
* -EBADF: Failed to open target code.
* Requires:
* COD module initialized.
* hmgr is valid.
* num_argc > 0.
* args != NULL.
* args[0] != NULL.
* pfn_write != NULL.
* Ensures:
*/
extern int cod_load_base(struct cod_manager *cod_mgr_obj,
u32 num_argc, char *args[],
cod_writefxn pfn_write, void *arb,
char *envp[]);
/*
* ======== cod_open ========
* Purpose:
* Open a library for reading sections. Does not load or set the base.
* Parameters:
* hmgr: manager to load the code with
* sz_coff_path: Coff file to open.
* flags: COD_NOLOAD (don't load symbols) or COD_SYMB (load
* symbols).
* lib_obj: Handle returned that can be used in calls to cod_close
* and cod_get_section.
* Returns:
* S_OK: Success.
* -EBADF: Failed to open target code.
* Requires:
* COD module initialized.
* hmgr is valid.
* flags == COD_NOLOAD || flags == COD_SYMB.
* sz_coff_path != NULL.
* Ensures:
*/
extern int cod_open(struct cod_manager *hmgr,
char *sz_coff_path,
u32 flags, struct cod_libraryobj **lib_obj);
/*
* ======== cod_open_base ========
* Purpose:
* Open base image for reading sections. Does not load the base.
* Parameters:
* hmgr: manager to load the code with
* sz_coff_path: Coff file to open.
* flags: Specifies whether to load symbols.
* Returns:
* 0: Success.
* -EBADF: Failed to open target code.
* Requires:
* COD module initialized.
* hmgr is valid.
* sz_coff_path != NULL.
* Ensures:
*/
extern int cod_open_base(struct cod_manager *hmgr, char *sz_coff_path,
dbll_flags flags);
/*
* ======== cod_read_section ========
* Purpose:
* Retrieve the content of a code section given the section name.
* Parameters:
* cod_mgr_obj - manager in which to search for the symbol
* str_sect - name of the section, with or without leading "."
* str_content - buffer to store content of the section.
* Returns:
* 0: on success, error code on failure
* -ESPIPE: Symbols have not been loaded onto the board.
* Requires:
* COD module initialized.
* valid cod_mgr_obj.
* str_sect != NULL;
* str_content != NULL;
* Ensures:
* 0: *str_content stores the content of the named section.
*/
extern int cod_read_section(struct cod_libraryobj *lib,
char *str_sect,
char *str_content, u32 content_size);
#endif /* COD_ */
|
