/*
 *  Copyright 2001-2008 Texas Instruments - http://www.ti.com/
 * 
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

/*
 *  ======== dbdcd.h ========
 *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
 *  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 */