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 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.
// 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) 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>
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... | |
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 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 |
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_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. RingIO_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 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) |
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. | |
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. |
#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 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 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_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.
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 |
None |
enum RingIO_Type_Tag |
enum RingIO_OpenMode_Tag |
enum RingIO_Flags_tag |
Enumeration of flags for RingIO client. It includes information about access to buffers.
Enumerates the notification types for RingIO.
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.
params
is a valid (non-NULL) pointer.[out] | params | Pointer to the RingIO interface type specific params, refer to Interface type specific header file (e.g. RingIOShm.h) for details on interface type specific params |
None |
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.
[in] | params | Pointer to the RingIO interface type specific params, refer to Interface type specific header file (e.g. RingIOShm.h) for details on interface type specific params |
params
is a valid (non-NULL) pointer to a set of interface type specific params.non-NULL | Operation successful |
NULL | Operation unsuccessful |
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.
[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. |
handlePtr
is a valid (non-NULL) pointer to a valid RingIO handle.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 |
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.
[in] | params | Pointer to the RingIO interface type specific params, refer to Interface type specific header file (e.g. RingIOShm.h) for details on interface type specific params. |
[out] | sharedMemReqDetails | Control, Data and Attr shared memory details |
params
is a valid (non-NULL) pointer to interface specific params. sharedMemReqDetails
is a valid (non-NULL) pointer.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 |
Int RingIO_open | ( | String | name, |
const RingIO_openParams * | params, | ||
UInt16 * | procIds, | ||
RingIO_Handle * | handlePtr | ||
) |
Opens a created instance of RingIO module.
[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. |
handlePtr
is a valid (non-NULL) pointer. params
is a valid (non-NULL) pointer to a set of parameters to open the RingIO instance.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 |
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.
[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. |
handlePtr
is a valid (non-NULL) pointer. params
is a valid (non-NULL) pointer to a set of parameters for opening the RingIO instance.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 |
Int RingIO_close | ( | RingIO_Handle * | handlePtr ) |
Closes previously opened instance of RingIO module.
[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. |
handlePtr
is a valid (non-NULL) pointer to a RingIO handle.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 |
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.
[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. |
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.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 |
Int RingIO_unregisterNotifier | ( | RingIO_Handle | handle ) |
Unregister a call back function.
[in] | handle | RingIO client Handle. |
handle
is a valid (non-NULL) RingIO handle.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. |
Int RingIO_setWaterMark | ( | RingIO_Handle | handle, |
UInt32 | watermark | ||
) |
Function to set client's watermark.
[in] | handle | RingIO client Handle. |
[in] | watermark | Watermark value |
handle
is a valid (non-NULL) RingIO handle.RingIO_S_SUCCESS | Operation is successful. |
RingIO_E_FAIL | Operation is not successful. |
RingIO_E_INVALIDARG | There is an invalid argument. |
Int RingIO_setNotifyType | ( | RingIO_Handle | handle, |
RingIO_NotifyType | notifyType | ||
) |
Function to set the notify type.
[in] | handle | Instance handle. |
[in] | notifyType | Type of notification |
handle
is a valid (non-NULL) RingIO handle.RingIO_S_SUCCESS | Operation is successful. |
RingIO_E_FAIL | Operation is not successful. |
RingIO_E_INVALIDARG | There is an invalid argument. |
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.
[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. |
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.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. |
Int RingIO_release | ( | RingIO_Handle | handle, |
UInt32 | size | ||
) |
Releases data from the RingIO instance.
[in] | handle | RingIO handle |
[in] | size | Size of the released buffer |
handle
is a valid (non-NULL) RingIO handle.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. |
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.
[in] | handle | RingIO handle |
handle
is a valid (non-NULL) RingIO handle.RingIO_S_SUCCESS | Operation is successful. |
RingIO_E_FAIL | General Failure No data acquired |
RingIO_E_INVALIDARG | Parameters passed are invalid |
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.
[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. |
handle
is a valid (non-NULL) RingIO handle. type
is a valid (non-NULL) pointer. param
is a valid (non-NULL) pointer.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. |
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
[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 |
handle
is a valid (non-NULL) RingIO handle.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:
|
RingIO_E_NOTIFYFAIL | Indicates that the underlying notification call failed. |
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.
[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. |
handle
is a valid (non-NULL) RingIO handle. type
is a valid (non-NULL) pointer. param
is a valid (non-NULL) pointer.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. |
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
[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 |
handle
is a valid (non-NULL) RingIO handle.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:
|
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.
[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. |
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.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. |
Int RingIO_sendNotify | ( | RingIO_Handle | handle, |
RingIO_NotifyMsg | msg | ||
) |
Send a force notification to the other client manually.
[in] | handle | Handle to RingIO instance |
[in] | msg | Payload to notification |
handle
is a valid (non-NULL) RingIO handle.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. |
UInt RingIO_getValidSize | ( | RingIO_Handle | handle ) |
Function to get valid data buffer size.
[in] | handle | RingIO client Handle. |
handle
is a valid (non-NULL) RingIO handle.Valid_data_buffer_size | Operation successful |
-1 | Operation unsuccessful. |
UInt RingIO_getEmptySize | ( | RingIO_Handle | handle ) |
Function to get empty data buffer size.
[in] | handle | RingIO client Handle. |
handle
is a valid (non-NULL) RingIO handle.Empty_data_buffer_size | Operation successful |
-1 | Operation unsuccessful |
UInt RingIO_getValidAttrSize | ( | RingIO_Handle | handle ) |
Function to get valid attribute size.
[in] | handle | RingIO client Handle. |
handle
is a valid (non-NULL) RingIO handle.Valid_attribute_size | Operation successful |
-1 | Operation unsuccessful |
UInt RingIO_getEmptyAttrSize | ( | RingIO_Handle | handle ) |
Function to get empty attribute size.
[in] | handle | RingIO client Handle. |
handle
is a valid (non-NULL) RingIO handle.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.
[in] | handle | RingIO client Handle. |
handle
is a valid (non-NULL) RingIO handle.Acquired_offset | Operation successful |
-1 | Operation unsuccessful |
UInt RingIO_getAcquiredSize | ( | RingIO_Handle | handle ) |
Function to get client's acquired size.
[in] | handle | RingIO client Handle. |
handle
is a valid (non-NULL) RingIO handle.Acquired_Size | Operation successful |
-1 | Operation unsuccessful |
UInt RingIO_getWaterMark | ( | RingIO_Handle | handle ) |
Function to get client's watermark.
[in] | handle | RingIO client Handle. |
handle
is a valid (non-NULL) RingIO handle.Watermark_value | Operation successful |
-1 | Operation unsuccessful |