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  */
34 enum nldr_loadtype {
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 {
85 	nldr_ovlyfxn ovly;
86 	nldr_writefxn write;
87 	u16 dsp_word_size;
88 	u16 dsp_mau_size;
89 };
90 
91 /*
92  *  ======== nldr_phase ========
93  *  Indicates node create, delete, or execute phase function.
94  */
95 enum nldr_phase {
96 	NLDR_CREATE,
97 	NLDR_DELETE,
98 	NLDR_EXECUTE,
99 	NLDR_NOPHASE
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  *      nldr_init(void) called.
123  *      Valid nldr_obj.
124  *      node_props != NULL.
125  *      nldr_nodeobj != NULL.
126  *  Ensures:
127  *      0:        IsValidNode(*nldr_nodeobj).
128  *      error:          *nldr_nodeobj == NULL.
129  */
130 typedef int(*nldr_allocatefxn) (struct nldr_object *nldr_obj,
131 				       void *priv_ref,
132 				       const struct dcd_nodeprops
133 				       * node_props,
134 				       struct nldr_nodeobject
135 				       **nldr_nodeobj,
136 				       bool *pf_phase_split);
137 
138 /*
139  *  ======== nldr_create ========
140  *  Create a loader object. This object handles the loading and unloading of
141  *  create, delete, and execute phase functions of nodes on the DSP target.
142  *
143  *  Parameters:
144  *      nldr:           Location to store loader handle on output.
145  *      hdev_obj:     Device for this processor.
146  *      pattrs:         Loader attributes.
147  *  Returns:
148  *      0:        Success;
149  *      -ENOMEM:    Insufficient memory for requested resources.
150  *  Requires:
151  *      nldr_init(void) called.
152  *      nldr != NULL.
153  *      hdev_obj != NULL.
154  *	pattrs != NULL.
155  *  Ensures:
156  *      0:        Valid *nldr.
157  *      error:          *nldr == NULL.
158  */
159 typedef int(*nldr_createfxn) (struct nldr_object **nldr,
160 				     struct dev_object *hdev_obj,
161 				     const struct nldr_attrs *pattrs);
162 
163 /*
164  *  ======== nldr_delete ========
165  *  Delete the NLDR loader.
166  *
167  *  Parameters:
168  *      nldr_obj:          Node manager object.
169  *  Returns:
170  *  Requires:
171  *      nldr_init(void) called.
172  *      Valid nldr_obj.
173  *  Ensures:
174  *	nldr_obj invalid
175  */
176 typedef void (*nldr_deletefxn) (struct nldr_object *nldr_obj);
177 
178 /*
179  *  ======== nldr_exit ========
180  *  Discontinue usage of NLDR module.
181  *
182  *  Parameters:
183  *  Returns:
184  *  Requires:
185  *      nldr_init(void) successfully called before.
186  *  Ensures:
187  *      Any resources acquired in nldr_init(void) will be freed when last NLDR
188  *      client calls nldr_exit(void).
189  */
190 typedef void (*nldr_exitfxn) (void);
191 
192 /*
193  *  ======== NLDR_Free ========
194  *  Free resources allocated in nldr_allocate.
195  *
196  *  Parameters:
197  *      nldr_node_obj:      Handle returned from nldr_allocate().
198  *  Returns:
199  *  Requires:
200  *      nldr_init(void) called.
201  *      Valid nldr_node_obj.
202  *  Ensures:
203  */
204 typedef void (*nldr_freefxn) (struct nldr_nodeobject *nldr_node_obj);
205 
206 /*
207  *  ======== nldr_get_fxn_addr ========
208  *  Get address of create, delete, or execute phase function of a node on
209  *  the DSP.
210  *
211  *  Parameters:
212  *      nldr_node_obj:      Handle returned from nldr_allocate().
213  *      str_fxn:        Name of function.
214  *      addr:           Location to store function address.
215  *  Returns:
216  *      0:        Success.
217  *      -ESPIPE:    Address of function not found.
218  *  Requires:
219  *      nldr_init(void) called.
220  *      Valid nldr_node_obj.
221  *      addr != NULL;
222  *      str_fxn != NULL;
223  *  Ensures:
224  */
225 typedef int(*nldr_getfxnaddrfxn) (struct nldr_nodeobject
226 					 * nldr_node_obj,
227 					 char *str_fxn, u32 * addr);
228 
229 /*
230  *  ======== nldr_init ========
231  *  Initialize the NLDR module.
232  *
233  *  Parameters:
234  *  Returns:
235  *      TRUE if initialization succeeded, FALSE otherwise.
236  *  Ensures:
237  */
238 typedef bool(*nldr_initfxn) (void);
239 
240 /*
241  *  ======== nldr_load ========
242  *  Load create, delete, or execute phase function of a node on the DSP.
243  *
244  *  Parameters:
245  *      nldr_node_obj:      Handle returned from nldr_allocate().
246  *      phase:          Type of function to load (create, delete, or execute).
247  *  Returns:
248  *      0:                Success.
249  *      -ENOMEM:            Insufficient memory on GPP.
250  *      -ENXIO:     Can't overlay phase because overlay memory
251  *                              is already in use.
252  *      -EILSEQ:           Failure in dynamic loader library.
253  *  Requires:
254  *      nldr_init(void) called.
255  *      Valid nldr_node_obj.
256  *  Ensures:
257  */
258 typedef int(*nldr_loadfxn) (struct nldr_nodeobject *nldr_node_obj,
259 				   enum nldr_phase phase);
260 
261 /*
262  *  ======== nldr_unload ========
263  *  Unload create, delete, or execute phase function of a node on the DSP.
264  *
265  *  Parameters:
266  *      nldr_node_obj:      Handle returned from nldr_allocate().
267  *      phase:          Node function to unload (create, delete, or execute).
268  *  Returns:
269  *      0:        Success.
270  *      -ENOMEM:    Insufficient memory on GPP.
271  *  Requires:
272  *      nldr_init(void) called.
273  *      Valid nldr_node_obj.
274  *  Ensures:
275  */
276 typedef int(*nldr_unloadfxn) (struct nldr_nodeobject *nldr_node_obj,
277 				     enum nldr_phase phase);
278 
279 /*
280  *  ======== node_ldr_fxns ========
281  */
282 struct node_ldr_fxns {
283 	nldr_allocatefxn allocate;
284 	nldr_createfxn create;
285 	nldr_deletefxn delete;
286 	nldr_exitfxn exit;
287 	nldr_getfxnaddrfxn get_fxn_addr;
288 	nldr_initfxn init;
289 	nldr_loadfxn load;
290 	nldr_unloadfxn unload;
291 };
292 
293 #endif /* NLDRDEFS_ */
294