1/* 2 * Copyright 2001-2008 Texas Instruments - http://www.ti.com/ 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18/* 19 * ======== DSPStream.h ======== 20 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 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#include <host_os.h> 56#ifndef DSPStream_ 57#define DSPStream_ 58 59#ifdef __cplusplus 60extern "C" { 61#endif 62 63/* 64 * ======== DSPStream_AllocateBuffers ======== 65 * Purpose: 66 * Allocate data buffers for use with a specific stream. 67 * Parameters: 68 * hStream: The stream handle. 69 * uSize: Size of the buffer 70 * apBuffer: Ptr to location to hold array of buffers. 71 * uNumBufs: The number of buffers to allocate of size uSize. 72 * Returns: 73 * DSP_SOK: Success. 74 * DSP_EHANDLE: Invalid Stream handle. 75 * DSP_EMEMORY: Insufficient memory 76 * DSP_EPOINTER: Parameter apBuffer is not valid. 77 * DSP_EALIGNMENT: Stream's alignment value not supported. 78 * DSP_ESIZE: Illegal size. 79 * DSP_EFAIL: General failure to allocate buffer. 80 * Details: 81 */ 82 extern DBAPI DSPStream_AllocateBuffers(DSP_HSTREAM hStream, 83 UINT uSize, OUT BYTE ** apBuffer, 84 UINT uNumBufs); 85 86/* 87 * ======== DSPStream_Close ======== 88 * Purpose: 89 * Close a stream and free the underlying stream object. 90 * Parameters: 91 * hStream: The stream handle. 92 * Returns: 93 * DSP_SOK: Success. 94 * DSP_EHANDLE: Invalid Stream handle. 95 * DSP_EPENDING: Not all stream buffers have been reclaimed 96 * DSP_EFAIL: Failure to Close the Stream 97 * Details: 98 */ 99 extern DBAPI DSPStream_Close(DSP_HSTREAM hStream); 100 101/* 102 * ======== DSPStream_FreeBuffers ======== 103 * Purpose: 104 * Free a previously allocated stream data buffer. 105 * Parameters: 106 * hStream: The stream handle. 107 * apBuffer: The array of buffers to free. 108 * uNumBufs: The number of buffers. 109 * Returns: 110 * DSP_SOK: Success. 111 * DSP_EHANDLE: Invalid Stream handle. 112 * DSP_EPOINTER: Parameter apBuffer is not valid. 113 * DSP_EFAIL: Failure to free the data buffers 114 * Details: 115 */ 116 extern DBAPI DSPStream_FreeBuffers(DSP_HSTREAM hStream, 117 IN BYTE ** apBuffer, UINT uNumBufs); 118 119/* 120 * ======== DSPStream_GetInfo ======== 121 * Purpose: 122 * Get information about a stream. 123 * Parameters: 124 * hStream: The stream handle. 125 * pStreamInfo: Ptr to the DSP_STREAMINFO structure. 126 * uStreamInfoSize: The size of structure. 127 * Returns: 128 * DSP_SOK: Success. 129 * DSP_EHANDLE: Invalid Stream handle. 130 * DSP_EPOINTER: Parameter pStreamInfo is invalid. 131 * DSP_ESIZE: uStreamInfoSize is too small to hold all stream 132 * information. 133 * DSP_EFAIL: Unable to retrieve Stream info 134 * Details: 135 */ 136 extern DBAPI DSPStream_GetInfo(DSP_HSTREAM hStream, 137 OUT struct DSP_STREAMINFO * pStreamInfo, 138 UINT uStreamInfoSize); 139 140/* 141 * ======== DSPStream_Idle ======== 142 * Purpose: 143 * Terminate I/O with a particular stream, and (optionally) 144 * flush output data buffers. 145 * Parameters: 146 * hStream: The stream handle. 147 * bFlush: Boolean flag 148 * Returns: 149 * DSP_SOK: Success. 150 * DSP_EHANDLE: Invalid Stream handle. 151 * DSP_ETIMEOUT: Time out occurred. 152 * DSP_ERESTART: A critical error has 153 * occurred and the DSP is being restarted. 154 * DSP_EFAIL: Unable to Idle the stream 155 * Details: 156 */ 157 extern DBAPI DSPStream_Idle(DSP_HSTREAM hStream, bool bFlush); 158 159/* 160 * ======== DSPStream_Issue ======== 161 * Purpose: 162 * Send a buffer of data to a stream. 163 * Parameters: 164 * hStream: The stream handle. 165 * pBuffer: Ptr to the buffer. 166 * dwDataSize: Size of data in buffer in bytes. 167 * dwBufSize: Size of actual buffer in bytes. 168 * dwArg: User defined buffer context. 169 * Returns: 170 * DSP_SOK: Success. 171 * DSP_EHANDLE: Invalid Stream handle. 172 * DSP_EPOINTER: Invalid pBuffer pointer 173 * DSP_ESTREAMFULL: The stream has been issued the maximum number 174 * of buffers allowed in the stream at once; 175 * buffers must be reclaimed from the stream 176 * before any more can be issued. 177 * DSP_EFAIL: Unable to issue the buffer. 178 * DSP_ETRANSLATE: Unable to map shared buffer to client process. 179 * Details: 180 */ 181 extern DBAPI DSPStream_Issue(DSP_HSTREAM hStream, IN BYTE * pBuffer, 182 ULONG dwDataSize, ULONG dwBufSize, 183 IN DWORD dwArg); 184 185/* 186 * ======== DSPStream_Open ======== 187 * Purpose: 188 * Retrieve a stream handle for sending/receiving data buffers 189 * to/from a task node on a DSP. 190 * Parameters: 191 * hNode: The node handle. 192 * uDirection: Stream direction: {DSP_TONODE | DSP_FROMNODE}. 193 * uIndex: Stream index (zero based). 194 * pAttrIn: Ptr to the stream attributes (optional) 195 * phStream: Ptr to location to store the stream handle. 196 * Returns: 197 * DSP_SOK: Success. 198 * DSP_EPOINTER: Invalid phStream pointer. 199 * DSP_ENODETYPE: Stream can not be opened for this node type/ 200 * DSP_EDIRECTION: uDirection is invalid 201 * DSP_EVALUE: uIndex is invalid, or, if pAttrIn != NULL, 202 * pAttrIn->uSegment is invalid. 203 * DSP_EFAIL: General failure. 204 * DSP_ESTRMMODE: Stream mode is invalid. 205 * DSP_EDMACHNL: DMAChnlId is invalid, if STRMMODE is LDMA or RDMA. 206 * DSP_EHANDLE: Invalid Stream handle. 207 * DSP_ENOTIMPL: Stream mode is not supported. 208 * 209 * Details: 210 */ 211 extern DBAPI DSPStream_Open(DSP_HNODE hNode, UINT uDirection, 212 UINT uIndex, 213 IN OPTIONAL struct DSP_STREAMATTRIN * pAttrIn, 214 OUT DSP_HSTREAM * phStream); 215 216/* 217 * ======== DSPStream_PrepareBuffer ======== 218 * Purpose: 219 * Prepare a buffer that was not allocated by DSPStream_AllocateBuffers 220 * for use with a stream 221 * Parameters: 222 * hStream: Stream handle 223 * uSize: Size of the allocated buffer(GPP bytes) 224 * pBffer: Address of the Allocated buffer 225 * Returns: 226 * DSP_SOK: Success 227 * DSP_EHANDLE: Invalid Stream handle 228 * DSP_EPOINTER: Invalid pBuffer 229 * DSP_EFAIL: Failure to Prepare a buffer 230 */ 231 extern DBAPI DSPStream_PrepareBuffer(DSP_HSTREAM hStream, UINT uSize, 232 BYTE * pBuffer); 233 234/* 235 * ======== DSPStream_Reclaim ======== 236 * Purpose: 237 * Request a buffer back from a stream. 238 * Parameters: 239 * hStream: The stream handle. 240 * pBufPtr: Ptr to location to store stream buffer. 241 * pDataSize: Ptr to location to store data size of the buffer. 242 * pBufSize: Ptr to location to store actual size of the buffer. 243 * pdwArg: Ptr to location to store user defined context. 244 * Returns: 245 * DSP_SOK: Success. 246 * DSP_EHANDLE: Invalid Stream handle. 247 * DSP_EPOINTER: One of pBufPtr or pBytes is invalid. 248 * DSP_ETIMEOUT: Timeout waiting from I/O completion. 249 * DSP_ERESTART: A critical error has occurred and 250 * the DSP is being restarted. 251 * DSP_EFAIL: Unable to Reclaim buffer. 252 * DSP_ETRANSLATE: Unable to map shared buffer to client process. 253 * Details: 254 */ 255 extern DBAPI DSPStream_Reclaim(DSP_HSTREAM hStream, 256 OUT BYTE ** pBufPtr, 257 OUT ULONG * pDataSize, 258 OUT ULONG * pBufSize, 259 OUT DWORD * pdwArg); 260 261/* 262 * ======== DSPStream_RegisterNotify ======== 263 * Purpose: 264 * Register to be notified of specific events for this stream. 265 * Parameters: 266 * hStream: The stream handle. 267 * uEventMask: Type of event to be notified about. 268 * uNotifyType: Type of notification to be sent. 269 * hNotification: Handle to be used for notification. 270 * Returns: 271 * DSP_SOK: Success. 272 * DSP_EHANDLE: Invalid stream handle or invalid hNotification 273 * DSP_EVALUE: uEventMask is invalid 274 * DSP_ENOTIMP: Not supported as specified in uNotifyType 275 * DSP_EFAIL: Unable to Register for notification 276 * Details: 277 */ 278 extern DBAPI DSPStream_RegisterNotify(DSP_HSTREAM hStream, 279 UINT uEventMask, UINT uNotifyType, 280 struct DSP_NOTIFICATION* hNotification); 281 282/* 283 * ======== DSPStream_Select ======== 284 * Purpose: 285 * Select a ready stream. 286 * Parameters: 287 * aStreamTab: Array of stream handles. 288 * nStreams: Number of streams in array. 289 * pMask: Pointer to the mask of ready streams. 290 * uTimeout: Timeout value in milliseconds. 291 * Returns: 292 * DSP_SOK: Success. 293 * DSP_ERANGE: nStreams is out of range 294 * DSP_EPOINTER: Invalid aStreamTab or pMask pointer. 295 * DSP_ETIMEOUT Timeout occured. 296 * DSP_EFAIL: Failure to select a stream. 297 * DSP_ERESTART: A critical error has occurred and 298 * the DSP is being restarted. 299 * Details: 300 */ 301 extern DBAPI DSPStream_Select(IN DSP_HSTREAM * aStreamTab, 302 UINT nStreams, OUT UINT * pMask, 303 UINT uTimeout); 304 305/* 306 * ======== DSPStream_UnprepareBuffer ======== 307 * Purpose: 308 * UnPrepare a buffer that was prepared by DSPStream_PrepareBuffer 309 * and will no longer be used with the stream 310 * Parameters: 311 * hStream: Stream handle 312 * uSize: Size of the allocated buffer(GPP bytes) 313 * pBffer: Address of the Allocated buffer 314 * Returns: 315 * DSP_SOK: Success 316 * DSP_EHANDLE: Invalid Stream handle 317 * DSP_EPOINTER: Invalid pBuffer 318 * DSP_EFAIL: Failure to UnPrepare a buffer 319 */ 320 extern DBAPI DSPStream_UnprepareBuffer(DSP_HSTREAM hStream, UINT uSize, 321 BYTE * pBuffer); 322 323#ifdef __cplusplus 324} 325#endif 326#endif /* DSPStream_ */ 327