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 */ 47extern 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 */ 71extern 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 */ 92extern 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 */ 108extern 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 */ 131extern 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 */ 145extern 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 */ 172extern 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 */ 202extern 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 */ 232extern 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 */ 264extern 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 */ 297extern 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 */ 313extern 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 */ 333extern 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 */ 355extern int dcd_unregister_object(struct dsp_uuid *uuid_obj, 356 enum dsp_dcdobjtype obj_type); 357 358#endif /* _DBDCD_H */ 359