Detailed Description

This will have definitions for interfaces and structures for RingIO module.

The RingIO component provides data streaming between GPP and DSP using ring buffer data as the transport.

In a multiprocessor system having shared access to a memory region, an efficient mode of data transfer can be implemented, which uses a ring buffer created within the shared memory. The reader and writer of the ring buffer can be on different processors.

The RingIO component on each processor shall provide the ability to create RingIO buffers within the memory provided by the application. The memory provided may be within the shared memory region between two processors. If the RingIO buffer is created within shared memory, it shall be accessible to reader and writer present on the two processors between which the memory is shared. The application can obtain a handle to the RingIO through a call to open it.

The RingIO component shall provide the ability for the writer to acquire empty regions of memory within the data buffer. The contents of the acquired region are committed to memory when the data buffer is released by the writer.

The RingIO component shall provide the ability for the reader to acquire regions of memory within the data buffer with valid data within them. On releasing the acquired region, the contents of this region are marked as invalid.

The RingIO component shall also support APIs for enabling synchronous transfer of attributes with data. End of Stream (EOS), Time Stamps, Stream offset etc. are examples of such attributes and these shall be associated with offsets in the ring buffer.

A client using RingIO is a single unit of execution. It may be a process or thread on the GPP or the DSP.

The RingIO instance can be created between a client on the ARM and a client on the DSP or between two DSP clients.

Either the reader or writer can create or delete the RingIO instance.

The RingIO instance should be created in a shared memory region which can be accessed directly by both the reader and the writer.

Both the reader and the writer need to open the RingIO instance and get a handle. Any data access on the RingIO instance should be made using these handles.

Each RingIO can have a single writer client and a single reader client. A RingIO handle may not be shared between multiple clients on the GPP or DSP.

The RingIO client can be closed only if there is no currently acquired data or attributes. If there is any unreleased data or attributes, they must be released or cancelled before the RingIO client can be closed.

The RingIO can be deleted only when both reader and writer clients have successfully closed their RingIO clients.

Each RingIO instance has an associated footer area, if configured. The foot buffer can be configured to be of zero size if not required. If configured, the foot-buffer is physically contiguous with the data buffer, and hence the memory size specified must be equal to (data buffer size + foot buffer size).

The RingIO data and attribute buffer sizes must comply with any constraints imposed by the heap that they are specified to be allocated from. For example, for the Shared Memory Heap, the buffer sizes must be aligned to DSP cache line.

#include <ti/syslink/SysLink.h>

Include dependency graph for RingIO.h:

Go to the source code of this file.

Data Structures
struct	RingIO_Config_Tag
	Structure defining config parameters for the RingIO module. More...
struct	RingIO_Params_Tag
	Common parameters required to create RingIO instance of any implementation. It should be the first element of the actual implementaton params structure . More...
struct	RingIO_openParams_Tag
	Structure defining config parameters for opening the RingIO instances. More...
struct	RingIO_sharedMemReqDetails_tag
	Structure defining config parameters for opening the RingIO instances. More...
Defines
#define	RingIO_S_PENDINGATTRIBUTE 4
	Indicates that either: 1) The amount of data requested could not be serviced due to the presence of an attribute 2) During an attribute read if another is also present at the same offset.
#define	RingIO_S_NOTCONTIGUOUSDATA 3
	Indicates that Valid data is present in the buffer but is not contiguous as data has been copied from top to footer area.
#define	RingIO_S_BUSY 2
	The resource is still in use.
#define	RingIO_S_ALREADYSETUP 1
	The module has been already setup.
#define	RingIO_S_SUCCESS 0
	Operation is successful.
#define	RingIO_E_FAIL -1
	Operation is not successful.
#define	RingIO_E_INVALIDARG -2
	There is an invalid argument.
#define	RingIO_E_MEMORY -3
	Operation resulted in memory failure.
#define	RingIO_E_ALREADYEXISTS -4
	The specified entity already exists.
#define	RingIO_E_NOTFOUND -5
	Unable to find the specified entity.
#define	RingIO_E_TIMEOUT -6
	Operation timed out.
#define	RingIO_E_INVALIDSTATE -7
	Module is not initialized.
#define	RingIO_E_OSFAILURE -8
	A failure occurred in an OS-specific call.
#define	RingIO_E_RESOURCE -9
	Specified resource is not available.
