Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
strm.h
Go to the documentation of this file.
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 resource 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_ */