4 * DSP-BIOS Bridge driver support functions for TI OMAP processors.
6 * Defines the DSP/BIOS Bridge Configuration Database (DCD) API.
8 * Copyright (C) 2008 Texas Instruments, Inc.
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.
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.
22 #include <dspbridge/dbdcddef.h>
23 #include <dspbridge/host_os.h>
24 #include <dspbridge/nldrdefs.h>
27 * ======== dcd_auto_register ========
29 * This function automatically registers DCD objects specified in a
30 * special COFF section called ".dcd_register"
32 * hdcd_mgr: A DCD manager handle.
33 * sz_coff_path: Pointer to name of COFF file containing DCD
34 * objects to be registered.
37 * -EACCES: Unable to find auto-registration/read/load section.
38 * -EFAULT: Invalid DCD_HMANAGER handle..
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.
47 extern int dcd_auto_register(struct dcd_manager *hdcd_mgr,
51 * ======== dcd_auto_unregister ========
53 * This function automatically unregisters DCD objects specified in a
54 * special COFF section called ".dcd_register"
56 * hdcd_mgr: A DCD manager handle.
57 * sz_coff_path: Pointer to name of COFF file containing
58 * DCD objects to be unregistered.
61 * -EACCES: Unable to find auto-registration/read/load section.
62 * -EFAULT: Invalid DCD_HMANAGER handle..
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.
71 extern int dcd_auto_unregister(struct dcd_manager *hdcd_mgr,
75 * ======== dcd_create_manager ========
77 * This function creates a DCD module manager.
79 * sz_zl_dll_name: Pointer to a DLL name string.
80 * dcd_mgr: A pointer to a DCD manager handle.
83 * -ENOMEM: Unable to allocate memory for DCD manager handle.
84 * -EPERM: General failure.
87 * sz_zl_dll_name is non-NULL.
88 * dcd_mgr is non-NULL.
90 * A DCD manager handle is created.
92 extern int dcd_create_manager(char *sz_zl_dll_name,
93 struct dcd_manager **dcd_mgr);
96 * ======== dcd_destroy_manager ========
98 * This function destroys a DCD module manager.
100 * hdcd_mgr: A DCD manager handle.
103 * -EFAULT: Invalid DCD manager handle.
108 extern int dcd_destroy_manager(struct dcd_manager *hdcd_mgr);
111 * ======== dcd_enumerate_object ========
113 * This function enumerates currently visible DSP/BIOS Bridge objects
114 * and returns the UUID and type of each enumerated object.
116 * index: The object enumeration index.
117 * obj_type: Type of object to enumerate.
118 * uuid_obj: Pointer to a dsp_uuid object.
121 * -EPERM: Unable to enumerate through the DCD database.
122 * ENODATA: Enumeration completed. This is not an error code.
125 * uuid_obj is a valid pointer.
128 * This function can be used in conjunction with dcd_get_object_def to
129 * retrieve object properties.
131 extern int dcd_enumerate_object(s32 index,
132 enum dsp_dcdobjtype obj_type,
133 struct dsp_uuid *uuid_obj);
136 * ======== dcd_exit ========
138 * This function cleans up the DCD module.
145 extern void dcd_exit(void);
148 * ======== dcd_get_dep_libs ========
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
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
162 * -ENOMEM: Memory allocation failure.
163 * -EACCES: Failure to read section containing library info.
164 * -EPERM: General failure.
169 * dep_lib_uuids != NULL.
172 extern int dcd_get_dep_libs(struct dcd_manager *hdcd_mgr,
173 struct dsp_uuid *uuid_obj,
175 struct dsp_uuid *dep_lib_uuids,
176 bool *prstnt_dep_libs,
177 enum nldr_phase phase);
180 * ======== dcd_get_num_dep_libs ========
182 * Given the uuid of a library, determine its number of dependent
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
192 * -ENOMEM: Memory allocation failure.
193 * -EACCES: Failure to read section containing library info.
194 * -EPERM: General failure.
202 extern int dcd_get_num_dep_libs(struct dcd_manager *hdcd_mgr,
203 struct dsp_uuid *uuid_obj,
206 enum nldr_phase phase);
209 * ======== dcd_get_library_name ========
211 * This function returns the name of a (dynamic) library for a given
214 * hdcd_mgr: A DCD manager handle.
215 * uuid_obj: Pointer to a dsp_uuid that represents a unique DSP/BIOS
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
223 * -EPERM: General failure.
227 * str_lib_name != NULL.
232 extern int dcd_get_library_name(struct dcd_manager *hdcd_mgr,
233 struct dsp_uuid *uuid_obj,
236 enum nldr_phase phase,
240 * ======== dcd_get_object_def ========
242 * This function returns the properties/attributes of a DSP/BIOS Bridge
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.
254 * -EACCES: Unable to access/read/parse/load content of object code
256 * -EPERM: General failure.
257 * -EFAULT: Invalid DCD_HMANAGER handle.
260 * obj_uuid is non-NULL.
261 * obj_def is non-NULL.
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);
270 * ======== dcd_get_objects ========
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.
278 * hdcd_mgr: A DCD manager handle.
279 * sz_coff_path: Pointer to name of COFF file containing DCD
281 * register_fxn: Callback fxn to be applied on each located
283 * handle: Handle to pass to callback.
286 * -EACCES: Unable to access/read/parse/load content of object code
288 * -EFAULT: Invalid DCD_HMANAGER handle..
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.
297 extern int dcd_get_objects(struct dcd_manager *hdcd_mgr,
299 dcd_registerfxn register_fxn, void *handle);
302 * ======== dcd_init ========
304 * This function initializes DCD.
307 * FALSE: Initialization failed.
308 * TRUE: Initialization succeeded.
313 extern bool dcd_init(void);
316 * ======== dcd_register_object ========
318 * This function registers a DSP/BIOS Bridge object in the DCD database.
320 * uuid_obj: Pointer to a dsp_uuid that identifies a DSP/BIOS
322 * obj_type: Type of object.
323 * psz_path_name: Path to the object's COFF file.
326 * -EPERM: Failed to register object.
329 * uuid_obj and szPathName are non-NULL values.
330 * obj_type is a valid type value.
333 extern int dcd_register_object(struct dsp_uuid *uuid_obj,
334 enum dsp_dcdobjtype obj_type,
335 char *psz_path_name);
338 * ======== dcd_unregister_object ========
340 * This function de-registers a valid DSP/BIOS Bridge object from the DCD
343 * uuid_obj: Pointer to a dsp_uuid that identifies a DSP/BIOS Bridge
345 * obj_type: Type of object.
348 * -EPERM: Unable to de-register the specified object.
351 * uuid_obj is a non-NULL value.
352 * obj_type is a valid type value.
355 extern int dcd_unregister_object(struct dsp_uuid *uuid_obj,
356 enum dsp_dcdobjtype obj_type);
358 #endif /* _DBDCD_H */