Detailed Description

RingIO module.

The RingIO component provides data streaming between cores using a ring buffer 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 a shared memory region between two processors. The RingIO buffer is 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 is typically a thread or task on a given processor.

The RingIO instance can be created between a client on the host CPU and a client on a slave CPU or between two clients on slave CPUs.

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

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 may have an associated footer area, if configured. The foot buffer can be configured to be of zero size if not required. If configured to be non-zero size, the foot-buffer is physically contiguous with the data buffer.

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 a Shared Memory Heap, the buffer sizes are automatically aligned to the SharedRegion's cache line size.

Example:

    // Setup SysLink
    SysLink_setup();
  
    // Create the RingIO
    RingIOShm_Params_init(&rioParams);
    rioParams.commonParams.name     = "My RingIO";
    rioParams.ctrlRegionId          = 1;
    rioParams.dataRegionId          = 1;
    rioParams.attrRegionId          = 1;
    rioParams.attrSharedAddrSize    = 16;
    rioParams.dataSharedAddrSize    = 40;
    rioParams.remoteProcId          = MultiProc_getId("DSP");
    rioParams.gateHandle            = NULL;
  
    rio_Handle = RingIO_create(&rioParams);
  
    // Open the RingIO
    rio_OpenParams.openMode         = RingIO_MODE_WRITER;
    rio_OpenParams.flags            = 0;
    status = RingIO_open(GPP_RINGIO_NAME, &rio_OpenParams, NULL,
            &rio_WriterHandle);
  
    // Write to RingIO
    status = RingIO_acquire(rio_WriterHandle, (RingIO_BufPtr*)&buffer,
            &acquiredSize);
  
    // (Can put some data into the buffer here)
  
    // Release the RingIO
    status = RingIO_release(rio_WriterHandle, acquiredSize);
  
    // Close the RingIO
    status = RingIO_close(&rio_WriterHandle);
  
    // Delete the RingIO
    status = RingIO_delete(&rio_Handle);

#include <ti/syslink/SysLink.h>

Include dependency graph for RingIO.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
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...

Macros
#define	RingIO_S_PENDINGATTRIBUTE 4
	Indicates that either: The amount of data requested could not be serviced due to the presence of an attribute During an attribute read if another is also present at the same offset.
#define	RingIO_S_NOTCONTIGUOUSDATA 3
	Indicates that data size requested is not available as a contiguous chunk. Returning partial buffer as NEED_EXACT_SIZE was not specified.
#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
	An invalid message was encountered.
#define	RingIO_E_NOTOWNER -12
	Not the owner.
#define	RingIO_E_REMOTEACTIVE -13
	Operation resulted in error.
#define	RingIO_E_INVALIDHEAPID -14
	An invalid heap id was encountered.
#define	RingIO_E_INVALIDPROCID -15
	An invalid MultiProc id was encountered.
#define	RingIO_E_MAXREACHED -16
	The max has been reached.
#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 offset, but attributes are present at a future offset.
#define	RingIO_E_VARIABLEATTRIBUTE -24
	Indicates that getAttribute() failed, need to extract variable length message using getvAttribute()
#define	RingIO_E_WRONGSTATE -25
	Indicates that the RingIO is in a wrong state.
#define	RingIO_E_NOTIFYFAIL -26
	Indicates that 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
	Pointer to a data or attribute buffer.
typedef UInt16	RingIO_NotifyMsg
	Notification message.
typedef struct RingIO_Object *	RingIO_Handle
	Handle for the RingIO instance.
typedef enum RingIO_Type_Tag	RingIO_Type
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.
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 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)
	Unregister a 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)
	Acquire data from the RingIO instance.
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.
Int	RingIO_setvAttribute (RingIO_Handle handle, UInt16 type, UInt32 param, RingIO_BufPtr pData, UInt32 size, Bool sendNotification)
	Set attribute in the RingIO instance.
Int	RingIO_getAttribute (RingIO_Handle handle, UInt16 type, UInt32 param)
	Obtain a fixed-size attribute from the attribute buffer.
Int	RingIO_setAttribute (RingIO_Handle handle, UInt16 type, UInt32 param, Bool sendNotification)
	This function sets a fixed-size attribute in the acquired data buffer.
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 acquire offset from the start of the buffer.
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.

Macro Definition Documentation

