staging: tidspbridge: remove strm_init() and strm_exit()
[linux-3.10.git] / drivers / staging / tidspbridge / include / dspbridge / strm.h
1 /*
2  * strm.h
3  *
4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
5  *
6  * DSPBridge Stream Manager.
7  *
8  * Copyright (C) 2005-2006 Texas Instruments, Inc.
9  *
10  * This package is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License version 2 as
12  * published by the Free Software Foundation.
13  *
14  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
15  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
16  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17  */
18
19 #ifndef STRM_
20 #define STRM_
21
22 #include <dspbridge/dev.h>
23
24 #include <dspbridge/strmdefs.h>
25 #include <dspbridge/proc.h>
26
27 /*
28  *  ======== strm_allocate_buffer ========
29  *  Purpose:
30  *      Allocate data buffer(s) for use with a stream.
31  *  Parameter:
32  *      strmres:     Stream resource info handle returned from strm_open().
33  *      usize:          Size (GPP bytes) of the buffer(s).
34  *      num_bufs:       Number of buffers to allocate.
35  *      ap_buffer:       Array to hold buffer addresses.
36  *  Returns:
37  *      0:        Success.
38  *      -EFAULT:    Invalid stream_obj.
39  *      -ENOMEM:    Insufficient memory.
40  *      -EPERM:      Failure occurred, unable to allocate buffers.
41  *      -EINVAL:      usize must be > 0 bytes.
42  *  Requires:
43  *      ap_buffer != NULL.
44  *  Ensures:
45  */
46 extern int strm_allocate_buffer(struct strm_res_object *strmres,
47                                        u32 usize,
48                                        u8 **ap_buffer,
49                                        u32 num_bufs,
50                                        struct process_context *pr_ctxt);
51
52 /*
53  *  ======== strm_close ========
54  *  Purpose:
55  *      Close a stream opened with strm_open().
56  *  Parameter:
57  *      strmres:          Stream resource info handle returned from strm_open().
58  *  Returns:
59  *      0:        Success.
60  *      -EFAULT:    Invalid stream_obj.
61  *      -EPIPE:   Some data buffers issued to the stream have not
62  *                      been reclaimed.
63  *      -EPERM:      Failure to close stream.
64  *  Requires:
65  *  Ensures:
66  */
67 extern int strm_close(struct strm_res_object *strmres,
68                              struct process_context *pr_ctxt);
69
70 /*
71  *  ======== strm_create ========
72  *  Purpose:
73  *      Create a STRM manager object. This object holds information about the
74  *      device needed to open streams.
75  *  Parameters:
76  *      strm_man:       Location to store handle to STRM manager object on
77  *                      output.
78  *      dev_obj:           Device for this processor.
79  *  Returns:
80  *      0:        Success;
81  *      -ENOMEM:    Insufficient memory for requested resources.
82  *      -EPERM:      General failure.
83  *  Requires:
84  *      strm_man != NULL.
85  *      dev_obj != NULL.
86  *  Ensures:
87  *      0:        Valid *strm_man.
88  *      error:          *strm_man == NULL.
89  */
90 extern int strm_create(struct strm_mgr **strm_man,
91                               struct dev_object *dev_obj);
92
93 /*
94  *  ======== strm_delete ========
95  *  Purpose:
96  *      Delete the STRM Object.
97  *  Parameters:
98  *      strm_mgr_obj:       Handle to STRM manager object from strm_create.
99  *  Returns:
100  *  Requires:
101  *      Valid strm_mgr_obj.
102  *  Ensures:
103  *      strm_mgr_obj is not valid.
104  */
105 extern void strm_delete(struct strm_mgr *strm_mgr_obj);
106
107 /*
108  *  ======== strm_free_buffer ========
109  *  Purpose:
110  *      Free buffer(s) allocated with strm_allocate_buffer.
111  *  Parameter:
112  *      strmres:     Stream resource info handle returned from strm_open().
113  *      ap_buffer:       Array containing buffer addresses.
114  *      num_bufs:       Number of buffers to be freed.
115  *  Returns:
116  *      0:        Success.
117  *      -EFAULT:    Invalid stream handle.
118  *      -EPERM:      Failure occurred, unable to free buffers.
119  *  Requires:
120  *      ap_buffer != NULL.
121  *  Ensures:
122  */
123 extern int strm_free_buffer(struct strm_res_object *strmres,
124                                    u8 **ap_buffer, u32 num_bufs,
125                                    struct process_context *pr_ctxt);
126
127 /*
128  *  ======== strm_get_info ========
129  *  Purpose:
130  *      Get information about a stream. User's dsp_streaminfo is contained
131  *      in stream_info struct. stream_info also contains Bridge private info.
132  *  Parameters:
133  *      stream_obj:         Stream handle returned from strm_open().
134  *      stream_info:        Location to store stream info on output.
135  *      uSteamInfoSize:     Size of user's dsp_streaminfo structure.
136  *  Returns:
137  *      0:            Success.
138  *      -EFAULT:        Invalid stream_obj.
139  *      -EINVAL:          stream_info_size < sizeof(dsp_streaminfo).
140  *      -EPERM:          Unable to get stream info.
141  *  Requires:
142  *      stream_info != NULL.
143  *  Ensures:
144  */
145 extern int strm_get_info(struct strm_object *stream_obj,
146                                 struct stream_info *stream_info,
147                                 u32 stream_info_size);
148
149 /*
150  *  ======== strm_idle ========
151  *  Purpose:
152  *      Idle a stream and optionally flush output data buffers.
153  *      If this is an output stream and flush_data is TRUE, all data currently
154  *      enqueued will be discarded.
155  *      If this is an output stream and flush_data is FALSE, this function
156  *      will block until all currently buffered data is output, or the timeout
157  *      specified has been reached.
158  *      After a successful call to strm_idle(), all buffers can immediately
159  *      be reclaimed.
160  *  Parameters:
161  *      stream_obj:     Stream handle returned from strm_open().
162  *      flush_data:     If TRUE, discard output buffers.
163  *  Returns:
164  *      0:        Success.
165  *      -EFAULT:    Invalid stream_obj.
166  *      -ETIME:   A timeout occurred before the stream could be idled.
167  *      -EPERM:      Unable to idle stream.
168  *  Requires:
169  *  Ensures:
170  */
171 extern int strm_idle(struct strm_object *stream_obj, bool flush_data);
172
173 /*
174  *  ======== strm_issue ========
175  *  Purpose:
176  *      Send a buffer of data to a stream.
177  *  Parameters:
178  *      stream_obj:         Stream handle returned from strm_open().
179  *      pbuf:               Pointer to buffer of data to be sent to the stream.
180  *      ul_bytes:            Number of bytes of data in the buffer.
181  *      ul_buf_size:          Actual buffer size in bytes.
182  *      dw_arg:              A user argument that travels with the buffer.
183  *  Returns:
184  *      0:            Success.
185  *      -EFAULT:        Invalid stream_obj.
186  *      -ENOSR:    The stream is full.
187  *      -EPERM:          Failure occurred, unable to issue buffer.
188  *  Requires:
189 *      pbuf != NULL.
190  *  Ensures:
191  */
192 extern int strm_issue(struct strm_object *stream_obj, u8 * pbuf,
193                              u32 ul_bytes, u32 ul_buf_size, u32 dw_arg);
194
195 /*
196  *  ======== strm_open ========
197  *  Purpose:
198  *      Open a stream for sending/receiving data buffers to/from a task of
199  *      DAIS socket node on the DSP.
200  *  Parameters:
201  *      hnode:          Node handle returned from node_allocate().
202  *      dir:           DSP_TONODE or DSP_FROMNODE.
203  *      index:         Stream index.
204  *      pattr:          Pointer to structure containing attributes to be
205  *                      applied to stream. Cannot be NULL.
206  *      strmres:     Location to store stream resuorce info handle on output.
207  *  Returns:
208  *      0:        Success.
209  *      -EFAULT:    Invalid hnode.
210  *      -EPERM: Invalid direction.
211  *              hnode is not a task or DAIS socket node.
212  *              Unable to open stream.
213  *      -EINVAL:     Invalid index.
214  *  Requires:
215  *      strmres != NULL.
216  *      pattr != NULL.
217  *  Ensures:
218  *      0:        *strmres is valid.
219  *      error:          *strmres == NULL.
220  */
221 extern int strm_open(struct node_object *hnode, u32 dir,
222                             u32 index, struct strm_attr *pattr,
223                             struct strm_res_object **strmres,
224                             struct process_context *pr_ctxt);
225
226 /*
227  *  ======== strm_reclaim ========
228  *  Purpose:
229  *      Request a buffer back from a stream.
230  *  Parameters:
231  *      stream_obj:          Stream handle returned from strm_open().
232  *      buf_ptr:        Location to store pointer to reclaimed buffer.
233  *      nbytes:         Location where number of bytes of data in the
234  *                      buffer will be written.
235  *      buff_size:      Location where actual buffer size will be written.
236  *      pdw_arg:         Location where user argument that travels with
237  *                      the buffer will be written.
238  *  Returns:
239  *      0:        Success.
240  *      -EFAULT:    Invalid stream_obj.
241  *      -ETIME:   A timeout occurred before a buffer could be
242  *                      retrieved.
243  *      -EPERM:      Failure occurred, unable to reclaim buffer.
244  *  Requires:
245  *      buf_ptr != NULL.
246  *      nbytes != NULL.
247  *      pdw_arg != NULL.
248  *  Ensures:
249  */
250 extern int strm_reclaim(struct strm_object *stream_obj,
251                                u8 **buf_ptr, u32 * nbytes,
252                                u32 *buff_size, u32 *pdw_arg);
253
254 /*
255  *  ======== strm_register_notify ========
256  *  Purpose:
257  *      Register to be notified on specific events for this stream.
258  *  Parameters:
259  *      stream_obj:     Stream handle returned by strm_open().
260  *      event_mask:     Mask of types of events to be notified about.
261  *      notify_type:    Type of notification to be sent.
262  *      hnotification:  Handle to be used for notification.
263  *  Returns:
264  *      0:        Success.
265  *      -EFAULT:    Invalid stream_obj.
266  *      -ENOMEM:    Insufficient memory on GPP.
267  *      -EINVAL:     event_mask is invalid.
268  *      -ENOSYS:   Notification type specified by notify_type is not
269  *                      supported.
270  *  Requires:
271  *      hnotification != NULL.
272  *  Ensures:
273  */
274 extern int strm_register_notify(struct strm_object *stream_obj,
275                                        u32 event_mask, u32 notify_type,
276                                        struct dsp_notification
277                                        *hnotification);
278
279 /*
280  *  ======== strm_select ========
281  *  Purpose:
282  *      Select a ready stream.
283  *  Parameters:
284  *      strm_tab:       Array of stream handles returned from strm_open().
285  *      strms:          Number of stream handles in array.
286  *      pmask:          Location to store mask of ready streams on output.
287  *      utimeout:       Timeout value (milliseconds).
288  *  Returns:
289  *      0:        Success.
290  *      -EDOM:     strms out of range.
291
292  *      -EFAULT:    Invalid stream handle in array.
293  *      -ETIME:   A timeout occurred before a stream became ready.
294  *      -EPERM:      Failure occurred, unable to select a stream.
295  *  Requires:
296  *      strm_tab != NULL.
297  *      strms > 0.
298  *      pmask != NULL.
299  *  Ensures:
300  *      0:        *pmask != 0 || utimeout == 0.
301  *      Error:          *pmask == 0.
302  */
303 extern int strm_select(struct strm_object **strm_tab,
304                               u32 strms, u32 *pmask, u32 utimeout);
305
306 #endif /* STRM_ */