1/* 2 * dspbridge/mpu_api/inc/DSPStream.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Copyright (C) 2007 Texas Instruments, Inc. 7 * 8 * This program is free software; you can redistribute it and/or modify it 9 * under the terms of the GNU Lesser General Public License as published 10 * by the Free Software Foundation version 2.1 of the License. 11 * 12 * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind, 13 * whether express or implied; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 */ 17 18 19/* 20 * ======== DSPStream.h ======== 21 * Description: 22 * This is the header for the DSP/BIOS Bridge stream module. 23 * 24 * Public Functions: 25 * DSPStream_AllocateBuffers 26 * DSPStream_Close 27 * DSPStream_FreeBuffers 28 * DSPStream_GetInfo 29 * DSPStream_Idle 30 * DSPStream_Issue 31 * DSPStream_Open 32 * DSPStream_Reclaim 33 * DSPStream_RegisterNotify 34 * DSPStream_Select 35 * 36 * Notes: 37 * 38 *! Revision History: 39 *! ================ 40 *! 23-Nov-2002 gp: Comment change: uEventMask is really a "type". 41 *! 17-Dec-2001 ag Fix return codes in DSPStream_[Issue][Reclaim] 42 *! 12-Dec-2001 ag Added DSP_ENOTIMPL error code to DSPStream_Open(). 43 *! 17-Nov-2001 ag Added DSP_ETRANSLATE error. 44 *! Added bufSize param and renamed dwBytes to dwDataSize in 45 *! DSPStream_[Issue][Reclaim](). 46 *! 07-Jun-2001 sg: Made buffer alloc/free fxn names plural. 47 *! 13-Feb-2001 kc: DSP/BIOS Bridge name updates. 48 *! 27-Sep-2000 jeh Removed DSP_BUFFERATTR parameter from DSPStream_Allocate- 49 *! Buffer(), since these have been moved to DSP_STREAMATTRIN. 50 *! 07-Sep-2000 jeh Changed type HANDLE in DSPStream_RegisterNotify to 51 *! DSP_HNOTIFICATION. 52 *! 20-Jul-2000 rr: Updated to version 0.8 53 *! 27-Jun-2000 rr: Created from DBAPI.h 54 */ 55 56#include <host_os.h> 57 58#ifndef DSPStream_ 59#define DSPStream_ 60 61#ifdef __cplusplus 62extern "C" { 63#endif 64 65/* 66 * ======== DSPStream_AllocateBuffers ======== 67 * Purpose: 68 * Allocate data buffers for use with a specific stream. 69 * Parameters: 70 * hStream: The stream handle. 71 * uSize: Size of the buffer 72 * apBuffer: Ptr to location to hold array of buffers. 73 * uNumBufs: The number of buffers to allocate of size uSize. 74 * Returns: 75 * DSP_SOK: Success. 76 * DSP_EHANDLE: Invalid Stream handle. 77 * DSP_EMEMORY: Insufficient memory 78 * DSP_EPOINTER: Parameter apBuffer is not valid. 79 * DSP_EALIGNMENT: Stream's alignment value not supported. 80 * DSP_ESIZE: Illegal size. 81 * DSP_EFAIL: General failure to allocate buffer. 82 * Details: 83 */ 84 extern DBAPI DSPStream_AllocateBuffers(DSP_HSTREAM hStream, 85 UINT uSize, OUT BYTE ** apBuffer, 86 UINT uNumBufs); 87 88/* 89 * ======== DSPStream_Close ======== 90 * Purpose: 91 * Close a stream and free the underlying stream object. 92 * Parameters: 93 * hStream: The stream handle. 94 * Returns: 95 * DSP_SOK: Success. 96 * DSP_EHANDLE: Invalid Stream handle. 97 * DSP_EPENDING: Not all stream buffers have been reclaimed 98 * DSP_EFAIL: Failure to Close the Stream 99 * Details: 100 */ 101 extern DBAPI DSPStream_Close(DSP_HSTREAM hStream); 102 103/* 104 * ======== DSPStream_FreeBuffers ======== 105 * Purpose: 106 * Free a previously allocated stream data buffer. 107 * Parameters: 108 * hStream: The stream handle. 109 * apBuffer: The array of buffers to free. 110 * uNumBufs: The number of buffers. 111 * Returns: 112 * DSP_SOK: Success. 113 * DSP_EHANDLE: Invalid Stream handle. 114 * DSP_EPOINTER: Parameter apBuffer is not valid. 115 * DSP_EFAIL: Failure to free the data buffers 116 * Details: 117 */ 118 extern DBAPI DSPStream_FreeBuffers(DSP_HSTREAM hStream, 119 IN BYTE ** apBuffer, UINT uNumBufs); 120 121/* 122 * ======== DSPStream_GetInfo ======== 123 * Purpose: 124 * Get information about a stream. 125 * Parameters: 126 * hStream: The stream handle. 127 * pStreamInfo: Ptr to the DSP_STREAMINFO structure. 128 * uStreamInfoSize: The size of structure. 129 * Returns: 130 * DSP_SOK: Success. 131 * DSP_EHANDLE: Invalid Stream handle. 132 * DSP_EPOINTER: Parameter pStreamInfo is invalid. 133 * DSP_ESIZE: uStreamInfoSize is too small to hold all stream 134 * information. 135 * DSP_EFAIL: Unable to retrieve Stream info 136 * Details: 137 */ 138 extern DBAPI DSPStream_GetInfo(DSP_HSTREAM hStream, 139 OUT struct DSP_STREAMINFO * pStreamInfo, 140 UINT uStreamInfoSize); 141 142/* 143 * ======== DSPStream_Idle ======== 144 * Purpose: 145 * Terminate I/O with a particular stream, and (optionally) 146 * flush output data buffers. 147 * Parameters: 148 * hStream: The stream handle. 149 * bFlush: Boolean flag 150 * Returns: 151 * DSP_SOK: Success. 152 * DSP_EHANDLE: Invalid Stream handle. 153 * DSP_ETIMEOUT: Time out occurred. 154 * DSP_ERESTART: A critical error has 155 * occurred and the DSP is being restarted. 156 * DSP_EFAIL: Unable to Idle the stream 157 * Details: 158 */ 159 extern DBAPI DSPStream_Idle(DSP_HSTREAM hStream, bool bFlush); 160 161/* 162 * ======== DSPStream_Issue ======== 163 * Purpose: 164 * Send a buffer of data to a stream. 165 * Parameters: 166 * hStream: The stream handle. 167 * pBuffer: Ptr to the buffer. 168 * dwDataSize: Size of data in buffer in bytes. 169 * dwBufSize: Size of actual buffer in bytes. 170 * dwArg: User defined buffer context. 171 * Returns: 172 * DSP_SOK: Success. 173 * DSP_EHANDLE: Invalid Stream handle. 174 * DSP_EPOINTER: Invalid pBuffer pointer 175 * DSP_ESTREAMFULL: The stream has been issued the maximum number 176 * of buffers allowed in the stream at once; 177 * buffers must be reclaimed from the stream 178 * before any more can be issued. 179 * DSP_EFAIL: Unable to issue the buffer. 180 * DSP_ETRANSLATE: Unable to map shared buffer to client process. 181 * Details: 182 */ 183 extern DBAPI DSPStream_Issue(DSP_HSTREAM hStream, IN BYTE * pBuffer, 184 ULONG dwDataSize, ULONG dwBufSize, 185 IN DWORD dwArg); 186 187/* 188 * ======== DSPStream_Open ======== 189 * Purpose: 190 * Retrieve a stream handle for sending/receiving data buffers 191 * to/from a task node on a DSP. 192 * Parameters: 193 * hNode: The node handle. 194 * uDirection: Stream direction: {DSP_TONODE | DSP_FROMNODE}. 195 * uIndex: Stream index (zero based). 196 * pAttrIn: Ptr to the stream attributes (optional) 197 * phStream: Ptr to location to store the stream handle. 198 * Returns: 199 * DSP_SOK: Success. 200 * DSP_EPOINTER: Invalid phStream pointer. 201 * DSP_ENODETYPE: Stream can not be opened for this node type/ 202 * DSP_EDIRECTION: uDirection is invalid 203 * DSP_EVALUE: uIndex is invalid, or, if pAttrIn != NULL, 204 * pAttrIn->uSegment is invalid. 205 * DSP_EFAIL: General failure. 206 * DSP_ESTRMMODE: Stream mode is invalid. 207 * DSP_EDMACHNL: DMAChnlId is invalid, if STRMMODE is LDMA or RDMA. 208 * DSP_EHANDLE: Invalid Stream handle. 209 * DSP_ENOTIMPL: Stream mode is not supported. 210 * 211 * Details: 212 */ 213 extern DBAPI DSPStream_Open(DSP_HNODE hNode, UINT uDirection, 214 UINT uIndex, 215 IN OPTIONAL struct DSP_STREAMATTRIN * pAttrIn, 216 OUT DSP_HSTREAM * phStream); 217 218/* 219 * ======== DSPStream_PrepareBuffer ======== 220 * Purpose: 221 * Prepare a buffer that was not allocated by DSPStream_AllocateBuffers 222 * for use with a stream 223 * Parameters: 224 * hStream: Stream handle 225 * uSize: Size of the allocated buffer(GPP bytes) 226 * pBffer: Address of the Allocated buffer 227 * Returns: 228 * DSP_SOK: Success 229 * DSP_EHANDLE: Invalid Stream handle 230 * DSP_EPOINTER: Invalid pBuffer 231 * DSP_EFAIL: Failure to Prepare a buffer 232 */ 233 extern DBAPI DSPStream_PrepareBuffer(DSP_HSTREAM hStream, UINT uSize, 234 BYTE * pBuffer); 235 236/* 237 * ======== DSPStream_Reclaim ======== 238 * Purpose: 239 * Request a buffer back from a stream. 240 * Parameters: 241 * hStream: The stream handle. 242 * pBufPtr: Ptr to location to store stream buffer. 243 * pDataSize: Ptr to location to store data size of the buffer. 244 * pBufSize: Ptr to location to store actual size of the buffer. 245 * pdwArg: Ptr to location to store user defined context. 246 * Returns: 247 * DSP_SOK: Success. 248 * DSP_EHANDLE: Invalid Stream handle. 249 * DSP_EPOINTER: One of pBufPtr or pBytes is invalid. 250 * DSP_ETIMEOUT: Timeout waiting from I/O completion. 251 * DSP_ERESTART: A critical error has occurred and 252 * the DSP is being restarted. 253 * DSP_EFAIL: Unable to Reclaim buffer. 254 * DSP_ETRANSLATE: Unable to map shared buffer to client process. 255 * Details: 256 */ 257 extern DBAPI DSPStream_Reclaim(DSP_HSTREAM hStream, 258 OUT BYTE ** pBufPtr, 259 OUT ULONG * pDataSize, 260 OUT ULONG * pBufSize, 261 OUT DWORD * pdwArg); 262 263/* 264 * ======== DSPStream_RegisterNotify ======== 265 * Purpose: 266 * Register to be notified of specific events for this stream. 267 * Parameters: 268 * hStream: The stream handle. 269 * uEventMask: Type of event to be notified about. 270 * uNotifyType: Type of notification to be sent. 271 * hNotification: Handle to be used for notification. 272 * Returns: 273 * DSP_SOK: Success. 274 * DSP_EHANDLE: Invalid stream handle or invalid hNotification 275 * DSP_EVALUE: uEventMask is invalid 276 * DSP_ENOTIMP: Not supported as specified in uNotifyType 277 * DSP_EFAIL: Unable to Register for notification 278 * Details: 279 */ 280 extern DBAPI DSPStream_RegisterNotify(DSP_HSTREAM hStream, 281 UINT uEventMask, UINT uNotifyType, 282 struct DSP_NOTIFICATION* hNotification); 283 284/* 285 * ======== DSPStream_Select ======== 286 * Purpose: 287 * Select a ready stream. 288 * Parameters: 289 * aStreamTab: Array of stream handles. 290 * nStreams: Number of streams in array. 291 * pMask: Pointer to the mask of ready streams. 292 * uTimeout: Timeout value in milliseconds. 293 * Returns: 294 * DSP_SOK: Success. 295 * DSP_ERANGE: nStreams is out of range 296 * DSP_EPOINTER: Invalid aStreamTab or pMask pointer. 297 * DSP_ETIMEOUT Timeout occured. 298 * DSP_EFAIL: Failure to select a stream. 299 * DSP_ERESTART: A critical error has occurred and 300 * the DSP is being restarted. 301 * Details: 302 */ 303 extern DBAPI DSPStream_Select(IN DSP_HSTREAM * aStreamTab, 304 UINT nStreams, OUT UINT * pMask, 305 UINT uTimeout); 306 307/* 308 * ======== DSPStream_UnprepareBuffer ======== 309 * Purpose: 310 * UnPrepare a buffer that was prepared by DSPStream_PrepareBuffer 311 * and will no longer be used with the stream 312 * Parameters: 313 * hStream: Stream handle 314 * uSize: Size of the allocated buffer(GPP bytes) 315 * pBffer: Address of the Allocated buffer 316 * Returns: 317 * DSP_SOK: Success 318 * DSP_EHANDLE: Invalid Stream handle 319 * DSP_EPOINTER: Invalid pBuffer 320 * DSP_EFAIL: Failure to UnPrepare a buffer 321 */ 322 extern DBAPI DSPStream_UnprepareBuffer(DSP_HSTREAM hStream, UINT uSize, 323 BYTE * pBuffer); 324 325#ifdef __cplusplus 326} 327#endif 328#endif /* DSPStream_ */ 329