#define	RingIO_E_RESTART -10
	Operation was interrupted. Please restart the operation.
#define	RingIO_E_INVALIDMSG -11
	Operation is successful.
#define	RingIO_E_NOTOWNER -12
	Not the owner.
#define	RingIO_E_REMOTEACTIVE -13
	Operation is successful.
#define	RingIO_E_INVALIDHEAPID -14
	Operation is successful.
#define	RingIO_E_INVALIDPROCID -15
	Operation is successful.
#define	RingIO_E_MAXREACHED -16
	Operation is successful.
#define	RingIO_E_INUSE -17
	Indicates that the instance is in use..
#define	RingIO_E_INVALIDCONTEXT -18
	Indicates that the api is called with wrong handle.
#define	RingIO_E_BADVERSION -19
	Versions don't match.
#define	RingIO_E_BUFWRAP -20
	Indicates that the amount of data requested could not be serviced due to the ring buffer getting wrapped.
#define	RingIO_E_BUFEMPTY -21
	Indicates that there is no data in the buffer for reading.
#define	RingIO_E_BUFFULL -22
	Indicates that the buffer is full.
#define	RingIO_E_PENDINGDATA -23
	Indicates that there is no attribute at the current, but attributes are present at a future offset.
#define	RingIO_E_VARIABLEATTRIBUTE -24
	Indicates that attibute get() failed, need to extract variable length message getv()
#define	RingIO_E_WRONGSTATE -25
	Indicates that the RingIO is in a wrong state.
#define	RingIO_E_NOTIFYFAIL -26
	Indicates that the the underlying notification call failed.
#define	RingIO_E_PENDINGATTRIBUTE -27
	Indicates that the the acquire failed as attribute is present at current read offset.
Typedefs
typedef Ptr	RingIO_BufPtr
typedef UInt16	RingIO_NotifyMsg
typedef struct RingIO_Object *	RingIO_Handle
	Handle for the RingIO instance.
typedef enum RingIO_Type_Tag	RingIO_Type
typedef struct RingIO_Config_Tag	RingIO_Config
	Structure defining config parameters for the RingIO module.
typedef struct RingIO_Params_Tag	RingIO_Params
	Common parameters required to create RingIO instance of any implementation. It should be the first element of the actual implementaton params structure .
typedef enum RingIO_OpenMode_Tag	RingIO_OpenMode
	Enumeration of RingIO open modes.
typedef struct RingIO_openParams_Tag	RingIO_openParams
	Structure defining config parameters for opening the RingIO instances.
typedef struct RingIO_sharedMemReqDetails_tag	RingIO_sharedMemReqDetails
	Structure defining config parameters for opening the RingIO instances.
typedef enum RingIO_Flags_tag	RingIO_Flags
	Enumeration of flags for RingIO client. It includes information about access to buffers.
typedef enum RingIO_NotifyType_Tag	RingIO_NotifyType
	Enumerates the notification types for RingIO.
typedef void(*	RingIO_NotifyFxn )(RingIO_Handle, Ptr, RingIO_NotifyMsg)
	Prototype of the RingIO call back function.
Enumerations
enum	RingIO_Type_Tag { RingIO_Type_SHAREDMEM = 0x0 }
enum	RingIO_OpenMode_Tag { RingIO_MODE_READER = 0x0, RingIO_MODE_WRITER = 0x1 }
	Enumeration of RingIO open modes. More...
enum	RingIO_Flags_tag { RingIO_DATABUF_MAINTAINCACHE = 0x1, RingIO_NEED_EXACT_SIZE = 0x2 }
	Enumeration of flags for RingIO client. It includes information about access to buffers. More...
enum	RingIO_NotifyType_Tag { RingIO_NOTIFICATION_NONE = SysLink_NOTIFICATION_NONE, RingIO_NOTIFICATION_ALWAYS = SysLink_NOTIFICATION_ALWAYS, RingIO_NOTIFICATION_ONCE = SysLink_NOTIFICATION_ONCE, RingIO_NOTIFICATION_HDWRFIFO_ALWAYS, RingIO_NOTIFICATION_HDWRFIFO_ONCE }
	Enumerates the notification types for RingIO. More...
Functions
Void	RingIO_Params_init (Void *params)
	Function to initialize the parameters for the RingIO instance.
