Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

gpp/inc/ringio.h File Reference

#include <dsplink.h>
#include <ringiodefs.h>

Include dependency graph for gpp/inc/ringio.h:

Go to the source code of this file.

Defines

#define RINGIO_H
#define RingIO_getAcquiredOffset(client)   (((RingIO_Client *) client)->acqStart)
 Returns the current acquire offset for the client.
#define RingIO_getAcquiredSize(client)   (((RingIO_Client *) client)->acqSize)
 Returns the size of buffer currently acquired.
#define RingIO_getWatermark(client)   (((RingIO_Client *) client)->notifyWaterMark)
 Returns the current watermark level specified by the client.
#define RingIO_init(procId)   RINGIO_SUCCESS
 This function initializes the RingIO component. This function has been deprecated and is provided for backward compatibility.
#define RingIO_exit(procId)   RINGIO_SUCCESS
 This function finalizes the RingIO component. This function has been deprecated and is provided for backward compatibility.

Functions

EXPORT_API Uint32 RingIO_getValidSize (IN RingIO_Handle handle)
 Returns the current valid data size.
EXPORT_API Uint32 RingIO_getEmptySize (IN RingIO_Handle handle)
 Returns the current empty buffer size.
EXPORT_API Uint32 RingIO_getValidAttrSize (IN RingIO_Handle handle)
 Returns the current valid attribute size.
EXPORT_API Uint32 RingIO_getEmptyAttrSize (IN RingIO_Handle handle)
 Returns the current empty attribute buffer size.
EXPORT_API DSP_STATUS RingIO_create (IN ProcessorId procId, IN Char8 *name, IN RingIO_Attrs *attrs)
 This function creates a RingIO instance in Shared memory using the creation params specified.
EXPORT_API DSP_STATUS RingIO_delete (IN ProcessorId procId, IN Char8 *name)
 This function deletes a RingIO channel.
EXPORT_API RingIO_Handle RingIO_open (IN Char8 *name, IN RingIO_OpenMode openMode, IN Uint32 flags)
 This function opens a RingIO channel. This function is used to open an RingIO Channel either for reading or writing. Only one reader and one writer can be opened on a RingIO.
EXPORT_API DSP_STATUS RingIO_close (IN RingIO_Handle handle)
 This function closes a RingIO instance.
EXPORT_API DSP_STATUS RingIO_acquire (IN RingIO_Handle handle, OUT RingIO_BufPtr *dataBuf, IN OUT Uint32 *size)
 This function acquires a data buffer from RingIO for reading or writing, depending on the mode in which the client (represented by the handle) has been opened.
EXPORT_API DSP_STATUS RingIO_release (IN RingIO_Handle handle, IN Uint32 size)
 This function releases a data buffer to RingIO. This function releases an acquired buffer or part of it.
EXPORT_API DSP_STATUS RingIO_cancel (IN RingIO_Handle handle)
 This function cancels any data buffers acquired by reader or writer. In the case of writer, all attributes that are set since the first acquire are removed. In the case of reader, all attributes that were obtained since the first acquired are re-instated in the RingIO instance.
EXPORT_API DSP_STATUS RingIO_getvAttribute (IN RingIO_Handle handle, OUT Uint16 *type, OUT Uint32 *param, IN RingIO_BufPtr vptr, IN OUT Uint32 *size)
 This function gets an attribute with a variable-sized payload from the attribute buffer. If an attribute is present, the attribute type, the optional parameter, a pointer to the optional payload and the payload size are returned.
EXPORT_API DSP_STATUS RingIO_setvAttribute (IN RingIO_Handle handle, IN Uint32 offset, IN Uint16 type, IN Uint32 param, IN RingIO_BufPtr pdata, IN Uint32 size)
 This function sets an attribute with a variable sized payload at the offset provided in the acquired data buffer. If the offset is not in the range of the acquired data buffer, the attribute is not set, and an error is returned. One exception to this rule is when no data buffer has been acquired. In this case an attribute is set at the next data buffer offset that can be acquired.
EXPORT_API DSP_STATUS RingIO_getAttribute (IN RingIO_Handle handle, OUT Uint16 *type, OUT Uint32 *param)
 This function gets a fixed-size attribute from the attribute buffer. If an attribute is present, the attribute type and a related parameter are returned.
EXPORT_API DSP_STATUS RingIO_setAttribute (IN RingIO_Handle handle, IN Uint32 offset, IN Uint16 type, IN Uint32 param)
 This function sets a fixed-size attribute at the offset provided in the acquired data buffer. If the offset is not in the range of the acquired data buffer, the attribute is not set, and an error is returned. One exception to this rule is when no data buffer has been acquired. In this case an attribute is set at the next data buffer offset that can be acquired.
