395 lines
14 KiB
C
395 lines
14 KiB
C
/*
|
|
* 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 */
|