RingIO_Handle	RingIO_create (const Void *params)
	Create a RingIO object.
Int	RingIO_delete (RingIO_Handle *handlePtr)
	Delete a RingIO object.
UInt32	RingIO_sharedMemReq (const Void params, RingIO_sharedMemReqDetails sharedMemReqDetails)
	Get shared memory requirements. Params_init must be called to initialize the parameters before calling this function.
Int	RingIO_open (String name, const RingIO_openParams params, UInt16 procIds, RingIO_Handle *handlePtr)
	Opens a created instance of RingIO module.
Int	RingIO_openByAddr (Ptr ctrlSharedAddr, const RingIO_openParams params, RingIO_Handle handlePtr)
	Opens a created instance of RingIO module by the shared memory address of the instance.
Int	RingIO_close (RingIO_Handle *handlePtr)
	Closes previously opened/created instance of RingIO module.
Int	RingIO_registerNotifier (RingIO_Handle handle, RingIO_NotifyType notifyType, UInt32 watermark, RingIO_NotifyFxn notifyFunc, Ptr cbContext)
	Function to register a call back function.
Int	RingIO_unregisterNotifier (RingIO_Handle handle)
	Function to un-register call back function.
Int	RingIO_setWaterMark (RingIO_Handle handle, UInt32 watermark)
	Function to set client's watermark.
Int	RingIO_setNotifyType (RingIO_Handle handle, RingIO_NotifyType notifyType)
	Function to set the notify type.
Int	RingIO_acquire (RingIO_Handle handle, RingIO_BufPtr pData, UInt32 pSize)
	Acquires data from the RingIO instance 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.
Int	RingIO_release (RingIO_Handle handle, UInt32 size)
	Releases data from the RingIO instance.
Int	RingIO_cancel (RingIO_Handle handle)
	Cancel the previous acquired buffer to the RingIO instance 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.
Int	RingIO_getvAttribute (RingIO_Handle handle, UInt16 type, UInt32 param, RingIO_BufPtr vptr, UInt32 *pSize)
	Get attribute from the RingIO instance 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 (RingIO_Handle handle, UInt16 type, UInt32 param, RingIO_BufPtr pData, UInt32 size, Bool sendNotification)
	Set attribute in the RingIO instance 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_getAttribute (RingIO_Handle handle, UInt16 type, 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.
Int	RingIO_setAttribute (RingIO_Handle handle, UInt16 type, UInt32 param, Bool sendNotification)
	This function sets a fixed-size attribute at the offset provided in the acquired data buffer. 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.
Int	RingIO_flush (RingIO_Handle handle, Bool hardFlush, UInt16 type, UInt32 param, UInt32 *bytesFlushed)
	Flush the buffer in the RingIO instance.
Int	RingIO_sendNotify (RingIO_Handle handle, RingIO_NotifyMsg msg)
	Send a force notification to the other client manually.
UInt	RingIO_getValidSize (RingIO_Handle handle)
	Function to get valid data buffer size.
UInt	RingIO_getEmptySize (RingIO_Handle handle)
	Function to get empty data buffer size.
UInt	RingIO_getValidAttrSize (RingIO_Handle handle)
	Function to get valid attribute size.
UInt	RingIO_getEmptyAttrSize (RingIO_Handle handle)
	Function to get empty attribute size.
UInt	RingIO_getAcquiredOffset (RingIO_Handle handle)
	Function to get client's acquired offset.
UInt	RingIO_getAcquiredSize (RingIO_Handle handle)
	Function to get client's acquired size.
UInt	RingIO_getWaterMark (RingIO_Handle handle)
	Function to get client's watermark.
Void	RingIO_getConfig (RingIO_Config *cfgParams)
	Function to get the default configuration for the RingIO module.
Int	RingIO_setup (const RingIO_Config *cfgParams)
	Function to setup the RingIO module.
Int	RingIO_destroy (Void)
	Function to destroy the RingIO module.

Define Documentation

#define RingIO_S_PENDINGATTRIBUTE 4

Indicates that either: 1) The amount of data requested could not be serviced due to the presence of an attribute 2) During an attribute read if another is also present at the same offset.

#define RingIO_S_NOTCONTIGUOUSDATA 3

Indicates that Valid data is present in the buffer but is not contiguous as data has been copied from top to footer area.