EXPORT_API DSP_STATUS RingIO_flush (IN RingIO_Handle handle, IN Bool hardFlush, OUT Uint16 *type, OUT Uint32 *param, OUT Uint32 *bytesFlushed)
 This function flushes the data buffer. This function is used to flush the data from the RingIO. Behavior of this function depends on the value of hardFlush argument When hardFlush is false: If function is called for the writer, all the valid data in buffer after the first attribute location will be discarded. In case there are no attributes, no data will be cleared from the buffer. Note that this does not include the data that has been already acquired by the reader. Note that the attribute will also be cleared from the attribute buffer. For the reader, all the data till the next attribute location will be discarded. And if there is no attribute in the buffer, all valid data will get discarded. Note that the attribute will remain the attribute buffer. This is different from the behavior mentioned for the writer. When hardFlush is true: If function is called from the writer, all committed data and attributes that is not acquired by reader are removed from the RingIO instance. The writer pointer is moved to point to reader's head pointer If function is called from the reader, all data and attributes that can be subsequently acquired from the reader are removed.
EXPORT_API DSP_STATUS RingIO_setNotifier (IN RingIO_Handle handle, IN RingIO_NotifyType notifyType, IN Uint32 notifyWatermark, IN RingIO_NotifyFunc notifyFunc, IN RingIO_NotifyParam notifyParam)
 This function sets Notification parameters for the RingIO Client. Both the reader and writer can set their notification mechanism using this function.
EXPORT_API DSP_STATUS RingIO_sendNotify (IN RingIO_Handle handle, IN RingIO_NotifyMsg msg)
 Send a notification to the other client manually.


Define Documentation

#define RingIO_exit procId   )     RINGIO_SUCCESS
 

This function finalizes the RingIO component. This function has been deprecated and is provided for backward compatibility.

============================================================================

Deprecated:
RingIO_exit

Parameters:
procId Processor Id
Returns:
RINGIO_SUCCESS Operation successfully completed.
Precondition:
None.
Postcondition:
None.
See also:
None. ============================================================================

Definition at line 246 of file gpp/inc/ringio.h.

#define RingIO_getAcquiredOffset client   )     (((RingIO_Client *) client)->acqStart)
 

Returns the current acquire offset for the client.

============================================================================

Function:
RingIO_getAcquiredOffset
Parameters:
handle Handle to the RingIO Client.
Returns:
<client's current acquired offset>
Precondition:
client must be a valid pointer(i.e valid RingIO Handle).
Postcondition:
None.
See also:
None. ============================================================================

Definition at line 159 of file gpp/inc/ringio.h.

#define RingIO_getAcquiredSize client   )     (((RingIO_Client *) client)->acqSize)
 

Returns the size of buffer currently acquired.

============================================================================

Function:
RingIO_getAcquiredSize
Parameters:
handle Handle to the RingIO Client.
Returns:
<current acquired="" buffer="" size>="">
Precondition:
client must be a valid pointer(i.e valid RingIO Handle).
Postcondition:
None.
See also:
None. ============================================================================

Definition at line 179 of file gpp/inc/ringio.h.

#define RingIO_getWatermark client   )     (((RingIO_Client *) client)->notifyWaterMark)
 

Returns the current watermark level specified by the client.

============================================================================

Function:
RingIO_getWatermark
Parameters:
handle Handle to the RingIO Client.
Returns:
<current watermark="" level="" set="" by="" the="" client>="">
Precondition:
client must be a valid pointer(i.e valid RingIO Handle)
Postcondition:
None.
See also:
None. ============================================================================

Definition at line 199 of file gpp/inc/ringio.h.

#define RINGIO_H
 

Definition at line 45 of file gpp/inc/ringio.h.

#define RingIO_init procId   )     RINGIO_SUCCESS
 

This function initializes the RingIO component. This function has been deprecated and is provided for backward compatibility.

============================================================================

Deprecated:
RingIO_init

Parameters:
procId Processor Id
Returns:
RINGIO_SUCCESS Operation successfully completed.
Precondition:
None.
Postcondition:
None.
See also:
None. ============================================================================

Definition at line 223 of file gpp/inc/ringio.h.


Function Documentation

EXPORT_API DSP_STATUS RingIO_acquire IN RingIO_Handle  handle,
OUT RingIO_BufPtr dataBuf,
IN OUT Uint32 size
 

This function acquires a data buffer from RingIO for reading or writing, depending on the mode in which the client (represented by the handle) has been opened.

============================================================================

