drivers/staging/tidspbridge/include/dspbridge/strm.h

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