#define RingIO_S_BUSY 2

The resource is still in use.

#define RingIO_S_ALREADYSETUP 1

The module has been already setup.

#define RingIO_S_SUCCESS 0

Operation is successful.

#define RingIO_E_FAIL -1

Operation is not successful.

#define RingIO_E_INVALIDARG -2

There is an invalid argument.

#define RingIO_E_MEMORY -3

Operation resulted in memory failure.

#define RingIO_E_ALREADYEXISTS -4

The specified entity already exists.

#define RingIO_E_NOTFOUND -5

Unable to find the specified entity.

#define RingIO_E_TIMEOUT -6

Operation timed out.

#define RingIO_E_INVALIDSTATE -7

Module is not initialized.

#define RingIO_E_OSFAILURE -8

A failure occurred in an OS-specific call.

#define RingIO_E_RESOURCE -9

Specified resource is not available.

#define RingIO_E_RESTART -10

Operation was interrupted. Please restart the operation.

#define RingIO_E_INVALIDMSG -11

Operation is successful.

#define RingIO_E_NOTOWNER -12

Not the owner.

#define RingIO_E_REMOTEACTIVE -13

Operation is successful.

#define RingIO_E_INVALIDHEAPID -14

Operation is successful.

#define RingIO_E_INVALIDPROCID -15

Operation is successful.

#define RingIO_E_MAXREACHED -16

Operation is successful.

#define RingIO_E_INUSE -17

Indicates that the instance is in use..

#define RingIO_E_INVALIDCONTEXT -18

Indicates that the api is called with wrong handle.

#define RingIO_E_BADVERSION -19

Versions don't match.

#define RingIO_E_BUFWRAP -20

Indicates that the amount of data requested could not be serviced due to the ring buffer getting wrapped.

#define RingIO_E_BUFEMPTY -21

Indicates that there is no data in the buffer for reading.

#define RingIO_E_BUFFULL -22

Indicates that the buffer is full.

#define RingIO_E_PENDINGDATA -23

Indicates that there is no attribute at the current, but attributes are present at a future offset.

#define RingIO_E_VARIABLEATTRIBUTE -24

Indicates that attibute get() failed, need to extract variable length message getv()

#define RingIO_E_WRONGSTATE -25

Indicates that the RingIO is in a wrong state.

#define RingIO_E_NOTIFYFAIL -26

Indicates that the the underlying notification call failed.

#define RingIO_E_PENDINGATTRIBUTE -27

Indicates that the the acquire failed as attribute is present at current read offset.

Typedef Documentation

typedef Ptr RingIO_BufPtr

typedef UInt16 RingIO_NotifyMsg

typedef struct RingIO_Object* RingIO_Handle

Handle for the RingIO instance.

typedef enum RingIO_Type_Tag RingIO_Type

typedef struct RingIO_Config_Tag RingIO_Config

Structure defining config parameters for the RingIO module.

typedef struct RingIO_Params_Tag RingIO_Params

Common parameters required to create RingIO instance of any implementation. It should be the first element of the actual implementaton params structure .

typedef enum RingIO_OpenMode_Tag RingIO_OpenMode

Enumeration of RingIO open modes.

typedef struct RingIO_openParams_Tag RingIO_openParams

Structure defining config parameters for opening the RingIO instances.

typedef struct RingIO_sharedMemReqDetails_tag RingIO_sharedMemReqDetails

Structure defining config parameters for opening the RingIO instances.

typedef enum RingIO_Flags_tag RingIO_Flags

Enumeration of flags for RingIO client. It includes information about access to buffers.

typedef enum RingIO_NotifyType_Tag RingIO_NotifyType

Enumerates the notification types for RingIO.

typedef void(* RingIO_NotifyFxn)(RingIO_Handle, Ptr, RingIO_NotifyMsg)

Prototype of the RingIO call back function.

Parameters:

RingIO_Handle Pointer to the RingIO instance structure in which the default params is to be returned. Ptr Argument to callback function e.g. handle to semaphore to be posted from callback RingIO_NotifyMsg message

Return values:

None

Enumeration Type Documentation

enum RingIO_Type_Tag

Enumerator:

RingIO_Type_SHAREDMEM

interface type for ringio delegate

enum RingIO_OpenMode_Tag

Enumeration of RingIO open modes.

