Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
dbdcd.h
Go to the documentation of this file.
1 /*
2  * dbdcd.h
3  *
4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
5  *
6  * Defines the DSP/BIOS Bridge Configuration Database (DCD) API.
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 DBDCD_
20 #define DBDCD_
21 
22 #include <dspbridge/dbdcddef.h>
23 #include <dspbridge/host_os.h>
24 #include <dspbridge/nldrdefs.h>
25 
26 /*
27  * ======== dcd_auto_register ========
28  * Purpose:
29  * This function automatically registers DCD objects specified in a
30  * special COFF section called ".dcd_register"
31  * Parameters:
32  * hdcd_mgr: A DCD manager handle.
33  * sz_coff_path: Pointer to name of COFF file containing DCD
34  * objects to be registered.
35  * Returns:
36  * 0: Success.
37  * -EACCES: Unable to find auto-registration/read/load section.
38  * -EFAULT: Invalid DCD_HMANAGER handle..
39  * Requires:
40  * DCD initialized.
41  * Ensures:
42  * Note:
43  * Due to the DCD database construction, it is essential for a DCD-enabled
44  * COFF file to contain the right COFF sections, especially
45  * ".dcd_register", which is used for auto registration.
46  */
47 extern int dcd_auto_register(struct dcd_manager *hdcd_mgr,
48  char *sz_coff_path);
49 
50 /*
51  * ======== dcd_auto_unregister ========
52  * Purpose:
53  * This function automatically unregisters DCD objects specified in a
54  * special COFF section called ".dcd_register"
55  * Parameters:
56  * hdcd_mgr: A DCD manager handle.
57  * sz_coff_path: Pointer to name of COFF file containing
58  * DCD objects to be unregistered.
59  * Returns:
60  * 0: Success.
61  * -EACCES: Unable to find auto-registration/read/load section.
62  * -EFAULT: Invalid DCD_HMANAGER handle..
63  * Requires:
64  * DCD initialized.
65  * Ensures:
66  * Note:
67  * Due to the DCD database construction, it is essential for a DCD-enabled
68  * COFF file to contain the right COFF sections, especially
69  * ".dcd_register", which is used for auto unregistration.
70  */
71 extern int dcd_auto_unregister(struct dcd_manager *hdcd_mgr,
72  char *sz_coff_path);
73 
74 /*
75  * ======== dcd_create_manager ========
76  * Purpose:
77  * This function creates a DCD module manager.
78  * Parameters:
79  * sz_zl_dll_name: Pointer to a DLL name string.
80  * dcd_mgr: A pointer to a DCD manager handle.
81  * Returns:
82  * 0: Success.
83  * -ENOMEM: Unable to allocate memory for DCD manager handle.
84  * -EPERM: General failure.
85  * Requires:
86  * DCD initialized.
87  * sz_zl_dll_name is non-NULL.
88  * dcd_mgr is non-NULL.
89  * Ensures:
90  * A DCD manager handle is created.
91  */
92 extern int dcd_create_manager(char *sz_zl_dll_name,
93  struct dcd_manager **dcd_mgr);
94 
95 /*
96  * ======== dcd_destroy_manager ========
97  * Purpose:
98  * This function destroys a DCD module manager.
99  * Parameters:
100  * hdcd_mgr: A DCD manager handle.
101  * Returns:
102  * 0: Success.
103  * -EFAULT: Invalid DCD manager handle.
104  * Requires:
105  * DCD initialized.
106  * Ensures:
107  */
108 extern int dcd_destroy_manager(struct dcd_manager *hdcd_mgr);
109 
110 /*
111  * ======== dcd_enumerate_object ========
112  * Purpose:
113  * This function enumerates currently visible DSP/BIOS Bridge objects
114  * and returns the UUID and type of each enumerated object.
115  * Parameters:
116  * index: The object enumeration index.
117  * obj_type: Type of object to enumerate.
118  * uuid_obj: Pointer to a dsp_uuid object.
119  * Returns:
120  * 0: Success.
121  * -EPERM: Unable to enumerate through the DCD database.
122  * ENODATA: Enumeration completed. This is not an error code.
123  * Requires:
124  * DCD initialized.
125  * uuid_obj is a valid pointer.
126  * Ensures:
127  * Details:
128  * This function can be used in conjunction with dcd_get_object_def to
129  * retrieve object properties.
130  */
131 extern int dcd_enumerate_object(s32 index,
132  enum dsp_dcdobjtype obj_type,
133  struct dsp_uuid *uuid_obj);
134 
135 /*
136  * ======== dcd_exit ========
137  * Purpose:
138  * This function cleans up the DCD module.
139  * Parameters:
140  * Returns:
141  * Requires:
142  * DCD initialized.
143  * Ensures:
144  */
145 extern void dcd_exit(void);
146 
147 /*
148  * ======== dcd_get_dep_libs ========
149  * Purpose:
150  * Given the uuid of a library and size of array of uuids, this function
151  * fills the array with the uuids of all dependent libraries of the input
152  * library.
153  * Parameters:
154  * hdcd_mgr: A DCD manager handle.
155  * uuid_obj: Pointer to a dsp_uuid for a library.
156  * num_libs: Size of uuid array (number of library uuids).
157  * dep_lib_uuids: Array of dependent library uuids to be filled in.
158  * prstnt_dep_libs: Array indicating if corresponding lib is persistent.
159  * phase: phase to obtain correct input library
160  * Returns:
161  * 0: Success.
162  * -ENOMEM: Memory allocation failure.
163  * -EACCES: Failure to read section containing library info.
164  * -EPERM: General failure.
165  * Requires:
166  * DCD initialized.
167  * Valid hdcd_mgr.
168  * uuid_obj != NULL
169  * dep_lib_uuids != NULL.
170  * Ensures:
171  */
172 extern int dcd_get_dep_libs(struct dcd_manager *hdcd_mgr,
173  struct dsp_uuid *uuid_obj,
174  u16 num_libs,
175  struct dsp_uuid *dep_lib_uuids,
176  bool *prstnt_dep_libs,
177  enum nldr_phase phase);
178 
179 /*
180  * ======== dcd_get_num_dep_libs ========
181  * Purpose:
182  * Given the uuid of a library, determine its number of dependent
183  * libraries.
184  * Parameters:
185  * hdcd_mgr: A DCD manager handle.
186  * uuid_obj: Pointer to a dsp_uuid for a library.
187  * num_libs: Size of uuid array (number of library uuids).
188  * num_pers_libs: number of persistent dependent library.
189  * phase: Phase to obtain correct input library
190  * Returns:
191  * 0: Success.
192  * -ENOMEM: Memory allocation failure.
193  * -EACCES: Failure to read section containing library info.
194  * -EPERM: General failure.
195  * Requires:
196  * DCD initialized.
197  * Valid hdcd_mgr.
198  * uuid_obj != NULL
199  * num_libs != NULL.
200  * Ensures:
201  */
202 extern int dcd_get_num_dep_libs(struct dcd_manager *hdcd_mgr,
203  struct dsp_uuid *uuid_obj,
204  u16 *num_libs,
205  u16 *num_pers_libs,
206  enum nldr_phase phase);
207 
208 /*
209  * ======== dcd_get_library_name ========
210  * Purpose:
211  * This function returns the name of a (dynamic) library for a given
212  * UUID.
213  * Parameters:
214  * hdcd_mgr: A DCD manager handle.
215  * uuid_obj: Pointer to a dsp_uuid that represents a unique DSP/BIOS
216  * Bridge object.
217  * str_lib_name: Buffer to hold library name.
218  * buff_size: Contains buffer size. Set to string size on output.
219  * phase: Which phase to load
220  * phase_split: Are phases in multiple libraries
221  * Returns:
222  * 0: Success.
223  * -EPERM: General failure.
224  * Requires:
225  * DCD initialized.
226  * Valid hdcd_mgr.
227  * str_lib_name != NULL.
228  * uuid_obj != NULL
229  * buff_size != NULL.
230  * Ensures:
231  */
232 extern int dcd_get_library_name(struct dcd_manager *hdcd_mgr,
233  struct dsp_uuid *uuid_obj,
234  char *str_lib_name,
235  u32 *buff_size,
236  enum nldr_phase phase,
237  bool *phase_split);
238 
239 /*
240  * ======== dcd_get_object_def ========
241  * Purpose:
242  * This function returns the properties/attributes of a DSP/BIOS Bridge
243  * object.
244  * Parameters:
245  * hdcd_mgr: A DCD manager handle.
246  * uuid_obj: Pointer to a dsp_uuid that represents a unique
247  * DSP/BIOS Bridge object.
248  * obj_type: The type of DSP/BIOS Bridge object to be
249  * referenced (node, processor, etc).
250  * obj_def: Pointer to an object definition structure. A
251  * union of various possible DCD object types.
252  * Returns:
253  * 0: Success.
254  * -EACCES: Unable to access/read/parse/load content of object code
255  * section.
256  * -EPERM: General failure.
257  * -EFAULT: Invalid DCD_HMANAGER handle.
258  * Requires:
259  * DCD initialized.
260  * obj_uuid is non-NULL.
261  * obj_def is non-NULL.
262  * Ensures:
263  */
264 extern int dcd_get_object_def(struct dcd_manager *hdcd_mgr,
265  struct dsp_uuid *obj_uuid,
266  enum dsp_dcdobjtype obj_type,
267  struct dcd_genericobj *obj_def);
268 
269 /*
270  * ======== dcd_get_objects ========
271  * Purpose:
272  * This function finds all DCD objects specified in a special
273  * COFF section called ".dcd_register", and for each object,
274  * call a "register" function. The "register" function may perform
275  * various actions, such as 1) register nodes in the node database, 2)
276  * unregister nodes from the node database, and 3) add overlay nodes.
277  * Parameters:
278  * hdcd_mgr: A DCD manager handle.
279  * sz_coff_path: Pointer to name of COFF file containing DCD
280  * objects.
281  * register_fxn: Callback fxn to be applied on each located
282  * DCD object.
283  * handle: Handle to pass to callback.
284  * Returns:
285  * 0: Success.
286  * -EACCES: Unable to access/read/parse/load content of object code
287  * section.
288  * -EFAULT: Invalid DCD_HMANAGER handle..
289  * Requires:
290  * DCD initialized.
291  * Ensures:
292  * Note:
293  * Due to the DCD database construction, it is essential for a DCD-enabled
294  * COFF file to contain the right COFF sections, especially
295  * ".dcd_register", which is used for auto registration.
296  */
297 extern int dcd_get_objects(struct dcd_manager *hdcd_mgr,
298  char *sz_coff_path,
299  dcd_registerfxn register_fxn, void *handle);
300 
301 /*
302  * ======== dcd_init ========
303  * Purpose:
304  * This function initializes DCD.
305  * Parameters:
306  * Returns:
307  * FALSE: Initialization failed.
308  * TRUE: Initialization succeeded.
309  * Requires:
310  * Ensures:
311  * DCD initialized.
312  */
313 extern bool dcd_init(void);
314 
315 /*
316  * ======== dcd_register_object ========
317  * Purpose:
318  * This function registers a DSP/BIOS Bridge object in the DCD database.
319  * Parameters:
320  * uuid_obj: Pointer to a dsp_uuid that identifies a DSP/BIOS
321  * Bridge object.
322  * obj_type: Type of object.
323  * psz_path_name: Path to the object's COFF file.
324  * Returns:
325  * 0: Success.
326  * -EPERM: Failed to register object.
327  * Requires:
328  * DCD initialized.
329  * uuid_obj and szPathName are non-NULL values.
330  * obj_type is a valid type value.
331  * Ensures:
332  */
333 extern int dcd_register_object(struct dsp_uuid *uuid_obj,
334  enum dsp_dcdobjtype obj_type,
335  char *psz_path_name);
336 
337 /*
338  * ======== dcd_unregister_object ========
339  * Purpose:
340  * This function de-registers a valid DSP/BIOS Bridge object from the DCD
341  * database.
342  * Parameters:
343  * uuid_obj: Pointer to a dsp_uuid that identifies a DSP/BIOS Bridge
344  * object.
345  * obj_type: Type of object.
346  * Returns:
347  * 0: Success.
348  * -EPERM: Unable to de-register the specified object.
349  * Requires:
350  * DCD initialized.
351  * uuid_obj is a non-NULL value.
352  * obj_type is a valid type value.
353  * Ensures:
354  */
355 extern int dcd_unregister_object(struct dsp_uuid *uuid_obj,
356  enum dsp_dcdobjtype obj_type);
357 
358 #endif /* _DBDCD_H */