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

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

Defines
#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.
Functions
Uint32	RingIO_getValidSize (IN RingIO_Handle handle)
	Returns the current valid data size.
Uint32	RingIO_getEmptySize (IN RingIO_Handle handle)
	Returns the current empty buffer size.
Uint32	RingIO_getValidAttrSize (IN RingIO_Handle handle)
	Returns the current valid attribute size.
Uint32	RingIO_getEmptyAttrSize (IN RingIO_Handle handle)
	Returns the current empty attribute buffer size.
Int	RingIO_create (IN Uint32 procId, IN Char name, IN RingIO_Attrs attrs)
	This function creates a RingIO instance in Shared memory using the creation params specified.
Int	RingIO_delete (IN Uint32 procId, IN Char *name)
	This function deletes a RingIO channel.
RingIO_Handle	RingIO_open (IN Char *name, IN RingIO_OpenMode openMode, IN Uint32 flags)
	This function opens a RingIO. 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.
Int	RingIO_close (IN RingIO_Handle handle)
	This function closes a RingIO instance.
Int	RingIO_acquire (IN RingIO_Handle handle, OUT RingIO_BufPtr pData, IN OUT Uint32 pSize)
	This function acquire a data buffer from RingIO. 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 Channel.
Int	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.
Int	RingIO_cancel (IN RingIO_Handle handle)
	Cancel the previous acquire.
Int	RingIO_getvAttribute (IN RingIO_Handle handle, OUT Uint16 type, OUT Uint32 param, IN RingIO_BufPtr vptr, IN OUT Uint32 *pSize)
	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.
Int	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.
Int	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.
Int	RingIO_setNotifier (IN RingIO_Handle handle, IN RingIO_NotifyType notifyType, IN Uint32 notifyWatermark, IN RingIO_NotifyFunc notifyFunc, IN RingIO_NotifyParam pNotifyParam)
	This function sets Notification parameters for the RingIO Client. Both the reader and writer can set their notification mechanism using this function.
Int	RingIO_sendNotify (IN RingIO_Handle handle, IN RingIO_NotifyMsg msg)
	Send a notification to the other client manually.

Define Documentation

#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. ============================================================================

#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. ============================================================================

#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. ============================================================================

Function Documentation

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

Postcondition:: None.

See also:: None. ============================================================================

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. ============================================================================

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. ============================================================================

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. ============================================================================

Int RingIO_create	(	IN Uint32	procId,
		IN Char *	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.

Precondition:: None.

Postcondition:: None.

See also:: None. ============================================================================

Int RingIO_delete	(	IN Uint32	procId,
		IN Char *	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.

Precondition:: None.

Postcondition:: None.

See also:: None. ============================================================================

RingIO_Handle RingIO_open	(	IN Char *	name,
		IN RingIO_OpenMode	openMode,
		IN Uint32	flags
	)

This function opens a RingIO. 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:: None.

Postcondition:: None.

See also:: None. ============================================================================

Int 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.

Precondition:: None.

Postcondition:: None.

See also:: None. ============================================================================

Int RingIO_acquire	(	IN RingIO_Handle	handle,
		OUT RingIO_BufPtr *	pData,
		IN OUT Uint32 *	pSize
	)

This function acquire a data buffer from RingIO. 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 Channel.

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

Function:: RingIO_acquire

Parameters:

handle	Handle to the RingIO Client.
pData	Location to store the pointer to the acquired data buffer.
pSize	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_EBUFWRAP Requested size of data buffer could not be returned. A smaller sized buffer may have been returned, if available. RINGIO_ENOTCONTIGUOUSDATA Valid data is present in the buffer but is not contiguous as data has been copied from top to footer area. RINGIO_EFAILURE General failure.

Precondition:: None.

Postcondition:: None.

See also:: None. ============================================================================

Int 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.

Precondition:: None.

Postcondition:: None.

See also:: None. ============================================================================

Int RingIO_cancel ( IN RingIO_Handle handle )

Cancel the previous acquire.

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

Function:: RingIO_cancel

Parameters:

handle Handle to the RingIO Client.

Returns:: RINGIO_SUCCESS Operation successfully completed. RINGIO_EFAILURE General failure.

Precondition:: None.

Postcondition:: None.

See also:: None. ============================================================================

Int RingIO_getvAttribute	(	IN RingIO_Handle	handle,
		OUT Uint16 *	type,
		OUT Uint32 *	param,
		IN RingIO_BufPtr	vptr,
		IN OUT Uint32 *	pSize
	)

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.
pSize	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.

Precondition:: None.

Postcondition:: None.

See also:: RingIO_getAttribute () ============================================================================

Int 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. RINGIO_EWRONGSTATE Failure to set attribute when data buffer is full with valid data and buffer is wrapped around.

Precondition:: None.

Postcondition:: None.

See also:: RingIO_setAttribute (), RingIO_getvAttribute () ============================================================================

Int 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.

Precondition:: None.

Postcondition:: None.

See also:: None. ============================================================================

Int RingIO_setNotifier	(	IN RingIO_Handle	handle,
		IN RingIO_NotifyType	notifyType,
		IN Uint32	notifyWatermark,
		IN RingIO_NotifyFunc	notifyFunc,
		IN RingIO_NotifyParam	pNotifyParam
	)

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
pNotifyParam	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.

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 ============================================================================

Int 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. ============================================================================

ringio.h File Reference

Defines

Functions

Define Documentation

Function Documentation