Function:
RingIO_acquire
Parameters:
handle Handle to the RingIO Client.
dataBuf Location to store the pointer to the acquired data buffer.
size Pointer to the size of data buffer acquired. Holds the size of buffer to be acquired. Returns the size of buffer actually acquired.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_SPENDINGATTRIBUTE No data buffer could be acquired because an attribute was present at the current read offset. RINGIO_EBUFFULL Requested size of data buffer could not be returned because the total available size is less than requested size. A smaller sized buffer may have been returned, if available. RINGIO_EBUFWRAP Requested size of data buffer could not be returned because the available contiguous size till end of buffer is less than requested size. A smaller sized buffer may have been returned, if available. RINGIO_EFAILURE General failure. RINGIO_ENOTCONTIGUOUSDATA Valid data is present but is not contiguous because the data has been acquired using the foot buffer.
Precondition:
handle must be valid. dataBuf must be a valid pointer. size must be a valid pointer. RINGIO_open (for reading/writing) has been successful.
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API DSP_STATUS RingIO_cancel IN RingIO_Handle  handle  ) 
 

This function cancels any data buffers acquired by reader or writer. In the case of writer, all attributes that are set since the first acquire are removed. In the case of reader, all attributes that were obtained since the first acquired are re-instated in the RingIO instance.

============================================================================

Function:
RingIO_cancel
Parameters:
handle Handle to the RingIO Client.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure.
Precondition:
handle must be valid. RINGIO_acquire has been successful.
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API DSP_STATUS RingIO_close IN RingIO_Handle  handle  ) 
 

This function closes a RingIO instance.

============================================================================

Function:
RingIO_close
Parameters:
handle Handle to the RingIO Client.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure. DSP_EINVALIDARG Invalid arguments. DSP_EACCESSDENIED The RINGIO component has not been initialized. DSP_EFAIL General failure.
Precondition:
handle must be valid. All RINGIO operations are complete.
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API DSP_STATUS RingIO_create IN ProcessorId  procId,
IN Char8 name,
IN RingIO_Attrs attrs
 

This function creates a RingIO instance in Shared memory using the creation params specified.

============================================================================

Function:
RingIO_create
Parameters:
procId Processor Identifier (Not available in legacy suuport)
name Unique name identifying the RingIO instance.
attrs Pointer to the RingIO creation attributes.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure. DSP_EINVALIDARG Invalid arguments. DSP_EACCESSDENIED The RINGIO component has not been initialized. DSP_EMEMORY Operation failed due to a memory error. RINGIO_EALREADYEXISTS The specified RINGIO name is already in use. DSP_EFAIL General failure.
Precondition:
RINGIO name must be valid. RINGIO creation attributes must be a valid. PROC_attach has been successful. Application specific POOL configuration is complete.
Postcondition:
None.
See also:
RINGIO_delete. ============================================================================

EXPORT_API DSP_STATUS RingIO_delete IN ProcessorId  procId,
IN Char8 name
 

This function deletes a RingIO channel.

============================================================================

Function:
RingIO_delete
Parameters:
procId Processor Identifier (Not available in legacy suuport)
name Name of the RingIO channel to be deleted.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure. DSP_EALREADYEXISTS The specified RINGIO name is already in use. DSP_EACCESSDENIED The RINGIO component has not been initialized. DSP_EFAIL General failure.
Precondition:
RINGIO name must be valid. All RINGIO operations are complete.
Postcondition:
None.
See also:
RINGIO_create. ============================================================================

EXPORT_API DSP_STATUS RingIO_flush IN RingIO_Handle  handle,
IN Bool  hardFlush,
OUT Uint16 type,
OUT Uint32 param,
OUT Uint32 bytesFlushed
 

This function flushes the data buffer. This function is used to flush the data from the RingIO. Behavior of this function depends on the value of hardFlush argument When hardFlush is false: If function is called for the writer, all the valid data in buffer after the first attribute location will be discarded. In case there are no attributes, no data will be cleared from the buffer. Note that this does not include the data that has been already acquired by the reader. Note that the attribute will also be cleared from the attribute buffer. For the reader, all the data till the next attribute location will be discarded. And if there is no attribute in the buffer, all valid data will get discarded. Note that the attribute will remain the attribute buffer. This is different from the behavior mentioned for the writer. When hardFlush is true: If function is called from the writer, all committed data and attributes that is not acquired by reader are removed from the RingIO instance. The writer pointer is moved to point to reader's head pointer If function is called from the reader, all data and attributes that can be subsequently acquired from the reader are removed.

============================================================================

