/* * 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 #include #include /* * ======== strm_allocate_buffer ======== * Purpose: * Allocate data buffer(s) for use with a stream. * Parameter: * strmres: Stream resource info 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_res_object *strmres, u32 usize, u8 **ap_buffer, u32 num_bufs, struct process_context *pr_ctxt); /* * ======== strm_close ======== * Purpose: * Close a stream opened with strm_open(). * Parameter: * strmres: Stream resource info 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_res_object *strmres, 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: * strmres: Stream resource info 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_res_object *strmres, u8 **ap_buffer, u32 num_bufs, struct process_context *pr_ctxt); /* * ======== 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. * strmres: Location to store stream resuorce info 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. * strmres != NULL. * pattr != NULL. * Ensures: * 0: *strmres is valid. * error: *strmres == NULL. */ extern int strm_open(struct node_object *hnode, u32 dir, u32 index, struct strm_attr *pattr, struct strm_res_object **strmres, struct process_context *pr_ctxt); /* * ======== 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); #endif /* STRM_ */