Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
nldrdefs.h
Go to the documentation of this file.
1 /*
2  * nldrdefs.h
3  *
4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
5  *
6  * Global Dynamic + static/overlay Node loader (NLDR) constants and types.
7  *
8  * Copyright (C) 2008 Texas Instruments, Inc.
9  *
10  * This package is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License version 2 as
12  * published by the Free Software Foundation.
13  *
14  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
15  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
16  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17  */
18 
19 #ifndef NLDRDEFS_
20 #define NLDRDEFS_
21 
22 #include <dspbridge/dbdcddef.h>
23 #include <dspbridge/devdefs.h>
24 
25 #define NLDR_MAXPATHLENGTH 255
26 /* NLDR Objects: */
27 struct nldr_object;
28 struct nldr_nodeobject;
29 
30 /*
31  * ======== nldr_loadtype ========
32  * Load types for a node. Must match values in node.h55.
33  */
35  NLDR_STATICLOAD, /* Linked in base image, not overlay */
36  NLDR_DYNAMICLOAD, /* Dynamically loaded node */
37  NLDR_OVLYLOAD /* Linked in base image, overlay node */
38 };
39 
40 /*
41  * ======== nldr_ovlyfxn ========
42  * Causes code or data to be copied from load address to run address. This
43  * is the "cod_writefxn" that gets passed to the DBLL_Library and is used as
44  * the ZL write function.
45  *
46  * Parameters:
47  * priv_ref: Handle to identify the node.
48  * dsp_run_addr: Run address of code or data.
49  * dsp_load_addr: Load address of code or data.
50  * ul_num_bytes: Number of (GPP) bytes to copy.
51  * mem_space: RMS_CODE or RMS_DATA.
52  * Returns:
53  * ul_num_bytes: Success.
54  * 0: Failure.
55  * Requires:
56  * Ensures:
57  */
58 typedef u32(*nldr_ovlyfxn) (void *priv_ref, u32 dsp_run_addr,
59  u32 dsp_load_addr, u32 ul_num_bytes, u32 mem_space);
60 
61 /*
62  * ======== nldr_writefxn ========
63  * Write memory function. Used for dynamic load writes.
64  * Parameters:
65  * priv_ref: Handle to identify the node.
66  * dsp_add: Address of code or data.
67  * pbuf: Code or data to be written
68  * ul_num_bytes: Number of (GPP) bytes to write.
69  * mem_space: DBLL_DATA or DBLL_CODE.
70  * Returns:
71  * ul_num_bytes: Success.
72  * 0: Failure.
73  * Requires:
74  * Ensures:
75  */
76 typedef u32(*nldr_writefxn) (void *priv_ref,
77  u32 dsp_add, void *pbuf,
78  u32 ul_num_bytes, u32 mem_space);
79 
80 /*
81  * ======== nldr_attrs ========
82  * Attributes passed to nldr_create function.
83  */
84 struct nldr_attrs {
89 };
90 
91 /*
92  * ======== nldr_phase ========
93  * Indicates node create, delete, or execute phase function.
94  */
95 enum nldr_phase {
100 };
101 
102 /*
103  * Typedefs of loader functions imported from a DLL, or defined in a
104  * function table.
105  */
106 
107 /*
108  * ======== nldr_allocate ========
109  * Allocate resources to manage the loading of a node on the DSP.
110  *
111  * Parameters:
112  * nldr_obj: Handle of loader that will load the node.
113  * priv_ref: Handle to identify the node.
114  * node_props: Pointer to a dcd_nodeprops for the node.
115  * nldr_nodeobj: Location to store node handle on output. This handle
116  * will be passed to nldr_load/nldr_unload.
117  * pf_phase_split: pointer to int variable referenced in node.c
118  * Returns:
119  * 0: Success.
120  * -ENOMEM: Insufficient memory on GPP.
121  * Requires:
122  * Valid nldr_obj.
123  * node_props != NULL.
124  * nldr_nodeobj != NULL.
125  * Ensures:
126  * 0: IsValidNode(*nldr_nodeobj).
127  * error: *nldr_nodeobj == NULL.
128  */
129 typedef int(*nldr_allocatefxn) (struct nldr_object *nldr_obj,
130  void *priv_ref,
131  const struct dcd_nodeprops
132  * node_props,
133  struct nldr_nodeobject
134  **nldr_nodeobj,
135  bool *pf_phase_split);
136 
137 /*
138  * ======== nldr_create ========
139  * Create a loader object. This object handles the loading and unloading of
140  * create, delete, and execute phase functions of nodes on the DSP target.
141  *
142  * Parameters:
143  * nldr: Location to store loader handle on output.
144  * hdev_obj: Device for this processor.
145  * pattrs: Loader attributes.
146  * Returns:
147  * 0: Success;
148  * -ENOMEM: Insufficient memory for requested resources.
149  * Requires:
150  * nldr != NULL.
151  * hdev_obj != NULL.
152  * pattrs != NULL.
153  * Ensures:
154  * 0: Valid *nldr.
155  * error: *nldr == NULL.
156  */
157 typedef int(*nldr_createfxn) (struct nldr_object **nldr,
158  struct dev_object *hdev_obj,
159  const struct nldr_attrs *pattrs);
160 
161 /*
162  * ======== nldr_delete ========
163  * Delete the NLDR loader.
164  *
165  * Parameters:
166  * nldr_obj: Node manager object.
167  * Returns:
168  * Requires:
169  * Valid nldr_obj.
170  * Ensures:
171  * nldr_obj invalid
172  */
173 typedef void (*nldr_deletefxn) (struct nldr_object *nldr_obj);
174 
175 /*
176  * ======== NLDR_Free ========
177  * Free resources allocated in nldr_allocate.
178  *
179  * Parameters:
180  * nldr_node_obj: Handle returned from nldr_allocate().
181  * Returns:
182  * Requires:
183  * Valid nldr_node_obj.
184  * Ensures:
185  */
186 typedef void (*nldr_freefxn) (struct nldr_nodeobject *nldr_node_obj);
187 
188 /*
189  * ======== nldr_get_fxn_addr ========
190  * Get address of create, delete, or execute phase function of a node on
191  * the DSP.
192  *
193  * Parameters:
194  * nldr_node_obj: Handle returned from nldr_allocate().
195  * str_fxn: Name of function.
196  * addr: Location to store function address.
197  * Returns:
198  * 0: Success.
199  * -ESPIPE: Address of function not found.
200  * Requires:
201  * Valid nldr_node_obj.
202  * addr != NULL;
203  * str_fxn != NULL;
204  * Ensures:
205  */
207  * nldr_node_obj,
208  char *str_fxn, u32 * addr);
209 
210 /*
211  * ======== nldr_load ========
212  * Load create, delete, or execute phase function of a node on the DSP.
213  *
214  * Parameters:
215  * nldr_node_obj: Handle returned from nldr_allocate().
216  * phase: Type of function to load (create, delete, or execute).
217  * Returns:
218  * 0: Success.
219  * -ENOMEM: Insufficient memory on GPP.
220  * -ENXIO: Can't overlay phase because overlay memory
221  * is already in use.
222  * -EILSEQ: Failure in dynamic loader library.
223  * Requires:
224  * Valid nldr_node_obj.
225  * Ensures:
226  */
227 typedef int(*nldr_loadfxn) (struct nldr_nodeobject *nldr_node_obj,
228  enum nldr_phase phase);
229 
230 /*
231  * ======== nldr_unload ========
232  * Unload create, delete, or execute phase function of a node on the DSP.
233  *
234  * Parameters:
235  * nldr_node_obj: Handle returned from nldr_allocate().
236  * phase: Node function to unload (create, delete, or execute).
237  * Returns:
238  * 0: Success.
239  * -ENOMEM: Insufficient memory on GPP.
240  * Requires:
241  * Valid nldr_node_obj.
242  * Ensures:
243  */
244 typedef int(*nldr_unloadfxn) (struct nldr_nodeobject *nldr_node_obj,
245  enum nldr_phase phase);
246 
247 /*
248  * ======== node_ldr_fxns ========
249  */
257 };
258 
259 #endif /* NLDRDEFS_ */