Function:
RingIO_flush
Parameters:
handle Handle to the RingIO Client.
hardFlush Mode in which the flush operation discards committed data and attributes
type Location to receive the User-defined type of attribute.
param Location to receive an optional parameter which depends on the attribute type.
bytesFlushed Location to recieve the size of the buffer flushed.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure. DSP_EINVALIDARG Invalid arguments.
Precondition:
handle must be a valid pointer. type must be valid. param must be valid.
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API DSP_STATUS RingIO_getAttribute IN RingIO_Handle  handle,
OUT Uint16 type,
OUT Uint32 param
 

This function gets a fixed-size attribute from the attribute buffer. If an attribute is present, the attribute type and a related parameter are returned.

============================================================================

Function:
RingIO_getAttribute
Parameters:
handle Handle to the RingIO Client.
type Location to receive the user-defined type of attribute.
param Location to receive an optional parameter which depends on the attribute type.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_SPENDINGATTRIBUTE Additional attributes are present at the current read offset. RINGIO_EVARIABLEATTRIBUTE A variable atrtibute exists. The application must call RingIO_getvAttribute () to get the variable attribute. RINGIO_EPENDINGDATA More data must be read before reading the attribute. RINGIO_EFAILURE No valid attributes are present, or general failure.
Precondition:
handle must be a valid pointer. type must be valid. param must be valid. RingIO_setAttribute has been successful.
Postcondition:
None.
See also:
RingIO_getvAttribute () ============================================================================

EXPORT_API Uint32 RingIO_getEmptyAttrSize IN RingIO_Handle  handle  ) 
 

Returns the current empty attribute buffer size.

============================================================================

Function:
RingIO_getEmptyAttrSize
Parameters:
handle Handle to the RingIO Client.
Returns:
<current empty="" attribute="" buffer="" size>="">
Precondition:
client must be a valid pointer(i.e valid RingIO Handle).
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API Uint32 RingIO_getEmptySize IN RingIO_Handle  handle  ) 
 

Returns the current empty buffer size.

============================================================================

Function:
RingIO_getEmptySize
Parameters:
handle Handle to the RingIO Client.
Returns:
<current empty="" buffer="" size>="">
Precondition:
client must be a valid pointer(i.e valid RingIO Handle).
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API Uint32 RingIO_getValidAttrSize IN RingIO_Handle  handle  ) 
 

Returns the current valid attribute size.

============================================================================

Function:
RingIO_getValidAttrSize
Parameters:
handle Handle to the RingIO Client.
Returns:
<current valid="" attribute="" size>="">
Precondition:
client must be a valid pointer(i.e valid RingIO Handle).
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API Uint32 RingIO_getValidSize IN RingIO_Handle  handle  ) 
 

Returns the current valid data size.

============================================================================

Function:
RingIO_getValidSize
Parameters:
handle Handle to the RingIO Client.
Returns:
<current valid="" data="" size>="">
Precondition:
client must be a valid pointer(i.e valid RingIO Handle).
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API DSP_STATUS RingIO_getvAttribute IN RingIO_Handle  handle,
OUT Uint16 type,
OUT Uint32 param,
IN RingIO_BufPtr  vptr,
IN OUT Uint32 size
 

This function gets an attribute with a variable-sized payload from the attribute buffer. If an attribute is present, the attribute type, the optional parameter, a pointer to the optional payload and the payload size are returned.

============================================================================

Function:
RingIO_getvAttribute
Parameters:
handle Handle to the RingIO Client.
type Location to receive the user-defined type of attribute.
param Location to receive an optional parameter which depends on the attribute type.
vptr Pointer to buffer to receive the optional payload.
size Location with the size of the variable attribute. On return, this stores the actual size of the payload.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_SPENDINGATTRIBUTE Additional attributes are present at the current read offset. RINGIO_EVARIABLEATTRIBUTE No buffer has been provided to receive the variable attribute payload. RINGIO_EPENDINGDATA More data must be read before reading the attribute. RINGIO_EFAILURE No valid attributes are present, or general failure. DSP_EINVALIDARG Invalid arguments.
Precondition:
handle must be a valid pointer. type must be valid. param must be valid. RingIO_setvAttribute has been successful.
Postcondition:
None.
See also:
RingIO_getAttribute () ============================================================================

EXPORT_API RingIO_Handle RingIO_open IN Char8 name,
IN RingIO_OpenMode  openMode,
IN Uint32  flags
 

This function opens a RingIO channel. This function is used to open an RingIO Channel either for reading or writing. Only one reader and one writer can be opened on a RingIO.

============================================================================