Enumerator:

RingIO_MODE_READER	If specifed in params, open call returns a reader handle.
RingIO_MODE_WRITER	If specifed in params, open call returns a writer handle.

enum RingIO_Flags_tag

Enumeration of flags for RingIO client. It includes information about access to buffers.

Enumerator:

RingIO_DATABUF_MAINTAINCACHE	Denotes whether cache maintenance needs to be performed on the data buffer
RingIO_NEED_EXACT_SIZE	Denotes whether requests for acquire buffer should always be satisfied. If a contiguous request could not be satisfied because of the buffer wrap, we need to mark an early end and provide only a contiguous buffer

enum RingIO_NotifyType_Tag

Enumerates the notification types for RingIO.

Enumerator:

RingIO_NOTIFICATION_NONE	No notification is required.
RingIO_NOTIFICATION_ALWAYS	Notify whenever the other client sends data/frees up space.
RingIO_NOTIFICATION_ONCE	Notify when the other side sends data/frees up space. Once the notification is done, the notification is disabled until it is enabled again.
RingIO_NOTIFICATION_HDWRFIFO_ALWAYS	Notify whenever the other side sends data/frees up space. This notification is never disabled.
RingIO_NOTIFICATION_HDWRFIFO_ONCE	Notify when the other side sends data/frees up space. Once the notification is done, the notification is disabled until it is enabled again. The notification is enabled once the watermark is crossed and does not require buffer to get full/empty.

Function Documentation

Void RingIO_Params_init ( Void * params )

Function to initialize the parameters for the RingIO instance.

This function can be called by the application to get their configuration parameter to RingIO_create filled in by the RingIO module with the default parameters.

Parameters:

params Pointer to the RingIO interface type specific params, refer to Interface type specific header file for details on interface type specific params

Return values:

None

See also:: RingIO_create

RingIO_Handle RingIO_create ( const Void * params )

Create a RingIO object.

This function creates an instance of the RingIO module and returns an instance handle, which is used to access the specified RingIO. Instance-level configuration needs to be provided to this function. If the user wishes to change some specific config parameters, then RingIO_Params_init can be called to get the configuration filled with the default values. After this, only the required configuration values can be changed.

Parameters:

params Pointer to the RingIO interface type specific params, refer to Interface type specific header file for details on interface type specific params

Return values:

Valid_handle_of_type_RingIO_Handle	Operation successful
NULL	Operation unsuccessful

See also:: RingIO_delete, RingIO_open, RingIO_close

Int RingIO_delete ( RingIO_Handle * handlePtr )

Delete a RingIO object.

Once this function is called, other RingIO instance level APIs that require the instance handle cannot be called.

Parameters:

handlePtr Pointer to Handle to the RingIO object

Return values:

RingIO_E_INVALIDSTATE	Module is in an invalid state Instance was not created on this processor
RingIO_E_INVALIDARG	handlePtr pointer passed is NULL
RingIO_E_INVALIDARG	*handlePtr passed is NULL
RingIO_S_SUCCESS	Operation Successful

See also:: RingIO_create

UInt32 RingIO_sharedMemReq	(	const Void *	params,
		RingIO_sharedMemReqDetails *	sharedMemReqDetails
	)

Get shared memory requirements. Params_init must be called to initialize the parameters before calling this function.

Parameters:

params	Pointer to the RingIO interface type specific params, refer to Interface type specific header file for details on interface type specific params.
sharedMemReqDetails	Control, Data and Attr shared memory details

Return values:

Shared-memory-requirements Operation successfully completed. The out parameter of sharedMemDetails contains the values for ctrlSharedMemReq : Control shared memory requirements dataSharedMemReq : Data Buffer shared memory requirements attrSharedMemReq : Attribute buffer shared memory requirements

See also:: None

Int RingIO_open	(	String	name,
		const RingIO_openParams *	params,
		UInt16 *	procIds,
		RingIO_Handle *	handlePtr
	)

Opens a created instance of RingIO module.

Parameters:

name	Name of the RingIO instance to be opened
params	Parameters for opening the RingIO instance.
procIds	Array of processor IDs to search for the RingIO instance. If NULL is specified, all processors are checked.
handlePtr	OUT parameter: Holds the RingIO handle on success.

Return values:

