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

/*
 *  ======== DSPNode.h ========
 *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
 *  Description:
 *      This is the header for the DSP/BIOS Bridge node module.
 *
 *  Public Functions:
 *      DSPNode_Allocate
 *      DSPNode_AllocMsgBuf
 *      DSPNode_ChangePriority
 *      DSPNode_Connect
 *      DSPNode_ConnectEx
 *      DSPNode_Create
 *      DSPNode_Delete
 *      DSPNode_FreeMsgBuf
 *      DSPNode_GetAttr
 *      DSPNode_GetMessage
 *      DSPNode_Pause
 *      DSPNode_PutMessage
 *      DSPNode_RegisterNotify
 *      DSPNode_Run
 *      DSPNode_Terminate
 *
 *  Notes:
 *
 *! Revision History:
 *! ================
 *! 23-Nov-2002 gp: Comment change: uEventMask now referred to as a "type".
 *!                 Comment cleanup, correspondence to db_api.doc.
 *! 12-Dec-2001 ag  DSP_ENOTIMPL added to DSPNode_Connect().
 *! 11-Sep-2001 ag  Added new error codes.
 *! 23-Apr-2001 jeh Added pStatus parameter to DSPNode_Terminate.
 *! 16-Feb-2001 jeh Added new error codes.
 *! 13-Feb-2001 kc: DSP/BIOS Bridge name updates.
 *! 27-Oct-2000 jeh Updated to version 0.9 API spec.
 *! 07-Sep-2000 jeh Changed type HANDLE in DSPNode_RegisterNotify to
 *!                 DSP_HNOTIFICATION. Added DSP_STRMATTR parameter to
 *!                 DSPNode_Connect().
 *! 27-Jul-2000 rr: Updated to ver 0.8 of DSPAPI.
 *! 27-Jun-2000 rr: Created from DBAPI.h
 */

#ifndef DSPNode_
#define DSPNode_

#ifdef __cplusplus
extern "C" {
#endif

/*
 *  ======== DSPNode_Allocate ========
 *  Purpose:
 *      Allocate data structures for controlling and communicating with a node
 *      on a specific DSP processor.
 *  Parameters:
 *      hProcessor:         The processor handle.
 *      pNodeID:            Ptr to DSP_UUID for the node.
 *      pArgs:              Ptr to optional node arguments.
 *      pAttrIn:            Ptr to optional node attributes.
 *      phNode:             Ptr to location to store node handle on return.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EPOINTER:       One of the input parameters pointers is invalid.
 *      DSP_EHANDLE:        Invalid processor handle.
 *      DSP_EMEMORY:        Memory is not available to allocate a node
 *      DSP_EUUID:          The node with the specified UUID is not registered.
 *      DSP_EWRONGSTATE:    The specified processor is in the wrong state
 *                          (not running)
 *      DSP_ERANGE:         The iPriority field specified in pAttrIn is out
 *                          of range.
 *      DSP_EFAIL:          General failure.
 */
extern DBAPI
DSPNode_Allocate(DSP_HPROCESSOR hProcessor,
		 IN CONST struct DSP_UUID * pNodeID,
		 IN CONST OPTIONAL struct DSP_CBDATA * pArgs,
		 IN OPTIONAL struct DSP_NODEATTRIN * pAttrIn,
		 OUT DSP_HNODE * phNode);

/*
 *  ======== DSPNode_AllocMsgBuf ========
 *  Purpose:
 *      Allocate and prepare a buffer whose descriptor will be passed to a DSP
 *      Node within a (DSP_MSG) message
 *  Parameters:
 *      hNode:              The node handle.
 *      uSize:              The size of the buffer (GPP bytes) to be allocated.
 *      pAttr:              Pointer to a DSP_BUFFERATTR structure.
 *      pBuffer:            Location to store the address of the allocated
 *                          buffer on output.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_EMEMORY:        Insufficent memory.
 *      DSP_EPOINTER:       pBuffer is not a valid address.
 *      DSP_EFAIL:          General Failure.
 *      DSP_EALIGNMENT:     Alignment value not supported.(Must be 0, 1, 2, 4)
 *      DSP_EBADSEGID:      Invalid Segment Id.
 *      DSP_ESIZE:          Invalid Size. Must be greater than zero.
 */
	extern DBAPI DSPNode_AllocMsgBuf(DSP_HNODE hNode, UINT uSize,
					 IN OPTIONAL struct DSP_BUFFERATTR * pAttr,
					 OUT BYTE ** pBuffer);

/*
 *  ======== DSPNode_ChangePriority ========
 *  Purpose:
 *      Change a task node's runtime priority within the DSP RTOS.
 *  Parameters:
 *      hNode:              The node handle.
 *      iPriority:          New runtime priority level.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_ERANGE:         iPriority is out of range.
 *      DSP_ENODETYPE:      Operation is invalid for this node type.
 *      DSP_ETIMEOUT:       A timeout occured before DSP responded.
 *      DSP_ERESTART:       A critical error occurred and the DSP is being
 *                          restarted.
 *      DSP_EWRONGSTATE:    The node is not allocated, paused, or running.
 *      DSP_EFAIL:          Unable to change the priority level.
 */
	extern DBAPI DSPNode_ChangePriority(DSP_HNODE hNode, INT iPriority);

/*
 *  ======== DSPNode_Connect ========
 *  Purpose:
 *      Make a stream connection, either between two nodes on a DSP,
 *      or between a node on a DSP and the GPP.
 *  Parameters:
 *      hNode:                  The first node handle.
 *      uStream:                Output stream index on first node (0 based).
 *      hOtherNode:             The second node handle.
 *      uOtherStream:           Input stream index on second node (0 based).
 *      pAttrs:                 Stream attributes. If NULL, defaults used.
 *  Returns:
 *      DSP_SOK:                Success.
 *      DSP_EHANDLE:            Invalid node handle.
 *      DSP_EMEMORY:            GPP memory allocation failure.
 *      DSP_EALREADYCONNCECTED: One of the specified connections has already
 *                              been made.
 *      DSP_EWRONGSTATE:        The node is not in the NODE_ALLOCATED state.
 *      DSP_EVALUE:             A Stream index is not valid.
 *      DSP_ENOMORECONNECTIONS: No more connections are allowed
 *      DSP_EFAIL:              Unable to make connection.
 *      DSP_ENOTIMPL:           Stream mode valid but not supported.
 *      DSP_ESTRMMODE           Illegal Stream mode specified.
 *
 */
	extern DBAPI DSPNode_Connect(DSP_HNODE hNode, UINT uStream,
				     DSP_HNODE hOtherNode, UINT uOtherStream,
				     IN OPTIONAL struct DSP_STRMATTR * pAttr);

/*
 *  ======== DSPNode_ConnectEx ========
 *  Purpose:
 *      Make a stream connection, either between two nodes on a DSP,
 *      or between a node on a DSP and the GPP.
 *  Parameters:
 *      hNode:                  The first node handle.
 *      uStream:                Output stream index on first node (0 based).
 *      hOtherNode:             The second node handle.
 *      uOtherStream:           Input stream index on second node (0 based).
 *      pAttrs:                 Stream attributes. If NULL, defaults used.
 *      pConnParam:             A pointer to a DSP_CBDATA structure that defines 
 *                              connection parameter for device nodes to pass to DSP side. 
 *                              If the value of this parameter is NULL, then this API behaves 
 *                              like DSPNode_Connect. This parameter will have length of the 
 *                              string and the null terminated string in DSP_CBDATA struct. 
 *                              This can be extended in future to pass binary data.
 *
 *  Returns:
 *      DSP_SOK:                Success.
 *      DSP_EHANDLE:            Invalid node handle.
 *      DSP_EMEMORY:            GPP memory allocation failure.
 *      DSP_EALREADYCONNCECTED: One of the specified connections has already
 *                              been made.
 *      DSP_EWRONGSTATE:        The node is not in the NODE_ALLOCATED state.
 *      DSP_EVALUE:             A Stream index is not valid.
 *      DSP_ENOMORECONNECTIONS: No more connections are allowed
 *      DSP_EFAIL:              Unable to make connection.
 *      DSP_ENOTIMPL:           Stream mode valid but not supported.
 *      DSP_ESTRMMODE           Illegal Stream mode specified.
 *
 */
	extern DBAPI DSPNode_ConnectEx(DSP_HNODE hNode, UINT uStream,
				       DSP_HNODE hOtherNode, UINT uOtherStream,
				       IN OPTIONAL struct DSP_STRMATTR * pAttr,
				       IN OPTIONAL struct DSP_CBDATA * pConnParam);

/*
 *  ======== DSPNode_Create ========
 *  Purpose:
 *      Create a node in a pre-run (i.e., inactive) state on its DSP processor.
 *  Parameters:
 *      hNode:              The node handle.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_ESYMBOL:        Create function, or iAlg, not found in the COFF file
 *      DSP_WRONGSTATE:     Operation is invalid for the current node state.
 *      DSP_ETASK:          Unable to create the task or process on the DSP.
 *      DSP_EMEMORY:        Memory Allocation failure on the DSP.
 *      DSP_ERESOURCE:      A requested resource is not available.
 *      DSP_EMULINST:       Multiple instances are not allowed.
 *      DSP_ENOTFOUND:      A specified entity was not found.
 *      DSP_EOUTOFIO:       An I/O resource is not available.
 *      DSP_ESTREAM:        Stream creation failure on the DSP.
 *      DSP_ETIMEOUT:       A timeout occurred before the DSP responded.
 *      DSP_ERESTART:       A critical error has occurred and the DSP is
 *                          being restarted.
 *      DSP_EOVERLAYMEMORY: Overlay region for this phase in use by another node
 *      DSP_EUSER1-16:      A node-specific failure occurred on the DSP.
 *      DSP_EFAIL:          Unable to Create the node.
 *  Details:
 */

	extern DBAPI DSPNode_Create(DSP_HNODE hNode);

/*
 *  ======== DSPNode_Delete ========
 *  Purpose:
 *      Delete all DSP-side and GPP-side resources for the node.
 *  Parameters:
 *      hNode:              The node handle.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_EDELETE:        A Deletion failure occured.
 *      DSP_EFREE:          A DSP memory free operation failed.
 *      DSP_EIOFREE:        A DSP I/O free operation failed.
 *      DSP_ETIMEOUT:       Timeout occured before the DSP responded.
 *      DSP_ERESTART:       A critical error has occurred and the DSP is
 *                          being restarted.
 *      DSP_EUSER1-16:      A node-specific failure occurred on the DSP.
 *      DSP_EOVERLAYMEMORY: Overlay region for this phase in use by another node
 *      DSP_EFAIL:          Unable to delete the node.
 *      DSP_ESYMBOL:        Delete function not found in the COFF file.
 */
	extern DBAPI DSPNode_Delete(DSP_HNODE hNode);

/*
 *  ======== DSPNode_FreeMsgBuf ========
 *  Purpose:
 *      Free a message buffer previously allocated by DSPNode_AllocMsgBuf..
 *  Parameters:
 *      hNode:              The node handle.
 *      pBuffer:            (Address) Buffer allocated by DSP_AllocMsgBuf.
 *      pAttr:              Same buffer attributes passed to DSP_AllocMsgBuf.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_EPOINTER:       pBuffer is not valid.
 *      DSP_EBADSEGID:      Invalid Segment Id.
 *      DSP_EFAIL:          Failure to free the buffer.
 */
	extern DBAPI DSPNode_FreeMsgBuf(DSP_HNODE hNode, IN BYTE * pBuffer,
					IN OPTIONAL struct DSP_BUFFERATTR * pAttr);

/*
 *  ======== DSPNode_GetAttr ========
 *  Purpose:
 *      Copy the current attributes of the specified node.
 *  Parameters:
 *      hNode:              The node handle.
 *      pAttr:              Location to store the node attributes.
 *      uAttrSize:          The size of structure.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_EPOINTER:       Parameter pAttr is not valid.
 *      DSP_EFAIL:          Unable to retrieve node attributes.
 *      DSP_ESIZE:          The size of the specified DSP_NODEATTR structure
 *                          is too small to hold all node information.
 */
	extern DBAPI DSPNode_GetAttr(DSP_HNODE hNode,
				     OUT struct DSP_NODEATTR * pAttr, UINT uAttrSize);

/*
 *  ======== DSPNode_GetMessage ========
 *  Purpose:
 *      Retrieve an event message from a task node.
 *  Parameters:
 *      hNode:              The node handle.
 *      pMessage:           The message structure.
 *      uTimeout:           Timeout to wait for message.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_EPOINTER:       Parameter pMessage is not valid.
 *      DSP_ENODETYPE:      Messages cannot be retrieved from this type of
 *                          node (eg a device node).
 *      DSP_ETIMEOUT:       A timeout occurred and there is no message ready.
 *      DSP_ERESTART:       A critical error has occurred and the DSP is
 *                          being restarted.
 *      DSP_EFAIL:          An error occurred trying to retrieve a message.
 *      DSP_ETRANSLATE      Message contains a shared memory buffer and unable
 *                          to map buffer to process.
 */
	extern DBAPI DSPNode_GetMessage(DSP_HNODE hNode, OUT struct DSP_MSG * pMessage,
					UINT uTimeout);

/*
 *  ======== DSPNode_Pause ========
 *  Purpose:
 *      Temporarily suspend execution of a task node that is
 *      currently running on a DSP.
 *  Parameters:
 *      hNode:              The node handle.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_ENODETYPE:      Invalid operation for this node type.
 *      DSP_ETIMEOUT:       A timeout occured before the DSP responded.
 *      DSP_EWRONGSTATE:    Operation is invalid for the current node state.
 *      DSP_ERESTART:       A critical error has occurred and the DSP is
 *                          being restarted.
 *      DSP_EFAIL:          General failure.
 */
	extern DBAPI DSPNode_Pause(DSP_HNODE hNode);

/*
 *  ======== DSPNode_PutMessage ========
 *  Purpose:
 *      Send an event message to a task node.
 *  Parameters:
 *      hNode:              The node handle.
 *      pMessage:           The message structure.
 *      uTimeout:           Timeout (msecs) waiting for message to be queued.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_EPOINTER:       Parameter pMessage is not valid.
 *      DSP_ENODETYPE:      Invalid operation for this node type
 *      DSP_EWRONGSTATE:    Node is in an invalid state to send a message.
 *      DSP_ETIMEOUT:       Time out occured.
 *      DSP_ERESTART:       A critical error has occurred and the DSP is
 *                          being restarted.
 *      DSP_ETRANSLATE      The shared memory buffer contained in the message
 *                          could not be mapped into the clients address space.
 *      DSP_EFAIL:          General failure.
 */
	extern DBAPI DSPNode_PutMessage(DSP_HNODE hNode,
					IN CONST struct DSP_MSG * pMessage,
					UINT uTimeout);

/*
 *  ======== DSPNode_RegisterNotify ========
 *  Purpose:
 *      Register to be notified of specific events for this node.
 *  Parameters:
 *      hNode:              The node handle.
 *      uEventMask:         Type of event about which to be notified.
 *      uNotifyType:        Type of notification to be sent.
 *      hNotification:      Handle of DSP_NOTIFICATION object.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle or hNotification.
 *      DSP_EVALUE:         Invalid uEventMask.
 *      DSP_ENOTIMP:        The specifed uNotifyType is not supported.
 *      DSP_EFAIL:          Unable to register for notification.
 */
	extern DBAPI DSPNode_RegisterNotify(DSP_HNODE hNode, UINT uEventMask,
					    UINT uNotifyType,
					    struct DSP_NOTIFICATION* hNotification);

/*
 *  ======== DSPNode_Run ========
 *  Purpose:
 *      Start a node running, or resume execution of a previously paused node.
 *  Parameters:
 *      hNode:              The node handle.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_ENODETYPE:      Invalid operation for this type of node.
 *      DSP_ESYMBOL:        Execute function not found in the COFF file.
 *      DSP_EWRONGSTATE:    The node is not in the Created or Paused state.
 *      DSP_ETIMEOUT:       A timeout occured before the DSP responded.
 *      DSP_ERESTART:       A critical error has occurred and the DSP is
 *                          being restarted.
 *      DSP_EOVERLAYMEMORY: Overlay region for this phase in use by another node
 *      DSP_EFAIL:          Unable to start or resume execution.
 */
	extern DBAPI DSPNode_Run(DSP_HNODE hNode);

/*
 *  ======== DSPNode_Terminate ========
 *  Purpose:
 *      Signal a task or xDAIS socket node running on a DSP processor that
 *      it should exit its execute-phase function.
 *  Parameters:
 *      hNode:              Handle of node to terminate.
 *      pStatus:            Location to execute-phase function return value.
 *                          Possible values are between DSP_EUSER1-16.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EHANDLE:        Invalid node handle.
 *      DSP_ENODETYPE:      Invalid operation for this type of node.
 *      DSP_EWRONGSTATE:    The node is not in the Created or Paused state.
 *      DSP_ETIMEOUT:       A timeout occured before the DSP responded.
 *      DSP_ERESTART:       A critical error has occurred and the DSP is
 *                          being restarted.
 *      DSP_EFAIL:          Unable to Terminate the node.
 */
	extern DBAPI DSPNode_Terminate(DSP_HNODE hNode, DSP_STATUS * pStatus);


/*
 *  ======== DSPNode_GetUUIDProps ========
 *  Purpose:
 *      Fetch the Node Properties from the DCD/DOF file, give the UUID
 *  Parameters:
 *      hProcessor:         The processor handle.
 *      pNodeID:            Ptr to DSP_UUID for the node.
 *      pNodeProps:         Ptr to location to store node properties.
 *  Returns:
 *      DSP_SOK:            Success.
 *      DSP_EPOINTER:       One of the input parameters pointers is invalid.
 *      DSP_EHANDLE:        Invalid processor handle.
 *      DSP_EMEMORY:        Memory is not available to allocate a node
 *      DSP_EUUID:          The node with the specified UUID is not registered.
 *      DSP_EWRONGSTATE:    The specified processor is in the wrong state
 *                          (not running)
 *      DSP_ERANGE:         The iPriority field specified in pAttrIn is out
 *                          of range.
 *      DSP_EFAIL:          General failure.
 */
	extern DBAPI DSPNode_GetUUIDProps(DSP_HPROCESSOR hProcessor,
				      IN CONST struct DSP_UUID * pNodeID,
				      OUT struct DSP_NDBPROPS * pNodeProps);
#ifdef __cplusplus
}
#endif
#endif				/* DSPNode_ */