/* * dspbridge/mpu_api/inc/DSPStream.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. */ /* * ======== DSPStream.h ======== * Description: * This is the header for the DSP/BIOS Bridge stream module. * * Public Functions: * DSPStream_AllocateBuffers * DSPStream_Close * DSPStream_FreeBuffers * DSPStream_GetInfo * DSPStream_Idle * DSPStream_Issue * DSPStream_Open * DSPStream_Reclaim * DSPStream_RegisterNotify * DSPStream_Select * * Notes: * *! Revision History: *! ================ *! 23-Nov-2002 gp: Comment change: uEventMask is really a "type". *! 17-Dec-2001 ag Fix return codes in DSPStream_[Issue][Reclaim] *! 12-Dec-2001 ag Added DSP_ENOTIMPL error code to DSPStream_Open(). *! 17-Nov-2001 ag Added DSP_ETRANSLATE error. *! Added bufSize param and renamed dwBytes to dwDataSize in *! DSPStream_[Issue][Reclaim](). *! 07-Jun-2001 sg: Made buffer alloc/free fxn names plural. *! 13-Feb-2001 kc: DSP/BIOS Bridge name updates. *! 27-Sep-2000 jeh Removed DSP_BUFFERATTR parameter from DSPStream_Allocate- *! Buffer(), since these have been moved to DSP_STREAMATTRIN. *! 07-Sep-2000 jeh Changed type HANDLE in DSPStream_RegisterNotify to *! DSP_HNOTIFICATION. *! 20-Jul-2000 rr: Updated to version 0.8 *! 27-Jun-2000 rr: Created from DBAPI.h */ #include #ifndef DSPStream_ #define DSPStream_ #ifdef __cplusplus extern "C" { #endif /* * ======== DSPStream_AllocateBuffers ======== * Purpose: * Allocate data buffers for use with a specific stream. * Parameters: * hStream: The stream handle. * uSize: Size of the buffer * apBuffer: Ptr to location to hold array of buffers. * uNumBufs: The number of buffers to allocate of size uSize. * Returns: * DSP_SOK: Success. * DSP_EHANDLE: Invalid Stream handle. * DSP_EMEMORY: Insufficient memory * DSP_EPOINTER: Parameter apBuffer is not valid. * DSP_EALIGNMENT: Stream's alignment value not supported. * DSP_ESIZE: Illegal size. * DSP_EFAIL: General failure to allocate buffer. * Details: */ extern DBAPI DSPStream_AllocateBuffers(DSP_HSTREAM hStream, UINT uSize, OUT BYTE ** apBuffer, UINT uNumBufs); /* * ======== DSPStream_Close ======== * Purpose: * Close a stream and free the underlying stream object. * Parameters: * hStream: The stream handle. * Returns: * DSP_SOK: Success. * DSP_EHANDLE: Invalid Stream handle. * DSP_EPENDING: Not all stream buffers have been reclaimed * DSP_EFAIL: Failure to Close the Stream * Details: */ extern DBAPI DSPStream_Close(DSP_HSTREAM hStream); /* * ======== DSPStream_FreeBuffers ======== * Purpose: * Free a previously allocated stream data buffer. * Parameters: * hStream: The stream handle. * apBuffer: The array of buffers to free. * uNumBufs: The number of buffers. * Returns: * DSP_SOK: Success. * DSP_EHANDLE: Invalid Stream handle. * DSP_EPOINTER: Parameter apBuffer is not valid. * DSP_EFAIL: Failure to free the data buffers * Details: */ extern DBAPI DSPStream_FreeBuffers(DSP_HSTREAM hStream, IN BYTE ** apBuffer, UINT uNumBufs); /* * ======== DSPStream_GetInfo ======== * Purpose: * Get information about a stream. * Parameters: * hStream: The stream handle. * pStreamInfo: Ptr to the DSP_STREAMINFO structure. * uStreamInfoSize: The size of structure. * Returns: * DSP_SOK: Success. * DSP_EHANDLE: Invalid Stream handle. * DSP_EPOINTER: Parameter pStreamInfo is invalid. * DSP_ESIZE: uStreamInfoSize is too small to hold all stream * information. * DSP_EFAIL: Unable to retrieve Stream info * Details: */ extern DBAPI DSPStream_GetInfo(DSP_HSTREAM hStream, OUT struct DSP_STREAMINFO * pStreamInfo, UINT uStreamInfoSize); /* * ======== DSPStream_Idle ======== * Purpose: * Terminate I/O with a particular stream, and (optionally) * flush output data buffers. * Parameters: * hStream: The stream handle. * bFlush: Boolean flag * Returns: * DSP_SOK: Success. * DSP_EHANDLE: Invalid Stream handle. * DSP_ETIMEOUT: Time out occurred. * DSP_ERESTART: A critical error has * occurred and the DSP is being restarted. * DSP_EFAIL: Unable to Idle the stream * Details: */ extern DBAPI DSPStream_Idle(DSP_HSTREAM hStream, bool bFlush); /* * ======== DSPStream_Issue ======== * Purpose: * Send a buffer of data to a stream. * Parameters: * hStream: The stream handle. * pBuffer: Ptr to the buffer. * dwDataSize: Size of data in buffer in bytes. * dwBufSize: Size of actual buffer in bytes. * dwArg: User defined buffer context. * Returns: * DSP_SOK: Success. * DSP_EHANDLE: Invalid Stream handle. * DSP_EPOINTER: Invalid pBuffer pointer * DSP_ESTREAMFULL: The stream has been issued the maximum number * of buffers allowed in the stream at once; * buffers must be reclaimed from the stream * before any more can be issued. * DSP_EFAIL: Unable to issue the buffer. * DSP_ETRANSLATE: Unable to map shared buffer to client process. * Details: */ extern DBAPI DSPStream_Issue(DSP_HSTREAM hStream, IN BYTE * pBuffer, ULONG dwDataSize, ULONG dwBufSize, IN DWORD dwArg); /* * ======== DSPStream_Open ======== * Purpose: * Retrieve a stream handle for sending/receiving data buffers * to/from a task node on a DSP. * Parameters: * hNode: The node handle. * uDirection: Stream direction: {DSP_TONODE | DSP_FROMNODE}. * uIndex: Stream index (zero based). * pAttrIn: Ptr to the stream attributes (optional) * phStream: Ptr to location to store the stream handle. * Returns: * DSP_SOK: Success. * DSP_EPOINTER: Invalid phStream pointer. * DSP_ENODETYPE: Stream can not be opened for this node type/ * DSP_EDIRECTION: uDirection is invalid * DSP_EVALUE: uIndex is invalid, or, if pAttrIn != NULL, * pAttrIn->uSegment is invalid. * DSP_EFAIL: General failure. * DSP_ESTRMMODE: Stream mode is invalid. * DSP_EDMACHNL: DMAChnlId is invalid, if STRMMODE is LDMA or RDMA. * DSP_EHANDLE: Invalid Stream handle. * DSP_ENOTIMPL: Stream mode is not supported. * * Details: */ extern DBAPI DSPStream_Open(DSP_HNODE hNode, UINT uDirection, UINT uIndex, IN OPTIONAL struct DSP_STREAMATTRIN * pAttrIn, OUT DSP_HSTREAM * phStream); /* * ======== DSPStream_PrepareBuffer ======== * Purpose: * Prepare a buffer that was not allocated by DSPStream_AllocateBuffers * for use with a stream * Parameters: * hStream: Stream handle * uSize: Size of the allocated buffer(GPP bytes) * pBffer: Address of the Allocated buffer * Returns: * DSP_SOK: Success * DSP_EHANDLE: Invalid Stream handle * DSP_EPOINTER: Invalid pBuffer * DSP_EFAIL: Failure to Prepare a buffer */ extern DBAPI DSPStream_PrepareBuffer(DSP_HSTREAM hStream, UINT uSize, BYTE * pBuffer); /* * ======== DSPStream_Reclaim ======== * Purpose: * Request a buffer back from a stream. * Parameters: * hStream: The stream handle. * pBufPtr: Ptr to location to store stream buffer. * pDataSize: Ptr to location to store data size of the buffer. * pBufSize: Ptr to location to store actual size of the buffer. * pdwArg: Ptr to location to store user defined context. * Returns: * DSP_SOK: Success. * DSP_EHANDLE: Invalid Stream handle. * DSP_EPOINTER: One of pBufPtr or pBytes is invalid. * DSP_ETIMEOUT: Timeout waiting from I/O completion. * DSP_ERESTART: A critical error has occurred and * the DSP is being restarted. * DSP_EFAIL: Unable to Reclaim buffer. * DSP_ETRANSLATE: Unable to map shared buffer to client process. * Details: */ extern DBAPI DSPStream_Reclaim(DSP_HSTREAM hStream, OUT BYTE ** pBufPtr, OUT ULONG * pDataSize, OUT ULONG * pBufSize, OUT DWORD * pdwArg); /* * ======== DSPStream_RegisterNotify ======== * Purpose: * Register to be notified of specific events for this stream. * Parameters: * hStream: The stream handle. * uEventMask: Type of event to be notified about. * uNotifyType: Type of notification to be sent. * hNotification: Handle to be used for notification. * Returns: * DSP_SOK: Success. * DSP_EHANDLE: Invalid stream handle or invalid hNotification * DSP_EVALUE: uEventMask is invalid * DSP_ENOTIMP: Not supported as specified in uNotifyType * DSP_EFAIL: Unable to Register for notification * Details: */ extern DBAPI DSPStream_RegisterNotify(DSP_HSTREAM hStream, UINT uEventMask, UINT uNotifyType, struct DSP_NOTIFICATION* hNotification); /* * ======== DSPStream_Select ======== * Purpose: * Select a ready stream. * Parameters: * aStreamTab: Array of stream handles. * nStreams: Number of streams in array. * pMask: Pointer to the mask of ready streams. * uTimeout: Timeout value in milliseconds. * Returns: * DSP_SOK: Success. * DSP_ERANGE: nStreams is out of range * DSP_EPOINTER: Invalid aStreamTab or pMask pointer. * DSP_ETIMEOUT Timeout occured. * DSP_EFAIL: Failure to select a stream. * DSP_ERESTART: A critical error has occurred and * the DSP is being restarted. * Details: */ extern DBAPI DSPStream_Select(IN DSP_HSTREAM * aStreamTab, UINT nStreams, OUT UINT * pMask, UINT uTimeout); /* * ======== DSPStream_UnprepareBuffer ======== * Purpose: * UnPrepare a buffer that was prepared by DSPStream_PrepareBuffer * and will no longer be used with the stream * Parameters: * hStream: Stream handle * uSize: Size of the allocated buffer(GPP bytes) * pBffer: Address of the Allocated buffer * Returns: * DSP_SOK: Success * DSP_EHANDLE: Invalid Stream handle * DSP_EPOINTER: Invalid pBuffer * DSP_EFAIL: Failure to UnPrepare a buffer */ extern DBAPI DSPStream_UnprepareBuffer(DSP_HSTREAM hStream, UINT uSize, BYTE * pBuffer); #ifdef __cplusplus } #endif #endif /* DSPStream_ */