/*
* 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 <dspbridge/dev.h>
#include <dspbridge/strmdefs.h>
#include <dspbridge/proc.h>
/*
* ======== 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_ */