#define RingIO_S_PENDINGATTRIBUTE 4

Indicates that either:

The amount of data requested could not be serviced due to the presence of an attribute
During an attribute read if another is also present at the same offset.

#define RingIO_S_NOTCONTIGUOUSDATA 3

Indicates that data size requested is not available as a contiguous chunk. Returning partial buffer as NEED_EXACT_SIZE was not specified.

#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

An invalid message was encountered.

#define RingIO_E_NOTOWNER -12

Not the owner.

#define RingIO_E_REMOTEACTIVE -13

Operation resulted in error.

#define RingIO_E_INVALIDHEAPID -14

An invalid heap id was encountered.

#define RingIO_E_INVALIDPROCID -15

An invalid MultiProc id was encountered.

#define RingIO_E_MAXREACHED -16

The max has been reached.

#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 offset, but attributes are present at a future offset.

#define RingIO_E_VARIABLEATTRIBUTE -24

Indicates that getAttribute() failed, need to extract variable length message using getvAttribute()

#define RingIO_E_WRONGSTATE -25

Indicates that the RingIO is in a wrong state.

#define RingIO_E_NOTIFYFAIL -26

Indicates that 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

Pointer to a data or attribute buffer.

typedef UInt16 RingIO_NotifyMsg

Notification message.

This is a 16 bit payload which can be sent to the remote processor in a notification call.

typedef struct RingIO_Object* RingIO_Handle

Handle for the RingIO instance.

typedef enum RingIO_Type_Tag RingIO_Type

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 transport

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. For a writer, if a contiguous request could not be satisfied because of the buffer wrap, we mark an early end and provide a contiguous buffer from the top of the buffer. For a reader, if a contiguous request could not be satisfied, we copy the top of the buffer into the footer.

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. after a failure to acquire data/space.
RingIO_NOTIFICATION_ONCE	Notify when the other side sends data/frees up space, after a failure to acquire data/space. Once the notification is done, the notification is disabled until it is enabled again when acquire fails.
RingIO_NOTIFICATION_HDWRFIFO_ALWAYS	Notify whenever the other side sends data/frees up space if the size of data/space available is above the watermark. This notification is never disabled.
RingIO_NOTIFICATION_HDWRFIFO_ONCE	Notify when the other side sends data/frees up space, if the size is above the watermark level. 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.

Precondition:: params is a valid (non-NULL) pointer.

Parameters:

[out] params Pointer to the RingIO interface type specific params. Currently only RingIOShm_Params are supported.

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 the parameter initialization function for the RingIO transport to be used (e.g. RingIOShm_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:

[in] params Pointer to the RingIO interface type specific params. Currently only RingIOShm_Params are supported.

Precondition:: params is a valid (non-NULL) pointer to a set of interface type specific params.

Return values:

non-NULL	Operation successful
NULL	Operation unsuccessful

See also:: RingIO_Params_init(); 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:

[in] handlePtr Pointer to Handle to the RingIO object. This MUST be a handle that was returned from RingIO_create() and not one that comes from RingIO_open().

Precondition:: handlePtr is a valid (non-NULL) pointer to a valid RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
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_E_INVALIDCONTEXT	Api is not called with a handle from RingIO_create()

See also:: RingIO_create()

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

Get shared memory requirements.

RingIO_Params_init() must be called to initialize the parameters before calling this function.

Parameters:

[in]	params	RingIO interface type specific params. Currently only RingIOShm_Params are supported.
[out]	sharedMemReqDetails	Control, Data and Attr shared memory details

Precondition:: params is a valid (non-NULL) pointer to interface specific params.; sharedMemReqDetails is a valid (non-NULL) pointer.

Return values:

Success Total Shared memory requirements

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

Opens a created instance of RingIO module.

Parameters:

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

Precondition:: handlePtr is a valid (non-NULL) pointer.; params is a valid (non-NULL) pointer to a set of parameters to open the RingIO instance.

Return values:

RingIO_S_SUCCESS	Operation is successful.
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

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:

[in]	ctrlSharedAddr	Shared address at which the instance exists
[in]	params	Parameters for opening the RingIO instance.
[out]	handlePtr	Holds the RingIO handle on success.

Precondition:: handlePtr is a valid (non-NULL) pointer.; params is a valid (non-NULL) pointer to a set of parameters for opening the RingIO instance.

Return values:

RingIO_S_SUCCESS	Operation is successful.
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

See also:: RingIO_create(); RingIO_delete(); RingIO_close()

Int RingIO_close ( RingIO_Handle * handlePtr )

Closes previously opened instance of RingIO module.

Parameters:

[in] handlePtr Pointer to handle for the opened RingIO instance. MUST be a pointer returned by RingIO_open and not RingIO_create. Reset to invalid when the function successfully completes.

Precondition:: handlePtr is a valid (non-NULL) pointer to a RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
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_E_INVALIDCONTEXT	Api is not called with a handle from RingIO_open

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 SysLink API should be called from a callback function registered through the RingIO module. On SYS/BIOS 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 SysLink 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:

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

Precondition:: handle is a valid (non-NULL) RingIO handle.; notifyFunc is a valid (non-NULL) function pointer to a notification function.; cbContext is a valid (non-NULL) pointer to data that would be passed to the notification function.

Return values:

RingIO_S_SUCCESS	Operation is successful.
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

See also:: RingIO_unregisterNotifier()

Int RingIO_unregisterNotifier ( RingIO_Handle handle )

Unregister a call back function.

Parameters:

[in] handle RingIO client Handle.

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
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	There is an invalid argument.

See also:: RingIO_registerNotifier()

Int RingIO_setWaterMark	(	RingIO_Handle	handle,
		UInt32	watermark
	)

Function to set client's watermark.

Parameters:

[in]	handle	RingIO client Handle.
[in]	watermark	Watermark value

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_FAIL	Operation is not successful.
RingIO_E_INVALIDARG	There is an invalid argument.

See also:: RingIO_registerNotifier()

Int RingIO_setNotifyType	(	RingIO_Handle	handle,
		RingIO_NotifyType	notifyType
	)

Function to set the notify type.

Parameters:

[in]	handle	Instance handle.
[in]	notifyType	Type of notification

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_FAIL	Operation is not successful.
RingIO_E_INVALIDARG	There is an invalid argument.

See also:: RingIO_NotifyType; RingIO_registerNotifier()

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

Acquire 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:

[in]	handle	RingIO handle
[out]	pData	Location to store the pointer to the acquired data buffer.
[in,out]	pSize	Pointer to the size of data buffer. Holds the size of buffer to be acquired. Returns the size of buffer actually acquired.

Precondition:: handle is a valid (non-NULL) RingIO handle.; pData is a valid (non-NULL) pointer to a RingIO_BufPtr.; pSize is a valid (non-NULL) pointer to a size.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_PENDINGATTRIBUTE	(For reader only) No data buffer could be acquired because an attribute was present at the current read offset.
RingIO_S_PENDINGATTRIBUTE	(For reader only) Flag NEED_EXACT_SIZE is not set. Partial Data buffer is retuned till the offset where an attribute was present.
RingIO_E_BUFFULL	(For writer only) 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	(For writer only) 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	(For reader only) Data size requested is not available as a contiguous chunk. Returning partial buffer as NEED_EXACT_SIZE was not specified.
RingIO_E_BUFEMPTY	(For reader only) No data available to acquire
RingIO_E_INVALIDARG	There is an invalid argument.

See also:: RingIO_release()

Int RingIO_release	(	RingIO_Handle	handle,
		UInt32	size
	)

Releases data from the RingIO instance.

Parameters:

[in]	handle	RingIO handle
[in]	size	Size of the released buffer

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
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.

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:

[in] handle RingIO handle

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_FAIL	General Failure No data acquired
RingIO_E_INVALIDARG	Parameters passed are invalid

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:

[in]	handle	RingIO handle
[out]	type	Location to receive the user-defined type of attribute.
[out]	param	Location to receive an optional parameter which depends on the attribute type.
[out]	vptr	Pointer to buffer to receive the optional payload.
[out]	pSize	Location with the size of the variable attribute. On return, this stores the actual size of the payload.

Precondition:: handle is a valid (non-NULL) RingIO handle.; type is a valid (non-NULL) pointer.; param is a valid (non-NULL) pointer.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_FAIL	General Failure No attribute present
RingIO_E_INVALIDARG	Parameters passed are invalid
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:

[in]	handle	Handle to the RingIO Client.
[in]	type	User-defined type of attribute.
[in]	param	Optional parameter which depends on the attribute type.
[in]	pData	Pointer to attribute payload buffer.
[in]	size	Size of the attribute payload.
[in]	sendNotification	Flag to indicate whether notification should be sent or not on successful setting of an attribute

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_FAIL	General Failure No attribute present
RingIO_E_INVALIDARG	There is an invalid argument.
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	Indicates that the underlying notification call failed.

See also:: RingIO_acquire()

Int RingIO_getAttribute	(	RingIO_Handle	handle,
		UInt16 *	type,
		UInt32 *	param
	)

Obtain a fixed-size attribute from the attribute buffer.

If an attribute is present, the attribute type and a related parameter are returned.

Parameters:

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

Precondition:: handle is a valid (non-NULL) RingIO handle.; type is a valid (non-NULL) pointer.; param is a valid (non-NULL) pointer.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_FAIL	General Failure No attribute present
RingIO_E_INVALIDARG	There is an invalid argument.
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 in the acquired data buffer.

When no data buffer has been acquired, the attribute is set at the next data buffer that can be acquired

Parameters:

[in]	handle	Handle to the RingIO Client
[in]	type	User-defined type of attribute
[in]	param	Optional parameter which depends on the attribute type
[in]	sendNotification	Flag indicating whether notification should be sent or not on successful setting of an attribute

Precondition:: handle is a valid (non-NULL) RingIO handle.

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 the reader's 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	Indicates that the underlying notification call failed.

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

Flush the buffer in the RingIO instance.

This function is used to flush the data from the RingIO. The 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:

[in]	handle	Handle to the RingIO Client.
[in]	hardFlush	Mode in which the flush operation discards committed data and attributes
[out]	type	Location to receive the User-defined type of attribute.
[out]	param	Location to receive an optional parameter which depends on the attribute type.
[out]	bytesFlushed	Location to recieve the size of the buffer flushed.

Precondition:: handle is a valid (non-NULL) RingIO handle.; type is a valid (non-NULL) pointer.; param is a valid (non-NULL) pointer.; bytesFlushed is a valid (non-NULL) pointer.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_FAIL	Operation is not successful.
RingIO_E_INVALIDARG	There is an invalid argument.
RingIO_E_NOTIFYFAIL	Indicates that the underlying notification call failed.

See also:: RingIO_acquire()

Int RingIO_sendNotify	(	RingIO_Handle	handle,
		RingIO_NotifyMsg	msg
	)

Send a force notification to the other client manually.

Parameters:

[in]	handle	Handle to RingIO instance
[in]	msg	Payload to notification

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

RingIO_S_SUCCESS	Operation is successful.
RingIO_E_FAIL	Operation is not successful.
RingIO_E_INVALIDARG	There is an invalid argument.
RingIO_E_NOTIFYFAIL	Indicates that the underlying notification call failed.

See also:: None

UInt RingIO_getValidSize ( RingIO_Handle handle )

Function to get valid data buffer size.

Parameters:

[in] handle RingIO client Handle.

Precondition:: handle is a valid (non-NULL) RingIO 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:

[in] handle RingIO client Handle.

Precondition:: handle is a valid (non-NULL) RingIO 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:

[in] handle RingIO client Handle.

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

Valid_attribute_size	Operation successful
-1	Operation unsuccessful

UInt RingIO_getEmptyAttrSize ( RingIO_Handle handle )

Function to get empty attribute size.

Parameters:

[in] handle RingIO client Handle.

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

Empty_attribute_size	Operation successful
-1	Operation unsuccessful

UInt RingIO_getAcquiredOffset ( RingIO_Handle handle )

Function to get client's acquire offset from the start of the buffer.

Parameters:

[in] handle RingIO client Handle.

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

Acquired_offset	Operation successful
-1	Operation unsuccessful

UInt RingIO_getAcquiredSize ( RingIO_Handle handle )

Function to get client's acquired size.

Parameters:

[in] handle RingIO client Handle.

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

Acquired_Size	Operation successful
-1	Operation unsuccessful

UInt RingIO_getWaterMark ( RingIO_Handle handle )

Function to get client's watermark.

Parameters:

[in] handle RingIO client Handle.

Precondition:: handle is a valid (non-NULL) RingIO handle.

Return values:

Watermark_value	Operation successful
-1	Operation unsuccessful

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation