Fix common misspellings
[deliverable/linux.git] / drivers / staging / tidspbridge / include / dspbridge / cod.h
CommitLineData
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 */
35struct cod_manager;
36
37/* COD library handle */
38struct cod_libraryobj;
39
6280238c
ORL
40/*
41 * Function prototypes for writing memory to a DSP system, allocating
42 * and freeing DSP memory.
43 */
5e2eae57 44typedef 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 */
61extern 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 84extern 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 */
100extern 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 */
115extern 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 */
132extern 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 */
152extern 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 */
170extern 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 */
188extern 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 */
217extern 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 */
242extern 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 */
257extern 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 */
285extern 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 */
311extern 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 332extern 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 */
354extern 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_ */
This page took 0.108695 seconds and 5 git commands to generate.