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_ */ 307