Function:
RingIO_open
Parameters:
name Name of the RingIO channel to be opened.
openMode Mode with which the RingIO channel is to be opened (Reader/Writer).
flags Cache usage and other notifification flags.
Returns:
Handle to the RingIO client structure. Operation successfully completed. NULL General failure, name not found.
Precondition:
RINGIO name must be valid. openMode must be either RINGIO_MODE_READ or RINGIO_MODE_WRITE RINGIO_create has been successful.
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API DSP_STATUS RingIO_release IN RingIO_Handle  handle,
IN Uint32  size
 

This function releases a data buffer to RingIO. This function releases an acquired buffer or part of it.

============================================================================

Function:
RingIO_release
Parameters:
handle Handle to the RingIO Client.
size Size of data buffer to be released.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure. DSP_EINVALIDARG Invalid arguments.
Precondition:
RINGIO_acquire has been successful.
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API DSP_STATUS RingIO_sendNotify IN RingIO_Handle  handle,
IN RingIO_NotifyMsg  msg
 

Send a notification to the other client manually.

============================================================================

Function:
RingIO_sendNotify
Parameters:
handle Handle to the RingIO Client. arg msg Message to be sent along with notification.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure.
Precondition:
None.
Postcondition:
None.
See also:
None. ============================================================================

EXPORT_API DSP_STATUS RingIO_setAttribute IN RingIO_Handle  handle,
IN Uint32  offset,
IN Uint16  type,
IN Uint32  param
 

This function sets a fixed-size attribute at the offset provided in the acquired data buffer. If the offset is not in the range of the acquired data buffer, the attribute is not set, and an error is returned. One exception to this rule is when no data buffer has been acquired. In this case an attribute is set at the next data buffer offset that can be acquired.

============================================================================

Function:
RingIO_setAttribute
Parameters:
handle Handle to the RingIO Client.
offset Offset in the acquired data buffer to which the attribute corresponds
type User-defined type of attribute.
param Optional parameter which depends on the attribute type.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure. DSP_EINVALIDARG Invalid arguments.
Precondition:
handle must be valid.
Postcondition:
None.
See also:
RingIO_setvAttribute (), RingIO_getAttribute () ============================================================================

EXPORT_API DSP_STATUS RingIO_setNotifier IN RingIO_Handle  handle,
IN RingIO_NotifyType  notifyType,
IN Uint32  notifyWatermark,
IN RingIO_NotifyFunc  notifyFunc,
IN RingIO_NotifyParam  notifyParam
 

This function sets Notification parameters for the RingIO Client. Both the reader and writer can set their notification mechanism using this function.

============================================================================

Function:
RingIO_setNotifier
Parameters:
handle Handle to the RingIO client.
notifyType Type of notification.
notifyWatermark Watermark for notification
notifyFunc Function to call when notification is required
notifyParam Pointer to the notification parameter. The type of the pointer and its size depends on the notification function
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure. DSP_EINVALIDARG Invalid arguments.
Precondition:
RingIO_open for both reader and writer has been successful. No DSP/BIOS Link API should be called from a callback function registered through the RingIO or NOTIFY module. On DSP-side or on operating systems such as PrOS, the callback functions are run from ISR context and must not perform any operations that may take a lock or block, which is done by most DSPLink APIs. Minimum functionality must be used in the callback functions, most often limited to posting a semaphore on which application is waiting, posting SWI etc.
Postcondition:
None.
See also:
RingIO_NotifyType, RingIO_NotifyFunc, RingIO_NotifyParam ============================================================================

EXPORT_API DSP_STATUS RingIO_setvAttribute IN RingIO_Handle  handle,
IN Uint32  offset,
IN Uint16  type,
IN Uint32  param,
IN RingIO_BufPtr  pdata,
IN Uint32  size
 

This function sets an attribute with a variable sized payload at the offset provided in the acquired data buffer. If the offset is not in the range of the acquired data buffer, the attribute is not set, and an error is returned. One exception to this rule is when no data buffer has been acquired. In this case an attribute is set at the next data buffer offset that can be acquired.

============================================================================

Function:
RingIO_setvAttribute
Parameters:
handle Handle to the RingIO Client.
offset Offset in the acquired data buffer to which the attribute corresponds
type User-defined type of attribute.
param Optional parameter which depends on the attribute type.
pdata Pointer to attribute payload buffer.
size Size of the attribute payload.
Returns:
RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure. DSP_EINVALIDARG Invalid arguments. RINGIO_EWRONGSTATE Failure to set attribute when data buffer is full with valid data and buffer is wrapped around.
Precondition:
handle must be a valid pointer.
Postcondition:
None.
See also:
RingIO_setAttribute (), RingIO_getvAttribute () ============================================================================


Generated on Fri Jul 16 14:34:09 2010 for DSP/BIOSLink by  doxygen 1.4.4