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 */ 47 extern 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 */ 69 extern 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 */ 93 extern 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 */ 109 extern 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 */ 121 extern 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 */ 140 extern 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_info ======== 146 * Purpose: 147 * Get information about a stream. User's dsp_streaminfo is contained 148 * in stream_info struct. stream_info also contains Bridge private info. 149 * Parameters: 150 * stream_obj: Stream handle returned from strm_open(). 151 * stream_info: Location to store stream info on output. 152 * uSteamInfoSize: Size of user's dsp_streaminfo structure. 153 * Returns: 154 * 0: Success. 155 * -EFAULT: Invalid stream_obj. 156 * -EINVAL: stream_info_size < sizeof(dsp_streaminfo). 157 * -EPERM: Unable to get stream info. 158 * Requires: 159 * strm_init(void) called. 160 * stream_info != NULL. 161 * Ensures: 162 */ 163 extern int strm_get_info(struct strm_object *stream_obj, 164 struct stream_info *stream_info, 165 u32 stream_info_size); 166 167 /* 168 * ======== strm_idle ======== 169 * Purpose: 170 * Idle a stream and optionally flush output data buffers. 171 * If this is an output stream and flush_data is TRUE, all data currently 172 * enqueued will be discarded. 173 * If this is an output stream and flush_data is FALSE, this function 174 * will block until all currently buffered data is output, or the timeout 175 * specified has been reached. 176 * After a successful call to strm_idle(), all buffers can immediately 177 * be reclaimed. 178 * Parameters: 179 * stream_obj: Stream handle returned from strm_open(). 180 * flush_data: If TRUE, discard output buffers. 181 * Returns: 182 * 0: Success. 183 * -EFAULT: Invalid stream_obj. 184 * -ETIME: A timeout occurred before the stream could be idled. 185 * -EPERM: Unable to idle stream. 186 * Requires: 187 * strm_init(void) called. 188 * Ensures: 189 */ 190 extern int strm_idle(struct strm_object *stream_obj, bool flush_data); 191 192 /* 193 * ======== strm_init ======== 194 * Purpose: 195 * Initialize the STRM module. 196 * Parameters: 197 * Returns: 198 * TRUE if initialization succeeded, FALSE otherwise. 199 * Requires: 200 * Ensures: 201 */ 202 extern bool strm_init(void); 203 204 /* 205 * ======== strm_issue ======== 206 * Purpose: 207 * Send a buffer of data to a stream. 208 * Parameters: 209 * stream_obj: Stream handle returned from strm_open(). 210 * pbuf: Pointer to buffer of data to be sent to the stream. 211 * ul_bytes: Number of bytes of data in the buffer. 212 * ul_buf_size: Actual buffer size in bytes. 213 * dw_arg: A user argument that travels with the buffer. 214 * Returns: 215 * 0: Success. 216 * -EFAULT: Invalid stream_obj. 217 * -ENOSR: The stream is full. 218 * -EPERM: Failure occurred, unable to issue buffer. 219 * Requires: 220 * strm_init(void) called. 221 * pbuf != NULL. 222 * Ensures: 223 */ 224 extern int strm_issue(struct strm_object *stream_obj, u8 * pbuf, 225 u32 ul_bytes, u32 ul_buf_size, u32 dw_arg); 226 227 /* 228 * ======== strm_open ======== 229 * Purpose: 230 * Open a stream for sending/receiving data buffers to/from a task of 231 * DAIS socket node on the DSP. 232 * Parameters: 233 * hnode: Node handle returned from node_allocate(). 234 * dir: DSP_TONODE or DSP_FROMNODE. 235 * index: Stream index. 236 * pattr: Pointer to structure containing attributes to be 237 * applied to stream. Cannot be NULL. 238 * strmres: Location to store stream resuorce info handle on output. 239 * Returns: 240 * 0: Success. 241 * -EFAULT: Invalid hnode. 242 * -EPERM: Invalid direction. 243 * hnode is not a task or DAIS socket node. 244 * Unable to open stream. 245 * -EINVAL: Invalid index. 246 * Requires: 247 * strm_init(void) called. 248 * strmres != NULL. 249 * pattr != NULL. 250 * Ensures: 251 * 0: *strmres is valid. 252 * error: *strmres == NULL. 253 */ 254 extern int strm_open(struct node_object *hnode, u32 dir, 255 u32 index, struct strm_attr *pattr, 256 struct strm_res_object **strmres, 257 struct process_context *pr_ctxt); 258 259 /* 260 * ======== strm_reclaim ======== 261 * Purpose: 262 * Request a buffer back from a stream. 263 * Parameters: 264 * stream_obj: Stream handle returned from strm_open(). 265 * buf_ptr: Location to store pointer to reclaimed buffer. 266 * nbytes: Location where number of bytes of data in the 267 * buffer will be written. 268 * buff_size: Location where actual buffer size will be written. 269 * pdw_arg: Location where user argument that travels with 270 * the buffer will be written. 271 * Returns: 272 * 0: Success. 273 * -EFAULT: Invalid stream_obj. 274 * -ETIME: A timeout occurred before a buffer could be 275 * retrieved. 276 * -EPERM: Failure occurred, unable to reclaim buffer. 277 * Requires: 278 * strm_init(void) called. 279 * buf_ptr != NULL. 280 * nbytes != NULL. 281 * pdw_arg != NULL. 282 * Ensures: 283 */ 284 extern int strm_reclaim(struct strm_object *stream_obj, 285 u8 **buf_ptr, u32 * nbytes, 286 u32 *buff_size, u32 *pdw_arg); 287 288 /* 289 * ======== strm_register_notify ======== 290 * Purpose: 291 * Register to be notified on specific events for this stream. 292 * Parameters: 293 * stream_obj: Stream handle returned by strm_open(). 294 * event_mask: Mask of types of events to be notified about. 295 * notify_type: Type of notification to be sent. 296 * hnotification: Handle to be used for notification. 297 * Returns: 298 * 0: Success. 299 * -EFAULT: Invalid stream_obj. 300 * -ENOMEM: Insufficient memory on GPP. 301 * -EINVAL: event_mask is invalid. 302 * -ENOSYS: Notification type specified by notify_type is not 303 * supported. 304 * Requires: 305 * strm_init(void) called. 306 * hnotification != NULL. 307 * Ensures: 308 */ 309 extern int strm_register_notify(struct strm_object *stream_obj, 310 u32 event_mask, u32 notify_type, 311 struct dsp_notification 312 *hnotification); 313 314 /* 315 * ======== strm_select ======== 316 * Purpose: 317 * Select a ready stream. 318 * Parameters: 319 * strm_tab: Array of stream handles returned from strm_open(). 320 * strms: Number of stream handles in array. 321 * pmask: Location to store mask of ready streams on output. 322 * utimeout: Timeout value (milliseconds). 323 * Returns: 324 * 0: Success. 325 * -EDOM: strms out of range. 326 327 * -EFAULT: Invalid stream handle in array. 328 * -ETIME: A timeout occurred before a stream became ready. 329 * -EPERM: Failure occurred, unable to select a stream. 330 * Requires: 331 * strm_init(void) called. 332 * strm_tab != NULL. 333 * strms > 0. 334 * pmask != NULL. 335 * Ensures: 336 * 0: *pmask != 0 || utimeout == 0. 337 * Error: *pmask == 0. 338 */ 339 extern int strm_select(struct strm_object **strm_tab, 340 u32 strms, u32 *pmask, u32 utimeout); 341 342 #endif /* STRM_ */ 343