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
62 extern "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