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 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>
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 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 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.
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.
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 | Pointer to the RingIO interface type specific params, refer to Interface type specific header file 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 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.
params | Pointer to the RingIO interface type specific params, refer to Interface type specific header file for details on interface type specific params |
Valid_handle_of_type_RingIO_Handle | 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.
handlePtr | Pointer to Handle to the RingIO object |
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 |
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.
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 |
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.
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. |
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 |
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.
ctrlSharedAddr | Shared address at which the instance exists |
params | Parameters for opening the RingIO instance. |
handlePtr | OUT parameter: Holds the RingIO handle on success. |
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 |
Int RingIO_close | ( | RingIO_Handle * | handlePtr ) |
Closes previously opened/created instance of RingIO module.
handlePtr | Pointer to handle for the opened RingIO instance. Reset to invalid when the function successfully completes. |
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 |
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.
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. |
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 |
Int RingIO_unregisterNotifier | ( | RingIO_Handle | handle ) |
Function to un-register call back function.
handle | RingIO client Handle. |
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 |
Int RingIO_setWaterMark | ( | RingIO_Handle | handle, |
UInt32 | watermark | ||
) |
Function to set client's watermark.
handle | RingIO client Handle. |
watermark | Watermark value |
-1 | Operation unsuccessful |
watermark | Operation successful |
Int RingIO_setNotifyType | ( | RingIO_Handle | handle, |
RingIO_NotifyType | notifyType | ||
) |
Function to set the notify type.
handle | Instance handle. |
notifyType | Type of notification |
RingIO_E_FAIL | Operation unsuccessful |
RingIO_E_INVALIDARG | Parameters passed are invalid |
RingIO_S_SUCCESS | Operation Successful |
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.
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. |
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 |
Int RingIO_release | ( | RingIO_Handle | handle, |
UInt32 | size | ||
) |
Releases data from the RingIO instance.
handle | RingIO handle |
size | Size of the released buffer |
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 |
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.
handle | RingIO handle |
RingIO_E_FAIL | General Failure No data acquired |
RingIO_E_INVALIDARG | Parameters passed are invalid |
RingIO_S_SUCCESS | Operation Successful |
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.
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. |
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. |
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.
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 |
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:
|
RingIO_E_NOTIFYFAIL | Failure when sending notification to other client. |
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.
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. |
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. |
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.
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 |
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 | 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.
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. |
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. |
Int RingIO_sendNotify | ( | RingIO_Handle | handle, |
RingIO_NotifyMsg | msg | ||
) |
Send a force notification to the other client manually.
handle | Handle to RingIO instance |
msg | Payload to notification |
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. |
UInt RingIO_getValidSize | ( | RingIO_Handle | handle ) |
Function to get valid data buffer size.
handle | RingIO client Handle. |
Valid_data_buffer_size | Operation successful |
-1 | Operation unsuccessful. |
UInt RingIO_getEmptySize | ( | RingIO_Handle | handle ) |
Function to get empty data buffer size.
handle | RingIO client Handle. |
Empty_data_buffer_size | Operation successful |
-1 | Operation unsuccessful |
UInt RingIO_getValidAttrSize | ( | RingIO_Handle | handle ) |
Function to get valid attribute size.
handle | RingIO client Handle. |
Valid_attribute_size | Operation successful |
-1 | Operation unsuccessful |
UInt RingIO_getEmptyAttrSize | ( | RingIO_Handle | handle ) |
Function to get empty attribute size.
handle | RingIO client Handle. |
Empty_attribute_size | Operation successful -1 Operation unsuccessful |
UInt RingIO_getAcquiredOffset | ( | RingIO_Handle | handle ) |
Function to get client's acquired offset.
handle | RingIO client Handle. |
Acquired_offset | Operation successful |
-1 | Operation unsuccessful |
UInt RingIO_getAcquiredSize | ( | RingIO_Handle | handle ) |
Function to get client's acquired size.
handle | RingIO client Handle. |
Acquired_Size | Operation successful |
-1 | Operation unsuccessful |
UInt RingIO_getWaterMark | ( | RingIO_Handle | handle ) |
Function to get client's watermark.
handle | RingIO client Handle. |
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.
cfgParams | Pointer to the RingIO module configuration structure in which the default config is to be returned. |
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.
cfgParams | Optional RingIO module configuration. If provided as NULL, default configuration is used. |