1 /* 2 * dspbridge/mpu_api/inc/dbdcd.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Copyright (C) 2007 Texas Instruments, Inc. 7 * 8 * This program is free software; you can redistribute it and/or modify it 9 * under the terms of the GNU Lesser General Public License as published 10 * by the Free Software Foundation version 2.1 of the License. 11 * 12 * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind, 13 * whether express or implied; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 */ 17 18 /* 19 * ======== dbdcd.h ======== 20 * Description: 21 * Defines the DSP/BIOS Bridge Configuration Database (DCD) API. 22 * 23 *! Revision History 24 *! ================ 25 *! 03-Dec-2003 map Changed DCD_OBJTYPE to DSP_DCDOBJTYPE 26 *! 24-Feb-2003 kc Updated DCD_AutoUnregister and DCD_GetObjects to simplify 27 *! DCD implementation. 28 *! 05-Aug-2002 jeh Added DCD_GetObjects(). 29 *! 11-Jul-2002 jeh Added DCD_GetDepLibs(), DCD_GetNumDepLibs(). 30 *! 22-Apr-2002 jeh Added DCD_GetLibraryName(). 31 *! 03-Apr-2001 sg Changed error names to have DCD_E* format. 32 *! 13-Feb-2001 kc Name changed from dcdbs.h to dbdcd.h. 33 *! 12-Dec-2000 kc Added DCD_AutoUnregister. 34 *! 09-Nov-2000 kc Updated usage of DCD_EnumerateObject. 35 *! 30-Oct-2000 kc Added DCD_AutoRegister. Updated error DCD error codes. 36 *! 29-Sep-2000 kc Incorporated code review comments. See 37 *! /src/reviews/dcd_review.txt. 38 *! 26-Jul-2000 kc Created. 39 *! 40 */ 41 42 #ifndef DBDCD_ 43 #define DBDCD_ 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 #include <dbdcddef.h> 50 #include <nldrdefs.h> 51 52 /* 53 * ======== DCD_AutoRegister ======== 54 * Purpose: 55 * This function automatically registers DCD objects specified in a 56 * special COFF section called ".dcd_register" 57 * Parameters: 58 * hDcdMgr: A DCD manager handle. 59 * pszCoffPath: Pointer to name of COFF file containing DCD 60 * objects to be registered. 61 * Returns: 62 * DSP_SOK: Success. 63 * DSP_EDCDNOAUTOREGISTER: Unable to find auto-registration section. 64 * DSP_EDCDREADSECT: Unable to read object code section. 65 * DSP_EDCDLOADBASE: Unable to load code base. 66 * DSP_EHANDLE: Invalid DCD_HMANAGER handle.. 67 * Requires: 68 * DCD initialized. 69 * Ensures: 70 * Note: 71 * Due to the DCD database construction, it is essential for a DCD-enabled 72 * COFF file to contain the right COFF sections, especially 73 * ".dcd_register", which is used for auto registration. 74 */ 75 extern DSP_STATUS DCD_AutoRegister(IN struct DCD_MANAGER* hDcdMgr, 76 IN CHAR * pszCoffPath); 77 78 /* 79 * ======== DCD_AutoUnregister ======== 80 * Purpose: 81 * This function automatically unregisters DCD objects specified in a 82 * special COFF section called ".dcd_register" 83 * Parameters: 84 * hDcdMgr: A DCD manager handle. 85 * pszCoffPath: Pointer to name of COFF file containing 86 * DCD objects to be unregistered. 87 * Returns: 88 * DSP_SOK: Success. 89 * DSP_EDCDNOAUTOREGISTER: Unable to find auto-registration section. 90 * DSP_EDCDREADSECT: Unable to read object code section. 91 * DSP_EDCDLOADBASE: Unable to load code base. 92 * DSP_EHANDLE: Invalid DCD_HMANAGER handle.. 93 * Requires: 94 * DCD initialized. 95 * Ensures: 96 * Note: 97 * Due to the DCD database construction, it is essential for a DCD-enabled 98 * COFF file to contain the right COFF sections, especially 99 * ".dcd_register", which is used for auto unregistration. 100 */ 101 extern DSP_STATUS DCD_AutoUnregister(IN struct DCD_MANAGER* hDcdMgr, 102 IN CHAR * pszCoffPath); 103 104 /* 105 * ======== DCD_CreateManager ======== 106 * Purpose: 107 * This function creates a DCD module manager. 108 * Parameters: 109 * pszZlDllName: Pointer to a DLL name string. 110 * phDcdMgr: A pointer to a DCD manager handle. 111 * Returns: 112 * DSP_SOK: Success. 113 * DSP_EMEMORY: Unable to allocate memory for DCD manager handle. 114 * DSP_EFAIL: General failure. 115 * Requires: 116 * DCD initialized. 117 * pszZlDllName is non-NULL. 118 * phDcdMgr is non-NULL. 119 * Ensures: 120 * A DCD manager handle is created. 121 */ 122 extern DSP_STATUS DCD_CreateManager(IN CHAR * pszZlDllName, 123 OUT struct DCD_MANAGER* * phDcdMgr); 124 125 /* 126 * ======== DCD_DestroyManager ======== 127 * Purpose: 128 * This function destroys a DCD module manager. 129 * Parameters: 130 * hDcdMgr: A DCD manager handle. 131 * Returns: 132 * DSP_SOK: Success. 133 * DSP_EHANDLE: Invalid DCD manager handle. 134 * Requires: 135 * DCD initialized. 136 * Ensures: 137 */ 138 extern DSP_STATUS DCD_DestroyManager(IN struct DCD_MANAGER* hDcdMgr); 139 140 /* 141 * ======== DCD_EnumerateObject ======== 142 * Purpose: 143 * This function enumerates currently visible DSP/BIOS Bridge objects 144 * and returns the UUID and type of each enumerated object. 145 * Parameters: 146 * cIndex: The object enumeration index. 147 * objType: Type of object to enumerate. 148 * pUuid: Pointer to a DSP_UUID object. 149 * Returns: 150 * DSP_SOK: Success. 151 * DSP_EFAIL: Unable to enumerate through the DCD database. 152 * DSP_SENUMCOMPLETE: Enumeration completed. This is not an error code. 153 * Requires: 154 * DCD initialized. 155 * pUuid is a valid pointer. 156 * Ensures: 157 * Details: 158 * This function can be used in conjunction with DCD_GetObjectDef to 159 * retrieve object properties. 160 */ 161 extern DSP_STATUS DCD_EnumerateObject(IN INT cIndex, 162 IN DSP_DCDOBJTYPE objType, 163 OUT struct DSP_UUID * pUuid); 164 165 /* 166 * ======== DCD_Exit ======== 167 * Purpose: 168 * This function cleans up the DCD module. 169 * Parameters: 170 * Returns: 171 * Requires: 172 * DCD initialized. 173 * Ensures: 174 */ 175 extern VOID DCD_Exit(); 176 177 /* 178 * ======== DCD_GetDepLibs ======== 179 * Purpose: 180 * Given the uuid of a library and size of array of uuids, this function 181 * fills the array with the uuids of all dependent libraries of the input 182 * library. 183 * Parameters: 184 * hDcdMgr: A DCD manager handle. 185 * pUuid: Pointer to a DSP_UUID for a library. 186 * numLibs: Size of uuid array (number of library uuids). 187 * pDepLibUuids: Array of dependent library uuids to be filled in. 188 * pPersistentDepLibs: Array indicating if corresponding lib is persistent. 189 * phase: phase to obtain correct input library 190 * Returns: 191 * DSP_SOK: Success. 192 * DSP_EMEMORY: Memory allocation failure. 193 * DSP_EDCDREADSECT: Failure to read section containing library info. 194 * DSP_EFAIL: General failure. 195 * Requires: 196 * DCD initialized. 197 * Valid hDcdMgr. 198 * pUuid != NULL 199 * pDepLibUuids != NULL. 200 * Ensures: 201 */ 202 extern DSP_STATUS DCD_GetDepLibs(IN struct DCD_MANAGER* hDcdMgr, 203 IN struct DSP_UUID * pUuid, 204 USHORT numLibs, 205 OUT struct DSP_UUID * pDepLibUuids, 206 OUT bool * pPersistentDepLibs, 207 IN NLDR_PHASE phase); 208 209 /* 210 * ======== DCD_GetNumDepLibs ======== 211 * Purpose: 212 * Given the uuid of a library, determine its number of dependent 213 * libraries. 214 * Parameters: 215 * hDcdMgr: A DCD manager handle. 216 * pUuid: Pointer to a DSP_UUID for a library. 217 * pNumLibs: Size of uuid array (number of library uuids). 218 * pNumPersLibs: number of persistent dependent library. 219 * phase: Phase to obtain correct input library 220 * Returns: 221 * DSP_SOK: Success. 222 * DSP_EMEMORY: Memory allocation failure. 223 * DSP_EDCDREADSECT: Failure to read section containing library info. 224 * DSP_EFAIL: General failure. 225 * Requires: 226 * DCD initialized. 227 * Valid hDcdMgr. 228 * pUuid != NULL 229 * pNumLibs != NULL. 230 * Ensures: 231 */ 232 extern DSP_STATUS DCD_GetNumDepLibs(IN struct DCD_MANAGER* hDcdMgr, 233 IN struct DSP_UUID * pUuid, 234 OUT USHORT * pNumLibs, 235 OUT USHORT * pNumPersLibs, 236 IN NLDR_PHASE phase); 237 238 /* 239 * ======== DCD_GetLibraryName ======== 240 * Purpose: 241 * This function returns the name of a (dynamic) library for a given 242 * UUID. 243 * Parameters: 244 * hDcdMgr: A DCD manager handle. 245 * pUuid: Pointer to a DSP_UUID that represents a unique DSP/BIOS 246 * Bridge object. 247 * pstrLibName: Buffer to hold library name. 248 * pdwSize: Contains buffer size. Set to string size on output. 249 * phase: Which phase to load 250 * fPhaseSplit: Are phases in multiple libraries 251 * Returns: 252 * DSP_SOK: Success. 253 * DSP_EFAIL: General failure. 254 * Requires: 255 * DCD initialized. 256 * Valid hDcdMgr. 257 * pstrLibName != NULL. 258 * pUuid != NULL 259 * pdwSize != NULL. 260 * Ensures: 261 */ 262 extern DSP_STATUS DCD_GetLibraryName(IN struct DCD_MANAGER* hDcdMgr, 263 IN struct DSP_UUID * pUuid, 264 IN OUT PSTR pstrLibName, 265 IN OUT DWORD * pdwSize, 266 IN NLDR_PHASE phase, 267 OUT bool * fPhaseSplit); 268 269 /* 270 * ======== DCD_GetObjectDef ======== 271 * Purpose: 272 * This function returns the properties/attributes of a DSP/BIOS Bridge 273 * object. 274 * Parameters: 275 * hDcdMgr: A DCD manager handle. 276 * pUuid: Pointer to a DSP_UUID that represents a unique 277 * DSP/BIOS Bridge object. 278 * objType: The type of DSP/BIOS Bridge object to be 279 * referenced (node, processor, etc). 280 * pObjDef: Pointer to an object definition structure. A 281 * union of various possible DCD object types. 282 * Returns: 283 * DSP_SOK: Success. 284 * DSP_EDCDPARSESECT: Unable to parse content of object code section. 285 * DSP_EDCDREADSECT: Unable to read object code section. 286 * DSP_EDCDGETSECT: Unable to access object code section. 287 * DSP_EDCDLOADBASE: Unable to load code base. 288 * DSP_EFAIL: General failure. 289 * DSP_EHANDLE: Invalid DCD_HMANAGER handle. 290 * Requires: 291 * DCD initialized. 292 * pObjUuid is non-NULL. 293 * pObjDef is non-NULL. 294 * Ensures: 295 */ 296 extern DSP_STATUS DCD_GetObjectDef(IN struct DCD_MANAGER* hDcdMgr, 297 IN struct DSP_UUID * pObjUuid, 298 IN DSP_DCDOBJTYPE objType, 299 OUT struct DCD_GENERICOBJ *pObjDef); 300 301 /* 302 * ======== DCD_GetObjects ======== 303 * Purpose: 304 * This function finds all DCD objects specified in a special 305 * COFF section called ".dcd_register", and for each object, 306 * call a "register" function. The "register" function may perform 307 * various actions, such as 1) register nodes in the node database, 2) 308 * unregister nodes from the node database, and 3) add overlay nodes. 309 * Parameters: 310 * hDcdMgr: A DCD manager handle. 311 * pszCoffPath: Pointer to name of COFF file containing DCD 312 * objects. 313 * registerFxn: Callback fxn to be applied on each located 314 * DCD object. 315 * handle: Handle to pass to callback. 316 * Returns: 317 * DSP_SOK: Success. 318 * DSP_EDCDNOAUTOREGISTER: Unable to find .dcd_register section. 319 * DSP_EDCDREADSECT: Unable to read object code section. 320 * DSP_EDCDLOADBASE: Unable to load code base. 321 * DSP_EHANDLE: Invalid DCD_HMANAGER handle.. 322 * Requires: 323 * DCD initialized. 324 * Ensures: 325 * Note: 326 * Due to the DCD database construction, it is essential for a DCD-enabled 327 * COFF file to contain the right COFF sections, especially 328 * ".dcd_register", which is used for auto registration. 329 */ 330 extern DSP_STATUS DCD_GetObjects(IN struct DCD_MANAGER* hDcdMgr, 331 IN CHAR * pszCoffPath, 332 DCD_REGISTERFXN registerFxn, 333 PVOID handle); 334 335 /* 336 * ======== DCD_Init ======== 337 * Purpose: 338 * This function initializes DCD. 339 * Parameters: 340 * Returns: 341 * FALSE: Initialization failed. 342 * TRUE: Initialization succeeded. 343 * Requires: 344 * Ensures: 345 * DCD initialized. 346 */ 347 extern bool DCD_Init(); 348 349 /* 350 * ======== DCD_RegisterObject ======== 351 * Purpose: 352 * This function registers a DSP/BIOS Bridge object in the DCD database. 353 * Parameters: 354 * pUuid: Pointer to a DSP_UUID that identifies a DSP/BIOS 355 * Bridge object. 356 * objType: Type of object. 357 * pszPathName: Path to the object's COFF file. 358 * Returns: 359 * DSP_SOK: Success. 360 * DSP_EFAIL: Failed to register object. 361 * Requires: 362 * DCD initialized. 363 * pUuid and szPathName are non-NULL values. 364 * objType is a valid type value. 365 * Ensures: 366 */ 367 extern DSP_STATUS DCD_RegisterObject(IN struct DSP_UUID * pUuid, 368 IN DSP_DCDOBJTYPE objType, 369 IN CHAR * pszPathName); 370 371 /* 372 * ======== DCD_UnregisterObject ======== 373 * Purpose: 374 * This function de-registers a valid DSP/BIOS Bridge object from the DCD 375 * database. 376 * Parameters: 377 * pUuid: Pointer to a DSP_UUID that identifies a DSP/BIOS Bridge 378 * object. 379 * objType: Type of object. 380 * Returns: 381 * DSP_SOK: Success. 382 * DSP_EFAIL: Unable to de-register the specified object. 383 * Requires: 384 * DCD initialized. 385 * pUuid is a non-NULL value. 386 * objType is a valid type value. 387 * Ensures: 388 */ 389 extern DSP_STATUS DCD_UnregisterObject(IN struct DSP_UUID * pUuid, 390 IN DSP_DCDOBJTYPE objType); 391 392 #ifdef __cplusplus 393 } 394 #endif 395 #endif /* _DBDCD_H */ 396