dspbridge/inc/nldrdefs.h - platform/hardware/ti/omap3 - Git at Google

 /*
  *  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.
  */


 /*
  *  ======== nldrdefs.h ========
  *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
  *  Description:
  *      Global Dynamic + static/overlay Node loader (NLDR) constants and types.
  *
  *! Revision History
  *! ================
  *! 07-Apr-2003 map     Consolidated dldrdefs.h into nldrdefs.h
  *! 05-Aug-2002 jeh     Created.
  */

 #ifndef NLDRDEFS_
 #define NLDRDEFS_

 #ifdef __cplusplus
 extern "C" {
 #endif

 #include <dbdcddef.h>
 #include <devdefs.h>

 #define NLDR_MAXPATHLENGTH       255
 /* NLDR Objects: */
 	struct  NLDR_OBJECT;
 	/*typedef struct NLDR_OBJECT *NLDR_HOBJECT;*/
 	struct NLDR_NODEOBJECT;
 	/*typedef struct NLDR_NODEOBJECT *NLDR_HNODE;*/

 /*
  *  ======== NLDR_LOADTYPE ========
  *  Load types for a node. Must match values in node.h55.
  */
 	typedef enum NLDR_LOADTYPE {
 		NLDR_STATICLOAD,	/* Linked in base image, not overlay */
 		NLDR_DYNAMICLOAD,	/* Dynamically loaded node */
 		NLDR_OVLYLOAD	/* Linked in base image, overlay node */
 	} NLDR_LOADTYPE;

 /*
  *  ======== NLDR_OVLYFXN ========
  *  Causes code or data to be copied from load address to run address. This
  *  is the "COD_WRITEFXN" that gets passed to the DBLL_Library and is used as
  *  the ZL write function.
  *
  *  Parameters:
  *      pPrivRef:       Handle to identify the node.
  *      ulDspRunAddr:   Run address of code or data.
  *      ulDspLoadAddr:  Load address of code or data.
  *      ulNumBytes:     Number of (GPP) bytes to copy.
  *      nMemSpace:      RMS_CODE or RMS_DATA.
  *  Returns:
  *      ulNumBytes:     Success.
  *      0:              Failure.
  *  Requires:
  *  Ensures:
  */
 	typedef ULONG(CDECL * NLDR_OVLYFXN) (PVOID pPrivRef, ULONG ulDspRunAddr,
 					     ULONG ulDspLoadAddr,
 					     ULONG ulNumBytes, UINT nMemSpace);

 /*
  *  ======== NLDR_WRITEFXN ========
  *  Write memory function. Used for dynamic load writes.
  *  Parameters:
  *      pPrivRef:       Handle to identify the node.
  *      ulDspAddr:      Address of code or data.
  *      pBuf:           Code or data to be written
  *      ulNumBytes:     Number of (GPP) bytes to write.
  *      nMemSpace:      DBLL_DATA or DBLL_CODE.
  *  Returns:
  *      ulNumBytes:     Success.
  *      0:              Failure.
  *  Requires:
  *  Ensures:
  */
 	typedef ULONG(CDECL * NLDR_WRITEFXN) (PVOID pPrivRef,
 					      ULONG ulDspAddr, PVOID pBuf,
 					      ULONG ulNumBytes, UINT nMemSpace);

 /*
  *  ======== NLDR_ATTRS ========
  *  Attributes passed to NLDR_Create function.
  */
 	struct NLDR_ATTRS {
 		NLDR_OVLYFXN pfnOvly;
 		NLDR_WRITEFXN pfnWrite;
 		USHORT usDSPWordSize;
 		USHORT usDSPMauSize;
 	} ;

 /*
  *  ======== NLDR_PHASE ========
  *  Indicates node create, delete, or execute phase function.
  */
 	typedef enum {
 		NLDR_CREATE,
 		NLDR_DELETE,
 		NLDR_EXECUTE,
 		NLDR_NOPHASE
 	} NLDR_PHASE;

 /*
  *  Typedefs of loader functions imported from a DLL, or defined in a
  *  function table.
  */

 /*
  *  ======== NLDR_Allocate ========
  *  Allocate resources to manage the loading of a node on the DSP.
  *
  *  Parameters:
  *      hNldr:          Handle of loader that will load the node.
  *      pPrivRef:       Handle to identify the node.
  *      pNodeProps:     Pointer to a DCD_NODEPROPS for the node.
  *      phNldrNode:     Location to store node handle on output. This handle
  *                      will be passed to NLDR_Load/NLDR_Unload.
  *      pfPhaseSplit:   pointer to boolean variable referenced in node.c
  *  Returns:
  *      DSP_SOK:        Success.
  *      DSP_EMEMORY:    Insufficient memory on GPP.
  *  Requires:
  *      NLDR_Init() called.
  *      Valid hNldr.
  *      pNodeProps != NULL.
  *      phNldrNode != NULL.
  *  Ensures:
  *      DSP_SOK:        IsValidNode(*phNldrNode).
  *      error:          *phNldrNode == NULL.
  */
 	typedef DSP_STATUS(*NLDR_ALLOCATEFXN) (struct NLDR_OBJECT* hNldr,
 					       PVOID pPrivRef,
 					       IN CONST struct DCD_NODEPROPS *pNodeProps,
 					       OUT struct NLDR_NODEOBJECT* * phNldrNode,
 					       OUT bool * pfPhaseSplit);

 /*
  *  ======== NLDR_Create ========
  *  Create a loader object. This object handles the loading and unloading of
  *  create, delete, and execute phase functions of nodes on the DSP target.
  *
  *  Parameters:
  *      phNldr:         Location to store loader handle on output.
  *      hDevObject:     Device for this processor.
  *      pAttrs:         Loader attributes.
  *  Returns:
  *      DSP_SOK:        Success;
  *      DSP_EMEMORY:    Insufficient memory for requested resources.
  *  Requires:
  *      NLDR_Init() called.
  *      phNldr != NULL.
  *      hDevObject != NULL.
  *	pAttrs != NULL.
  *  Ensures:
  *      DSP_SOK:        Valid *phNldr.
  *      error:          *phNldr == NULL.
  */
 	typedef DSP_STATUS(*NLDR_CREATEFXN) (OUT struct NLDR_OBJECT* * phNldr,
 					     struct DEV_OBJECT* hDevObject,
 					     IN CONST struct NLDR_ATTRS * pAttrs);

 /*
  *  ======== NLDR_Delete ========
  *  Delete the NLDR loader.
  *
  *  Parameters:
  *      hNldr:          Node manager object.
  *  Returns:
  *  Requires:
  *      NLDR_Init() called.
  *      Valid hNldr.
  *  Ensures:
  *	hNldr invalid
  */
 	typedef VOID(*NLDR_DELETEFXN) (struct NLDR_OBJECT* hNldr);

 /*
  *  ======== NLDR_Exit ========
  *  Discontinue usage of NLDR module.
  *
  *  Parameters:
  *  Returns:
  *  Requires:
  *      NLDR_Init() successfully called before.
  *  Ensures:
  *      Any resources acquired in NLDR_Init() will be freed when last NLDR
  *      client calls NLDR_Exit().
  */
 	typedef VOID(*NLDR_EXITFXN) ();

 /*
  *  ======== NLDR_Free ========
  *  Free resources allocated in NLDR_Allocate.
  *
  *  Parameters:
  *      hNldrNode:      Handle returned from NLDR_Allocate().
  *  Returns:
  *  Requires:
  *      NLDR_Init() called.
  *      Valid hNldrNode.
  *  Ensures:
  */
 	typedef VOID(*NLDR_FREEFXN) (struct NLDR_NODEOBJECT* hNldrNode);

 /*
  *  ======== NLDR_GetFxnAddr ========
  *  Get address of create, delete, or execute phase function of a node on
  *  the DSP.
  *
  *  Parameters:
  *      hNldrNode:      Handle returned from NLDR_Allocate().
  *      pstrFxn:        Name of function.
  *      pulAddr:        Location to store function address.
  *  Returns:
  *      DSP_SOK:        Success.
  *      DSP_ESYMBOL:    Address of function not found.
  *  Requires:
  *      NLDR_Init() called.
  *      Valid hNldrNode.
  *      pulAddr != NULL;
  *      pstrFxn != NULL;
  *  Ensures:
  */
 	typedef DSP_STATUS(*NLDR_GETFXNADDRFXN) (struct NLDR_NODEOBJECT* hNldrNode,
 						 PSTR pstrFxn, ULONG * pulAddr);

 /*
  *  ======== NLDR_Init ========
  *  Initialize the NLDR module.
  *
  *  Parameters:
  *  Returns:
  *      TRUE if initialization succeeded, FALSE otherwise.
  *  Ensures:
  */
 	typedef bool(*NLDR_INITFXN) ();

 /*
  *  ======== NLDR_Load ========
  *  Load create, delete, or execute phase function of a node on the DSP.
  *
  *  Parameters:
  *      hNldrNode:      Handle returned from NLDR_Allocate().
  *      phase:          Type of function to load (create, delete, or execute).
  *  Returns:
  *      DSP_SOK:                Success.
  *      DSP_EMEMORY:            Insufficient memory on GPP.
  *      DSP_EOVERLAYMEMORY:     Can't overlay phase because overlay memory
  *                              is already in use.
  *      DSP_EDYNLOAD:           Failure in dynamic loader library.
  *      DSP_EFWRITE:            Failed to write phase's code or date to target.
  *  Requires:
  *      NLDR_Init() called.
  *      Valid hNldrNode.
  *  Ensures:
  */
 	typedef DSP_STATUS(*NLDR_LOADFXN) (struct NLDR_NODEOBJECT* hNldrNode,
 					   NLDR_PHASE phase);

 /*
  *  ======== NLDR_Unload ========
  *  Unload create, delete, or execute phase function of a node on the DSP.
  *
  *  Parameters:
  *      hNldrNode:      Handle returned from NLDR_Allocate().
  *      phase:          Node function to unload (create, delete, or execute).
  *  Returns:
  *      DSP_SOK:        Success.
  *      DSP_EMEMORY:    Insufficient memory on GPP.
  *  Requires:
  *      NLDR_Init() called.
  *      Valid hNldrNode.
  *  Ensures:
  */
 	typedef DSP_STATUS(*NLDR_UNLOADFXN) (struct NLDR_NODEOBJECT* hNldrNode,
 					     NLDR_PHASE phase);

 /*
  *  ======== NLDR_FXNS ========
  */
 	struct NLDR_FXNS {
 		NLDR_ALLOCATEFXN pfnAllocate;
 		NLDR_CREATEFXN pfnCreate;
 		NLDR_DELETEFXN pfnDelete;
 		NLDR_EXITFXN pfnExit;
 		NLDR_FREEFXN pfnFree;
 		NLDR_GETFXNADDRFXN pfnGetFxnAddr;
 		NLDR_INITFXN pfnInit;
 		NLDR_LOADFXN pfnLoad;
 		NLDR_UNLOADFXN pfnUnload;
 	} ;

 #ifdef __cplusplus
 }
 #endif
 #endif				/* NLDRDEFS_ */
	/*
	* 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.
	*/



	/*
	* ======== nldrdefs.h ========
	* DSP-BIOS Bridge driver support functions for TI OMAP processors.
	* Description:
	* Global Dynamic + static/overlay Node loader (NLDR) constants and types.
	*
	*! Revision History
	*! ================
	*! 07-Apr-2003 map Consolidated dldrdefs.h into nldrdefs.h
	*! 05-Aug-2002 jeh Created.
	*/

	#ifndef NLDRDEFS_
	#define NLDRDEFS_

	#ifdef __cplusplus
	extern "C" {
	#endif

	#include <dbdcddef.h>
	#include <devdefs.h>

	#define NLDR_MAXPATHLENGTH 255
	/* NLDR Objects: */
	struct NLDR_OBJECT;
	/typedef struct NLDR_OBJECT NLDR_HOBJECT;*/
	struct NLDR_NODEOBJECT;
	/typedef struct NLDR_NODEOBJECT NLDR_HNODE;*/

	/*
	* ======== NLDR_LOADTYPE ========
	* Load types for a node. Must match values in node.h55.
	*/
	typedef enum NLDR_LOADTYPE {
	NLDR_STATICLOAD, /* Linked in base image, not overlay */
	NLDR_DYNAMICLOAD, /* Dynamically loaded node */
	NLDR_OVLYLOAD /* Linked in base image, overlay node */
	} NLDR_LOADTYPE;

	/*
	* ======== NLDR_OVLYFXN ========
	* Causes code or data to be copied from load address to run address. This
	* is the "COD_WRITEFXN" that gets passed to the DBLL_Library and is used as
	* the ZL write function.
	*
	* Parameters:
	* pPrivRef: Handle to identify the node.
	* ulDspRunAddr: Run address of code or data.
	* ulDspLoadAddr: Load address of code or data.
	* ulNumBytes: Number of (GPP) bytes to copy.
	* nMemSpace: RMS_CODE or RMS_DATA.
	* Returns:
	* ulNumBytes: Success.
	* 0: Failure.
	* Requires:
	* Ensures:
	*/
	typedef ULONG(CDECL * NLDR_OVLYFXN) (PVOID pPrivRef, ULONG ulDspRunAddr,
	ULONG ulDspLoadAddr,
	ULONG ulNumBytes, UINT nMemSpace);

	/*
	* ======== NLDR_WRITEFXN ========
	* Write memory function. Used for dynamic load writes.
	* Parameters:
	* pPrivRef: Handle to identify the node.
	* ulDspAddr: Address of code or data.
	* pBuf: Code or data to be written
	* ulNumBytes: Number of (GPP) bytes to write.
	* nMemSpace: DBLL_DATA or DBLL_CODE.
	* Returns:
	* ulNumBytes: Success.
	* 0: Failure.
	* Requires:
	* Ensures:
	*/
	typedef ULONG(CDECL * NLDR_WRITEFXN) (PVOID pPrivRef,
	ULONG ulDspAddr, PVOID pBuf,
	ULONG ulNumBytes, UINT nMemSpace);

	/*
	* ======== NLDR_ATTRS ========
	* Attributes passed to NLDR_Create function.
	*/
	struct NLDR_ATTRS {
	NLDR_OVLYFXN pfnOvly;
	NLDR_WRITEFXN pfnWrite;
	USHORT usDSPWordSize;
	USHORT usDSPMauSize;
	} ;

	/*
	* ======== NLDR_PHASE ========
	* Indicates node create, delete, or execute phase function.
	*/
	typedef enum {
	NLDR_CREATE,
	NLDR_DELETE,
	NLDR_EXECUTE,
	NLDR_NOPHASE
	} NLDR_PHASE;

	/*
	* Typedefs of loader functions imported from a DLL, or defined in a
	* function table.
	*/

	/*
	* ======== NLDR_Allocate ========
	* Allocate resources to manage the loading of a node on the DSP.
	*
	* Parameters:
	* hNldr: Handle of loader that will load the node.
	* pPrivRef: Handle to identify the node.
	* pNodeProps: Pointer to a DCD_NODEPROPS for the node.
	* phNldrNode: Location to store node handle on output. This handle
	* will be passed to NLDR_Load/NLDR_Unload.
	* pfPhaseSplit: pointer to boolean variable referenced in node.c
	* Returns:
	* DSP_SOK: Success.
	* DSP_EMEMORY: Insufficient memory on GPP.
	* Requires:
	* NLDR_Init() called.
	* Valid hNldr.
	* pNodeProps != NULL.
	* phNldrNode != NULL.
	* Ensures:
	* DSP_SOK: IsValidNode(*phNldrNode).
	* error: *phNldrNode == NULL.
	*/
	typedef DSP_STATUS(NLDR_ALLOCATEFXN) (struct NLDR_OBJECT hNldr,
	PVOID pPrivRef,
	IN CONST struct DCD_NODEPROPS *pNodeProps,
	OUT struct NLDR_NODEOBJECT* * phNldrNode,
	OUT bool * pfPhaseSplit);

	/*
	* ======== NLDR_Create ========
	* Create a loader object. This object handles the loading and unloading of
	* create, delete, and execute phase functions of nodes on the DSP target.
	*
	* Parameters:
	* phNldr: Location to store loader handle on output.
	* hDevObject: Device for this processor.
	* pAttrs: Loader attributes.
	* Returns:
	* DSP_SOK: Success;
	* DSP_EMEMORY: Insufficient memory for requested resources.
	* Requires:
	* NLDR_Init() called.
	* phNldr != NULL.
	* hDevObject != NULL.
	* pAttrs != NULL.
	* Ensures:
	* DSP_SOK: Valid *phNldr.
	* error: *phNldr == NULL.
	*/
	typedef DSP_STATUS(NLDR_CREATEFXN) (OUT struct NLDR_OBJECT * phNldr,
	struct DEV_OBJECT* hDevObject,
	IN CONST struct NLDR_ATTRS * pAttrs);

	/*
	* ======== NLDR_Delete ========
	* Delete the NLDR loader.
	*
	* Parameters:
	* hNldr: Node manager object.
	* Returns:
	* Requires:
	* NLDR_Init() called.
	* Valid hNldr.
	* Ensures:
	* hNldr invalid
	*/
	typedef VOID(NLDR_DELETEFXN) (struct NLDR_OBJECT hNldr);

	/*
	* ======== NLDR_Exit ========
	* Discontinue usage of NLDR module.
	*
	* Parameters:
	* Returns:
	* Requires:
	* NLDR_Init() successfully called before.
	* Ensures:
	* Any resources acquired in NLDR_Init() will be freed when last NLDR
	* client calls NLDR_Exit().
	*/
	typedef VOID(*NLDR_EXITFXN) ();

	/*
	* ======== NLDR_Free ========
	* Free resources allocated in NLDR_Allocate.
	*
	* Parameters:
	* hNldrNode: Handle returned from NLDR_Allocate().
	* Returns:
	* Requires:
	* NLDR_Init() called.
	* Valid hNldrNode.
	* Ensures:
	*/
	typedef VOID(NLDR_FREEFXN) (struct NLDR_NODEOBJECT hNldrNode);

	/*
	* ======== NLDR_GetFxnAddr ========
	* Get address of create, delete, or execute phase function of a node on
	* the DSP.
	*
	* Parameters:
	* hNldrNode: Handle returned from NLDR_Allocate().
	* pstrFxn: Name of function.
	* pulAddr: Location to store function address.
	* Returns:
	* DSP_SOK: Success.
	* DSP_ESYMBOL: Address of function not found.
	* Requires:
	* NLDR_Init() called.
	* Valid hNldrNode.
	* pulAddr != NULL;
	* pstrFxn != NULL;
	* Ensures:
	*/
	typedef DSP_STATUS(NLDR_GETFXNADDRFXN) (struct NLDR_NODEOBJECT hNldrNode,
	PSTR pstrFxn, ULONG * pulAddr);

	/*
	* ======== NLDR_Init ========
	* Initialize the NLDR module.
	*
	* Parameters:
	* Returns:
	* TRUE if initialization succeeded, FALSE otherwise.
	* Ensures:
	*/
	typedef bool(*NLDR_INITFXN) ();

	/*
	* ======== NLDR_Load ========
	* Load create, delete, or execute phase function of a node on the DSP.
	*
	* Parameters:
	* hNldrNode: Handle returned from NLDR_Allocate().
	* phase: Type of function to load (create, delete, or execute).
	* Returns:
	* DSP_SOK: Success.
	* DSP_EMEMORY: Insufficient memory on GPP.
	* DSP_EOVERLAYMEMORY: Can't overlay phase because overlay memory
	* is already in use.
	* DSP_EDYNLOAD: Failure in dynamic loader library.
	* DSP_EFWRITE: Failed to write phase's code or date to target.
	* Requires:
	* NLDR_Init() called.
	* Valid hNldrNode.
	* Ensures:
	*/
	typedef DSP_STATUS(NLDR_LOADFXN) (struct NLDR_NODEOBJECT hNldrNode,
	NLDR_PHASE phase);

	/*
	* ======== NLDR_Unload ========
	* Unload create, delete, or execute phase function of a node on the DSP.
	*
	* Parameters:
	* hNldrNode: Handle returned from NLDR_Allocate().
	* phase: Node function to unload (create, delete, or execute).
	* Returns:
	* DSP_SOK: Success.
	* DSP_EMEMORY: Insufficient memory on GPP.
	* Requires:
	* NLDR_Init() called.
	* Valid hNldrNode.
	* Ensures:
	*/
	typedef DSP_STATUS(NLDR_UNLOADFXN) (struct NLDR_NODEOBJECT hNldrNode,
	NLDR_PHASE phase);

	/*
	* ======== NLDR_FXNS ========
	*/
	struct NLDR_FXNS {
	NLDR_ALLOCATEFXN pfnAllocate;
	NLDR_CREATEFXN pfnCreate;
	NLDR_DELETEFXN pfnDelete;
	NLDR_EXITFXN pfnExit;
	NLDR_FREEFXN pfnFree;
	NLDR_GETFXNADDRFXN pfnGetFxnAddr;
	NLDR_INITFXN pfnInit;
	NLDR_LOADFXN pfnLoad;
	NLDR_UNLOADFXN pfnUnload;
	} ;

	#ifdef __cplusplus
	}
	#endif
	#endif /* NLDRDEFS_ */