RingIO_E_INVALIDSTATE	Module is in an invalid state
RingIO_E_NOTFOUND	RingIO not found
RingIO_E_FAIL	Failed to open the gate associated with the RingIO instance. Failed to open the clientnotifymgr associated with the RingIO instance.
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful

See also:: RingIO_close, RingIO_openParams

Int RingIO_openByAddr	(	Ptr	ctrlSharedAddr,
		const RingIO_openParams *	params,
		RingIO_Handle *	handlePtr
	)

Opens a created instance of RingIO module by the shared memory address of the instance.

Parameters:

ctrlSharedAddr	Shared address at which the instance exists
params	Parameters for opening the RingIO instance.
handlePtr	OUT parameter: Holds the RingIO handle on success.

Return values:

RingIO_E_INVALIDSTATE	Module is in an invalid state
RingIO_E_NOTFOUND	RingIO not found
RingIO_E_FAIL	Failed to open the gate associated with the RingIO instance. Failed to open the clientnotifymgr associated with the RingIO instance.
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful

See also:: RingIO_create, RingIO_delete, RingIO_close

Int RingIO_close ( RingIO_Handle * handlePtr )

Closes previously opened/created instance of RingIO module.

Parameters:

handlePtr Pointer to handle for the opened RingIO instance. Reset to invalid when the function successfully completes.

Return values:

RingIO_E_INVALIDSTATE	Module is in an invalid state
RingIO_E_FAIL	Failed to open the gate associated with the RingIO instance. Failed to open the clientnotifymgr associated with the RingIO instance.
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful

See also:: RingIO_create, RingIO_delete, RingIO_open

Int RingIO_registerNotifier	(	RingIO_Handle	handle,
		RingIO_NotifyType	notifyType,
		UInt32	watermark,
		RingIO_NotifyFxn	notifyFunc,
		Ptr	cbContext
	)

Function to register a call back function.

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

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.

Parameters:

handle	RingIO client Handle.
notifyType	Type of notification.
watermark	WaterMark
notifyFunc	Call back function
cbContext	Context pointer that needs to be passed to call back.

Return values:

RingIO_E_INVALIDSTATE	Module is in an invalid state RingIO_open is not called yet
RingIO_E_FAIL	Failed to open the gate associated with the RingIO instance. Failed to open the clientnotifymgr associated with the RingIO instance.
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful

See also:: None

Int RingIO_unregisterNotifier ( RingIO_Handle handle )

Function to un-register call back function.

Parameters:

handle RingIO client Handle.

Return values:

RingIO_E_INVALIDSTATE	Module is in an invalid state RingIO_open is not called yet
RingIO_E_FAIL	Failed to open the gate associated with the RingIO instance. Failed to open the clientnotifymgr associated with the RingIO instance.
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful

See also:: RingIO_registerNotifier

Int RingIO_setWaterMark	(	RingIO_Handle	handle,
		UInt32	watermark
	)

Function to set client's watermark.

Parameters:

handle	RingIO client Handle.
watermark	Watermark value

Return values:

-1	Operation unsuccessful
watermark	Operation successful

See also:: RingIO_registerNotifier

Int RingIO_setNotifyType	(	RingIO_Handle	handle,
		RingIO_NotifyType	notifyType
	)

Function to set the notify type.

Parameters:

handle	Instance handle.
notifyType	Type of notification

Return values:

RingIO_E_FAIL	Operation unsuccessful
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful

See also:: RingIO_NotifyType, RingIO_registerNotifier

Int RingIO_acquire	(	RingIO_Handle	handle,
		RingIO_BufPtr *	pData,
		UInt32 *	pSize
	)

Acquires data from the RingIO instance 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.

Parameters:

handle	RingIO handle
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.

Return values:

RingIO_S_SUCCESS	Operation successfully completed.
RingIO_E_PENDINGATTRIBUTE	No data buffer could be acquired because an attribute was present at the current read offset.
RingIO_S_PENDINGATTRIBUTE	Flag RingIO_NEED_EXACT_SIZE is set. Partial Data buffer is retuned till the offset where an attribute was present/
RingIO_E_BUFFULL	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_E_BUFWRAP	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_E_FAIL	General failure. Contiguous buffer requirement cannot be satisfied even by setting early end.
RingIO_S_NOTCONTIGUOUSDATA	Valid data is present but is not contiguous because the data has been acquired using the foot buffer.
RingIO_E_BUFEMPTY	No data available to acquire
RingIO_E_INVALIDARG	Parameters passed are invalid

