| /* |
| * dspbridge/mpu_api/inc/dbdcd.h |
| * |
| * DSP-BIOS Bridge driver support functions for TI OMAP processors. |
| * |
| * Copyright (C) 2007 Texas Instruments, Inc. |
| * |
| * This program is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU Lesser General Public License as published |
| * by the Free Software Foundation version 2.1 of the License. |
| * |
| * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind, |
| * whether express or implied; without even the implied warranty of |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| * Lesser General Public License for more details. |
| */ |
| |
| /* |
| * ======== dbdcd.h ======== |
| * Description: |
| * Defines the DSP/BIOS Bridge Configuration Database (DCD) API. |
| * |
| *! Revision History |
| *! ================ |
| *! 03-Dec-2003 map Changed DCD_OBJTYPE to DSP_DCDOBJTYPE |
| *! 24-Feb-2003 kc Updated DCD_AutoUnregister and DCD_GetObjects to simplify |
| *! DCD implementation. |
| *! 05-Aug-2002 jeh Added DCD_GetObjects(). |
| *! 11-Jul-2002 jeh Added DCD_GetDepLibs(), DCD_GetNumDepLibs(). |
| *! 22-Apr-2002 jeh Added DCD_GetLibraryName(). |
| *! 03-Apr-2001 sg Changed error names to have DCD_E* format. |
| *! 13-Feb-2001 kc Name changed from dcdbs.h to dbdcd.h. |
| *! 12-Dec-2000 kc Added DCD_AutoUnregister. |
| *! 09-Nov-2000 kc Updated usage of DCD_EnumerateObject. |
| *! 30-Oct-2000 kc Added DCD_AutoRegister. Updated error DCD error codes. |
| *! 29-Sep-2000 kc Incorporated code review comments. See |
| *! /src/reviews/dcd_review.txt. |
| *! 26-Jul-2000 kc Created. |
| *! |
| */ |
| |
| #ifndef DBDCD_ |
| #define DBDCD_ |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #include <dbdcddef.h> |
| #include <nldrdefs.h> |
| |
| /* |
| * ======== DCD_AutoRegister ======== |
| * Purpose: |
| * This function automatically registers DCD objects specified in a |
| * special COFF section called ".dcd_register" |
| * Parameters: |
| * hDcdMgr: A DCD manager handle. |
| * pszCoffPath: Pointer to name of COFF file containing DCD |
| * objects to be registered. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EDCDNOAUTOREGISTER: Unable to find auto-registration section. |
| * DSP_EDCDREADSECT: Unable to read object code section. |
| * DSP_EDCDLOADBASE: Unable to load code base. |
| * DSP_EHANDLE: Invalid DCD_HMANAGER handle.. |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| * Note: |
| * Due to the DCD database construction, it is essential for a DCD-enabled |
| * COFF file to contain the right COFF sections, especially |
| * ".dcd_register", which is used for auto registration. |
| */ |
| extern DSP_STATUS DCD_AutoRegister(IN struct DCD_MANAGER* hDcdMgr, |
| IN CHAR * pszCoffPath); |
| |
| /* |
| * ======== DCD_AutoUnregister ======== |
| * Purpose: |
| * This function automatically unregisters DCD objects specified in a |
| * special COFF section called ".dcd_register" |
| * Parameters: |
| * hDcdMgr: A DCD manager handle. |
| * pszCoffPath: Pointer to name of COFF file containing |
| * DCD objects to be unregistered. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EDCDNOAUTOREGISTER: Unable to find auto-registration section. |
| * DSP_EDCDREADSECT: Unable to read object code section. |
| * DSP_EDCDLOADBASE: Unable to load code base. |
| * DSP_EHANDLE: Invalid DCD_HMANAGER handle.. |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| * Note: |
| * Due to the DCD database construction, it is essential for a DCD-enabled |
| * COFF file to contain the right COFF sections, especially |
| * ".dcd_register", which is used for auto unregistration. |
| */ |
| extern DSP_STATUS DCD_AutoUnregister(IN struct DCD_MANAGER* hDcdMgr, |
| IN CHAR * pszCoffPath); |
| |
| /* |
| * ======== DCD_CreateManager ======== |
| * Purpose: |
| * This function creates a DCD module manager. |
| * Parameters: |
| * pszZlDllName: Pointer to a DLL name string. |
| * phDcdMgr: A pointer to a DCD manager handle. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EMEMORY: Unable to allocate memory for DCD manager handle. |
| * DSP_EFAIL: General failure. |
| * Requires: |
| * DCD initialized. |
| * pszZlDllName is non-NULL. |
| * phDcdMgr is non-NULL. |
| * Ensures: |
| * A DCD manager handle is created. |
| */ |
| extern DSP_STATUS DCD_CreateManager(IN CHAR * pszZlDllName, |
| OUT struct DCD_MANAGER* * phDcdMgr); |
| |
| /* |
| * ======== DCD_DestroyManager ======== |
| * Purpose: |
| * This function destroys a DCD module manager. |
| * Parameters: |
| * hDcdMgr: A DCD manager handle. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Invalid DCD manager handle. |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| */ |
| extern DSP_STATUS DCD_DestroyManager(IN struct DCD_MANAGER* hDcdMgr); |
| |
| /* |
| * ======== DCD_EnumerateObject ======== |
| * Purpose: |
| * This function enumerates currently visible DSP/BIOS Bridge objects |
| * and returns the UUID and type of each enumerated object. |
| * Parameters: |
| * cIndex: The object enumeration index. |
| * objType: Type of object to enumerate. |
| * pUuid: Pointer to a DSP_UUID object. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EFAIL: Unable to enumerate through the DCD database. |
| * DSP_SENUMCOMPLETE: Enumeration completed. This is not an error code. |
| * Requires: |
| * DCD initialized. |
| * pUuid is a valid pointer. |
| * Ensures: |
| * Details: |
| * This function can be used in conjunction with DCD_GetObjectDef to |
| * retrieve object properties. |
| */ |
| extern DSP_STATUS DCD_EnumerateObject(IN INT cIndex, |
| IN DSP_DCDOBJTYPE objType, |
| OUT struct DSP_UUID * pUuid); |
| |
| /* |
| * ======== DCD_Exit ======== |
| * Purpose: |
| * This function cleans up the DCD module. |
| * Parameters: |
| * Returns: |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| */ |
| extern VOID DCD_Exit(); |
| |
| /* |
| * ======== DCD_GetDepLibs ======== |
| * Purpose: |
| * Given the uuid of a library and size of array of uuids, this function |
| * fills the array with the uuids of all dependent libraries of the input |
| * library. |
| * Parameters: |
| * hDcdMgr: A DCD manager handle. |
| * pUuid: Pointer to a DSP_UUID for a library. |
| * numLibs: Size of uuid array (number of library uuids). |
| * pDepLibUuids: Array of dependent library uuids to be filled in. |
| * pPersistentDepLibs: Array indicating if corresponding lib is persistent. |
| * phase: phase to obtain correct input library |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EMEMORY: Memory allocation failure. |
| * DSP_EDCDREADSECT: Failure to read section containing library info. |
| * DSP_EFAIL: General failure. |
| * Requires: |
| * DCD initialized. |
| * Valid hDcdMgr. |
| * pUuid != NULL |
| * pDepLibUuids != NULL. |
| * Ensures: |
| */ |
| extern DSP_STATUS DCD_GetDepLibs(IN struct DCD_MANAGER* hDcdMgr, |
| IN struct DSP_UUID * pUuid, |
| USHORT numLibs, |
| OUT struct DSP_UUID * pDepLibUuids, |
| OUT bool * pPersistentDepLibs, |
| IN NLDR_PHASE phase); |
| |
| /* |
| * ======== DCD_GetNumDepLibs ======== |
| * Purpose: |
| * Given the uuid of a library, determine its number of dependent |
| * libraries. |
| * Parameters: |
| * hDcdMgr: A DCD manager handle. |
| * pUuid: Pointer to a DSP_UUID for a library. |
| * pNumLibs: Size of uuid array (number of library uuids). |
| * pNumPersLibs: number of persistent dependent library. |
| * phase: Phase to obtain correct input library |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EMEMORY: Memory allocation failure. |
| * DSP_EDCDREADSECT: Failure to read section containing library info. |
| * DSP_EFAIL: General failure. |
| * Requires: |
| * DCD initialized. |
| * Valid hDcdMgr. |
| * pUuid != NULL |
| * pNumLibs != NULL. |
| * Ensures: |
| */ |
| extern DSP_STATUS DCD_GetNumDepLibs(IN struct DCD_MANAGER* hDcdMgr, |
| IN struct DSP_UUID * pUuid, |
| OUT USHORT * pNumLibs, |
| OUT USHORT * pNumPersLibs, |
| IN NLDR_PHASE phase); |
| |
| /* |
| * ======== DCD_GetLibraryName ======== |
| * Purpose: |
| * This function returns the name of a (dynamic) library for a given |
| * UUID. |
| * Parameters: |
| * hDcdMgr: A DCD manager handle. |
| * pUuid: Pointer to a DSP_UUID that represents a unique DSP/BIOS |
| * Bridge object. |
| * pstrLibName: Buffer to hold library name. |
| * pdwSize: Contains buffer size. Set to string size on output. |
| * phase: Which phase to load |
| * fPhaseSplit: Are phases in multiple libraries |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EFAIL: General failure. |
| * Requires: |
| * DCD initialized. |
| * Valid hDcdMgr. |
| * pstrLibName != NULL. |
| * pUuid != NULL |
| * pdwSize != NULL. |
| * Ensures: |
| */ |
| extern DSP_STATUS DCD_GetLibraryName(IN struct DCD_MANAGER* hDcdMgr, |
| IN struct DSP_UUID * pUuid, |
| IN OUT PSTR pstrLibName, |
| IN OUT DWORD * pdwSize, |
| IN NLDR_PHASE phase, |
| OUT bool * fPhaseSplit); |
| |
| /* |
| * ======== DCD_GetObjectDef ======== |
| * Purpose: |
| * This function returns the properties/attributes of a DSP/BIOS Bridge |
| * object. |
| * Parameters: |
| * hDcdMgr: A DCD manager handle. |
| * pUuid: Pointer to a DSP_UUID that represents a unique |
| * DSP/BIOS Bridge object. |
| * objType: The type of DSP/BIOS Bridge object to be |
| * referenced (node, processor, etc). |
| * pObjDef: Pointer to an object definition structure. A |
| * union of various possible DCD object types. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EDCDPARSESECT: Unable to parse content of object code section. |
| * DSP_EDCDREADSECT: Unable to read object code section. |
| * DSP_EDCDGETSECT: Unable to access object code section. |
| * DSP_EDCDLOADBASE: Unable to load code base. |
| * DSP_EFAIL: General failure. |
| * DSP_EHANDLE: Invalid DCD_HMANAGER handle. |
| * Requires: |
| * DCD initialized. |
| * pObjUuid is non-NULL. |
| * pObjDef is non-NULL. |
| * Ensures: |
| */ |
| extern DSP_STATUS DCD_GetObjectDef(IN struct DCD_MANAGER* hDcdMgr, |
| IN struct DSP_UUID * pObjUuid, |
| IN DSP_DCDOBJTYPE objType, |
| OUT struct DCD_GENERICOBJ *pObjDef); |
| |
| /* |
| * ======== DCD_GetObjects ======== |
| * Purpose: |
| * This function finds all DCD objects specified in a special |
| * COFF section called ".dcd_register", and for each object, |
| * call a "register" function. The "register" function may perform |
| * various actions, such as 1) register nodes in the node database, 2) |
| * unregister nodes from the node database, and 3) add overlay nodes. |
| * Parameters: |
| * hDcdMgr: A DCD manager handle. |
| * pszCoffPath: Pointer to name of COFF file containing DCD |
| * objects. |
| * registerFxn: Callback fxn to be applied on each located |
| * DCD object. |
| * handle: Handle to pass to callback. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EDCDNOAUTOREGISTER: Unable to find .dcd_register section. |
| * DSP_EDCDREADSECT: Unable to read object code section. |
| * DSP_EDCDLOADBASE: Unable to load code base. |
| * DSP_EHANDLE: Invalid DCD_HMANAGER handle.. |
| * Requires: |
| * DCD initialized. |
| * Ensures: |
| * Note: |
| * Due to the DCD database construction, it is essential for a DCD-enabled |
| * COFF file to contain the right COFF sections, especially |
| * ".dcd_register", which is used for auto registration. |
| */ |
| extern DSP_STATUS DCD_GetObjects(IN struct DCD_MANAGER* hDcdMgr, |
| IN CHAR * pszCoffPath, |
| DCD_REGISTERFXN registerFxn, |
| PVOID handle); |
| |
| /* |
| * ======== DCD_Init ======== |
| * Purpose: |
| * This function initializes DCD. |
| * Parameters: |
| * Returns: |
| * FALSE: Initialization failed. |
| * TRUE: Initialization succeeded. |
| * Requires: |
| * Ensures: |
| * DCD initialized. |
| */ |
| extern bool DCD_Init(); |
| |
| /* |
| * ======== DCD_RegisterObject ======== |
| * Purpose: |
| * This function registers a DSP/BIOS Bridge object in the DCD database. |
| * Parameters: |
| * pUuid: Pointer to a DSP_UUID that identifies a DSP/BIOS |
| * Bridge object. |
| * objType: Type of object. |
| * pszPathName: Path to the object's COFF file. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EFAIL: Failed to register object. |
| * Requires: |
| * DCD initialized. |
| * pUuid and szPathName are non-NULL values. |
| * objType is a valid type value. |
| * Ensures: |
| */ |
| extern DSP_STATUS DCD_RegisterObject(IN struct DSP_UUID * pUuid, |
| IN DSP_DCDOBJTYPE objType, |
| IN CHAR * pszPathName); |
| |
| /* |
| * ======== DCD_UnregisterObject ======== |
| * Purpose: |
| * This function de-registers a valid DSP/BIOS Bridge object from the DCD |
| * database. |
| * Parameters: |
| * pUuid: Pointer to a DSP_UUID that identifies a DSP/BIOS Bridge |
| * object. |
| * objType: Type of object. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EFAIL: Unable to de-register the specified object. |
| * Requires: |
| * DCD initialized. |
| * pUuid is a non-NULL value. |
| * objType is a valid type value. |
| * Ensures: |
| */ |
| extern DSP_STATUS DCD_UnregisterObject(IN struct DSP_UUID * pUuid, |
| IN DSP_DCDOBJTYPE objType); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| #endif /* _DBDCD_H */ |
