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