See also:: RingIO_release

Int RingIO_release	(	RingIO_Handle	handle,
		UInt32	size
	)

Releases data from the RingIO instance.

Parameters:

handle	RingIO handle
size	Size of the released buffer

Return values:

RingIO_E_FAIL	General Failure Invalid size argument > client acquired size passed
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_E_NOTIFYFAIL	Failure when sending notification to other client.
RingIO_S_SUCCESS	Operation Successful

See also:: RingIO_acquire

Int RingIO_cancel ( RingIO_Handle handle )

Cancel the previous acquired buffer to the RingIO instance 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.

Parameters:

handle RingIO handle

Return values:

RingIO_E_FAIL	General Failure No data acquired
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful

See also:: RingIO_acquire

Int RingIO_getvAttribute	(	RingIO_Handle	handle,
		UInt16 *	type,
		UInt32 *	param,
		RingIO_BufPtr	vptr,
		UInt32 *	pSize
	)

Get attribute from the RingIO instance 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.

Parameters:

handle	RingIO handle
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.

Return values:

RingIO_E_FAIL	General Failure No attribute present
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful
RingIO_S_PENDINGATTRIBUTE	Additional attributes are present at the current read offset.
RingIO_E_VARIABLEATTRIBUTE	No buffer has been provided to receive the variable attribute payload.
RingIO_E_PENDINGDATA	More data must be read before reading the attribute.

See also:: RingIO_getAttribute

Int RingIO_setvAttribute	(	RingIO_Handle	handle,
		UInt16	type,
		UInt32	param,
		RingIO_BufPtr	pData,
		UInt32	size,
		Bool	sendNotification
	)

Set attribute in the RingIO instance 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.

Parameters:

handle	Handle to the RingIO Client.
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.
sendNotification	Flag to indicate whether notification should be sent or not on successful setting of an attribute

Return values:

RingIO_E_FAIL	General Failure No attribute present
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful
RingIO_E_WRONGSTATE	Do not allow setting an attribute when it falls into reader region. The following scenarios cover this condition: The buffer is completely full. In this case, attribute can only be set at offset 0. But offset 0 falls into reader region. The buffer is completely acquired by the writer. Part or none of this buffer may be released. Writer is attempting to set an attribute at the end of its acquired range. In this case, end of writer buffer is the same as beginning of reader buffer. If the reader has acquired and released some data, resulting in its moving further such that its acquire start is not at the same location where writer may be able to set an attribute, the above conditions do not hold true, and the attribute is allowed to be set.
RingIO_E_NOTIFYFAIL	Failure when sending notification to other client.

See also:: RingIO_acquire

