452 lines
19 KiB
C
452 lines
19 KiB
C
/*
|
|
* 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_ */
|