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