Int RingIO_getAttribute	(	RingIO_Handle	handle,
		UInt16 *	type,
		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.

Parameters:

handle	RingIO handle
type	Location to receive the user-defined type of attribute.
param	Location to receive an optional parameter which depends on the attribute type.

Return values:

RingIO_E_FAIL	General Failure No attribute present
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful
RingIO_S_PENDINGATTRIBUTE	Additional attributes are present at the current read offset.
RingIO_E_VARIABLEATTRIBUTE	A variable attribute exists.The application must call RingIO_getvAttribute () to get the variable attribute.
RingIO_E_PENDINGDATA	More data must be read before reading the attribute.

See also:: RingIO_getvAttribute

Int RingIO_setAttribute	(	RingIO_Handle	handle,
		UInt16	type,
		UInt32	param,
		Bool	sendNotification
	)

This function sets a fixed-size attribute at the offset provided in the acquired data buffer. 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.

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.
sendNotification	Flag to indicate whether notification should be sent or not on successful setting of an attribute

Return values:

RingIO_E_FAIL	General Failure
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful
RingIO_E_WRONGSTATE	Do not allow setting an attribute when it falls into reader region. The following scenarios cover this condition: The buffer is completely full. In this case, attribute can only be set at offset 0. But offset 0 falls into reader region. The buffer is completely acquired by the writer. Part or none of this buffer may be released. Writer is attempting to set an attribute at the end of its acquired range. In this case, end of writer buffer is the same as beginning of reader buffer. If the reader has acquired and released some data, resulting in its moving further such that its acquire start is not at the same location where writer may be able to set an attribute, the above conditions do not hold true, and the attribute is allowed to be set.
RingIO_E_NOTIFYFAIL	Failure when sending notification to other client.

Int RingIO_flush	(	RingIO_Handle	handle,
		Bool	hardFlush,
		UInt16 *	type,
		UInt32 *	param,
		UInt32 *	bytesFlushed
	)

Flush the buffer in the RingIO instance.

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.

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.

Return values:

RingIO_E_FAIL	General Failure
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful
RingIO_E_NOTIFYFAIL	Failure when sending notification to other client.

See also:: RingIO_acquire

Int RingIO_sendNotify	(	RingIO_Handle	handle,
		RingIO_NotifyMsg	msg
	)

Send a force notification to the other client manually.

Parameters:

handle	Handle to RingIO instance
msg	Payload to notification

Return values:

RingIO_E_FAIL	General Failure
RingIO_E_INVALIDARG	Parameters passed are invalid
RingIO_S_SUCCESS	Operation Successful
RingIO_E_NOTIFYFAIL	Failure when sending notification to other client.

See also:: None

UInt RingIO_getValidSize ( RingIO_Handle handle )

Function to get valid data buffer size.

Parameters:

handle RingIO client Handle.

Return values:

Valid_data_buffer_size	Operation successful
-1	Operation unsuccessful.

UInt RingIO_getEmptySize ( RingIO_Handle handle )

Function to get empty data buffer size.

Parameters:

handle RingIO client Handle.

Return values:

Empty_data_buffer_size	Operation successful
-1	Operation unsuccessful

UInt RingIO_getValidAttrSize ( RingIO_Handle handle )

Function to get valid attribute size.

Parameters:

handle RingIO client Handle.

Return values:

Valid_attribute_size	Operation successful
-1	Operation unsuccessful

UInt RingIO_getEmptyAttrSize ( RingIO_Handle handle )

Function to get empty attribute size.

Parameters:

handle RingIO client Handle.

Return values:

Empty_attribute_size Operation successful -1 Operation unsuccessful

UInt RingIO_getAcquiredOffset ( RingIO_Handle handle )

Function to get client's acquired offset.

Parameters:

handle RingIO client Handle.

Return values:

Acquired_offset	Operation successful
-1	Operation unsuccessful

UInt RingIO_getAcquiredSize ( RingIO_Handle handle )

Function to get client's acquired size.

Parameters:

handle RingIO client Handle.

Return values:

Acquired_Size	Operation successful
-1	Operation unsuccessful

UInt RingIO_getWaterMark ( RingIO_Handle handle )

Function to get client's watermark.

Parameters:

handle RingIO client Handle.

Return values:

Watermark_value Operation successful -1 Operation unsuccessful

Void RingIO_getConfig ( RingIO_Config * cfgParams )

Function to get the default configuration for the RingIO module.

This function can be called by the application to get their configuration parameter to RingIO_setup filled in by the RingIO module with the default parameters. If the user does not wish to make any change in the default parameters, this API is not required to be called.

Parameters:

cfgParams Pointer to the RingIO module configuration structure in which the default config is to be returned.

See also:: RingIO_setup

Int RingIO_setup ( const RingIO_Config * cfgParams )

Function to setup the RingIO module.

This function sets up the RingIO module. This function must be called before any other instance-level APIs can be invoked. Module-level configuration needs to be provided to this function. If the user wishes to change some specific config parameters, then RingIO_getConfig can be called to get the configuration filled with the default values. After this, only the required configuration values can be changed. If the user does not wish to make any change in the default parameters, the application can simply call RingIO with NULL parameters. The default parameters would get automatically used.

Parameters:

cfgParams Optional RingIO module configuration. If provided as NULL, default configuration is used.

Return values:

See also:: RingIO_destroy NameServer_create GateMutex_create Memory_alloc

Int RingIO_destroy ( Void )

Function to destroy the RingIO module.

Once this function is called, other RingIO module APIs, except for the RingIO_getConfig API cannot be called anymore.

Return values:

@sa	RingIO_setup, NameServer_delete, GateMutex_delete

RingIO.h File Reference

Detailed Description

Data Structures

Defines

Typedefs

Enumerations

Functions

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation