Developer World
Spresense SDK Library v1.5.0-b17578a
Collaboration diagram for Simple Fifo API:

Files

file  CMN_SimpleFifo.h
 CXD5602 Sipmle Fifo API.
 

Classes

struct  CMN_SimpleFifoHandle
 FIFO handle which holds data required to manipulate FIFO. More...
 
struct  CMN_SimpleFifoPeekHandle
 Data handle used for CMN_SimpleFifoPeek(). More...
 

Typedefs

typedef void *(* CMN_SimpleFifoCopierFunc) (void *pCopierFuncExtInfo, void *pDest, const void *pSrc, size_t sz)
 Definition of data copier function. More...
 

Manupilation

int CMN_SimpleFifoInitialize (CMN_SimpleFifoHandle *pHandle, void *pFifoBuffer, size_t szFifoBuffer, void *pExtInfo)
 Initialize FIFO. More...
 
void CMN_SimpleFifoClear (CMN_SimpleFifoHandle *pHandle)
 Reset the RP/WP of the FIFO. More...
 

Offer(Insert)

size_t CMN_SimpleFifoOffer (CMN_SimpleFifoHandle *pHandle, const void *pElement, size_t sz)
 Insert data to the FIFO using the default copier(memcpy like). More...
 
size_t CMN_SimpleFifoOfferWithSpecificCopier (CMN_SimpleFifoHandle *pHandle, const void *pElement, size_t sz, CMN_SimpleFifoCopierFunc copierFunc, void *pCopierFuncExtInfo)
 Insert data to the FIFO using the specified copier. More...
 
size_t CMN_SimpleFifoOfferContinuous (CMN_SimpleFifoHandle *pHandle, const void *pElement, size_t sz, int fallback, size_t *pGap)
 Insert data to the FIFO with Continuous Region Option using the default copier(memcpy like). More...
 
size_t CMN_SimpleFifoOfferContinuousWithSpecificCopier (CMN_SimpleFifoHandle *pHandle, const void *pElement, size_t sz, int fallback, size_t *pGap, CMN_SimpleFifoCopierFunc copierFunc, void *pCopierFuncExtInfo)
 Insert data to the FIFO with Continuous Region Option using the specified copier. More...
 

Refer and Remove

size_t CMN_SimpleFifoPoll (CMN_SimpleFifoHandle *pHandle, void *pElement, size_t sz)
 Retrieves data on the head of FIFO and removes it from the FIFO using the default copier(memcpy like). More...
 
size_t CMN_SimpleFifoPollWithSpecificCopier (CMN_SimpleFifoHandle *pHandle, void *pElement, size_t sz, CMN_SimpleFifoCopierFunc copierFunc, void *pCopierFuncExtInfo)
 Retrieves data on the head of FIFO and removes it from the FIFO using the specified copier. More...
 

Refer and NOT Remove

size_t CMN_SimpleFifoPeekWithOffset (const CMN_SimpleFifoHandle *pHandle, CMN_SimpleFifoPeekHandle *pPeekHandle, size_t sz, size_t offset)
 Retrieves data on the offset from head of the FIFO but does not remove from the FIFO. More...
 

Query and Utility

size_t CMN_SimpleFifoGetVacantSize (const CMN_SimpleFifoHandle *pHandle)
 Get vacant size of the FIFO. More...
 
size_t CMN_SimpleFifoGetOccupiedSize (const CMN_SimpleFifoHandle *pHandle)
 Get occupied size of the FIFO. More...
 
void * CMN_SimpleFifoGetExtInfo (const CMN_SimpleFifoHandle *pHandle)
 Get the value of the ExtInfo set to the FIFO. More...
 
size_t CMN_SimpleFifoGetDataSizeOfPeekHandle (const CMN_SimpleFifoPeekHandle *pPeekHandle)
 Get total size of data in peek handle. More...
 
size_t CMN_SimpleFifoCopyFromPeekHandle (const CMN_SimpleFifoPeekHandle *pPeekHandle, void *pDest, size_t sz)
 Copy data pointed by PeekHandle using default copier(memcpy like). More...
 
size_t CMN_SimpleFifoCopyFromPeekHandleWithSpecificCopier (const CMN_SimpleFifoPeekHandle *pPeekHandle, void *pDest, size_t sz, CMN_SimpleFifoCopierFunc copierFunc, void *pCopierFuncExtInfo)
 Copy data pointed by PeekHandle using specific copier. More...
 

Detailed Description

Typedef Documentation

◆ CMN_SimpleFifoCopierFunc

typedef void*(* CMN_SimpleFifoCopierFunc) (void *pCopierFuncExtInfo, void *pDest, const void *pSrc, size_t sz)

Definition of data copier function.

Clients can set specific copier function to some APIs.

Specific copier might be special copier function like DMA-controller-involved-copier or special-logic-copier.

Otherwise, normal version APIs that utilize embedded memory copier should be enough.

Parameters
[in]pCopierFuncExtInfoInfo passed to the copier function.
[in]pDestAddress of the destination region.
[in]pSrcAddress of the source region.
[in]szNumber of bytes to copy.
Returns
Pointer to the destination region.

Function Documentation

◆ CMN_SimpleFifoInitialize()

int CMN_SimpleFifoInitialize ( CMN_SimpleFifoHandle pHandle,
void *  pFifoBuffer,
size_t  szFifoBuffer,
void *  pExtInfo 
)

Initialize FIFO.

Clients should prepare all memory regions required for the FIFO. This function receives memory regions and sets up them for FIFO use.

On failures, any data pointed with the pHandle and the pFifoBuffer are kept untouched.

Parameters
[in]pHandlePointer to a memory region used for FIFO management. It should be word aligned address. NULL is NOT allowed.
  • API call Failure
    • Not word aligned
    • NULL
  • Assertion Failure
[in]pFifoBufferPointer to a memory region used for FIFO data buffer. It should be word aligned address. NULL is NOT allowed.
  • API call Failure
    • Not word aligned
    • NULL
  • Assertion Failure
[in]szFifoBufferSize of memory region pointed with pFifoBuffer. It must be equal to or greater than
  1. Avaiable size for FIFO data is szFifoBuffer - 1. If the value is 1 or less, the API call fails.
  • API call Failure
    • 1 or less
  • Assertion Failure
[in]pExtInfoData shared through the FIFO. Any CMN_SimpleFifo APIs never refer to and modify this. NULL is allowed.
Returns
Result of the API call.
  • 0 on success
  • -1 on failures.

◆ CMN_SimpleFifoOffer()

size_t CMN_SimpleFifoOffer ( CMN_SimpleFifoHandle pHandle,
const void *  pElement,
size_t  sz 
)

Insert data to the FIFO using the default copier(memcpy like).

If all data cannot be stored, FIFO is kept untouched and the API call fails.

Parameters
[in]pHandlePointer to the control block of the FIFO in which data will be stored. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]pElementPointer to the data to be stored. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]szSise of data to be stored.
Returns
  • On success, size of stored data
  • On failure, 0

◆ CMN_SimpleFifoOfferWithSpecificCopier()

size_t CMN_SimpleFifoOfferWithSpecificCopier ( CMN_SimpleFifoHandle pHandle,
const void *  pElement,
size_t  sz,
CMN_SimpleFifoCopierFunc  copierFunc,
void *  pCopierFuncExtInfo 
)

Insert data to the FIFO using the specified copier.

Specific copier might be special copier function like DMA-controller-involved-copier or special-logic-copier.

If all data cannot be stored, FIFO is kept untouched.

Parameters
[in]pHandlePointer to the control block of the FIFO in which data will be stored. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]pElementPointer to the data to be stored. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]szSize of the data to be stored.
[in]copierFuncPointer to copier function. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]pCopierFuncExtInfoAn argument passed to the copierFunc. CMN_SimpleFifo never refer to the pointer.
Returns
  • On success, size of stored data
  • On failure, 0

◆ CMN_SimpleFifoOfferContinuous()

size_t CMN_SimpleFifoOfferContinuous ( CMN_SimpleFifoHandle pHandle,
const void *  pElement,
size_t  sz,
int  fallback,
size_t *  pGap 
)

Insert data to the FIFO with Continuous Region Option using the default copier(memcpy like).

It will try to store data in one (continuous) region first. Client can specify a preferred behavior for the case that it's impossible to store the data in one region.

If all data cannot be stored after all, FIFO is kept untouched.

Parameters
[in]pHandlePointer to the control block of the FIFO in which data will be stored. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]pElementPointer to the data to be stored. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]szSize of the data to be stored.
[in]fallbackSpecify behavior if it's impossible to store the data in one region. Fallback is to allow to store in separated regions
  • 0 to allow fallback.
  • Values other than 0 to NOT allow fallback.
[out]pGapSize of the gap inserted prior to the store data. FIFO readers should skip the gap to obtain the data. If the API call fails, cleared with 0. NULL is NOT allowed.
  • Assertion Failure
    • NULL
Returns
  • On success, size of stored data
  • On failure, 0

◆ CMN_SimpleFifoOfferContinuousWithSpecificCopier()

size_t CMN_SimpleFifoOfferContinuousWithSpecificCopier ( CMN_SimpleFifoHandle pHandle,
const void *  pElement,
size_t  sz,
int  fallback,
size_t *  pGap,
CMN_SimpleFifoCopierFunc  copierFunc,
void *  pCopierFuncExtInfo 
)

Insert data to the FIFO with Continuous Region Option using the specified copier.

It will try to store data in one (continuous) region. Client can specify the preferred behavior if it's impossible to store the data in one region.

Specific copier might be special copier function like DMA-controller-involved-copier or special-logic-copier.

If all data cannot be stored, FIFO is kept untouched.

Parameters
[in]pHandlePointer to the control block of the FIFO in which data will be stored. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]pElementPointer to the data to be stored. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]szSize of the data to be stored.
[in]fallbackSpecify behavior if it's impossible to store the data in one region. Fallback is to allow to store in separated regions
  • 0 to allow fallback.
  • Values other than 0 to NOT allow fallback.
[out]pGapSize of the gap inserted prior to the store data. FIFO readers should skip the gap to obtain the data. If the API call fails, cleared with 0. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]copierFuncPointer to copier function. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]pCopierFuncExtInfoAn argument passed to the copierFunc. CMN_SimpleFifo never refer to the pointer.
Returns
  • On success, size of stored data
  • On failure, 0

◆ CMN_SimpleFifoPoll()

size_t CMN_SimpleFifoPoll ( CMN_SimpleFifoHandle pHandle,
void *  pElement,
size_t  sz 
)

Retrieves data on the head of FIFO and removes it from the FIFO using the default copier(memcpy like).

On failures, the FIFO is kept untouched.

Parameters
[in]pHandlePointer to the control block of the FIFO from which data will be retrieved. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[out]pElementPointer to the memory in which retrieved data is stored. Client should prepare enough memory. NULL is allowed. If NULL is specified, retrieved data is just dicarded.
[in]szSize of data to retrieve.
Returns
  • On success, size of data retrieved.
  • On failure, 0 is returned.

◆ CMN_SimpleFifoPollWithSpecificCopier()

size_t CMN_SimpleFifoPollWithSpecificCopier ( CMN_SimpleFifoHandle pHandle,
void *  pElement,
size_t  sz,
CMN_SimpleFifoCopierFunc  copierFunc,
void *  pCopierFuncExtInfo 
)

Retrieves data on the head of FIFO and removes it from the FIFO using the specified copier.

Specific copier might be special copier function like DMA-controller-involved-copier or special-logic-copier.

On failures, the FIFO is kept untouched.

Parameters
[in]pHandlePointer to the control block of the FIFO from which data will be retrieved. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[out]pElementPointer to the memory in which retrieved data is stored. Client should prepare enough memory. NULL is allowed. If NULL is specified, retrieved data is just dicarded.
[in]szSize of data to retrieve.
[in]copierFuncPointer to copier function. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]pCopierFuncExtInfoAn argument passed to the copierFunc. CMN_SimpleFifo never refer to the pointer.
Returns
  • On success, size of data retrieved.
  • On failure, 0 is returned.

◆ CMN_SimpleFifoPeekWithOffset()

size_t CMN_SimpleFifoPeekWithOffset ( const CMN_SimpleFifoHandle pHandle,
CMN_SimpleFifoPeekHandle pPeekHandle,
size_t  sz,
size_t  offset 
)

Retrieves data on the offset from head of the FIFO but does not remove from the FIFO.

Parameters
[in]pHandlePointer to the control block of the FIFO from which data will be retrieved. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[out]pPeekHandlePointer to the memory in which retrieved peek info is stored. Client must prepare enough memory. On failure, cleared with values meaning empty. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]szSize of data to retrieve.
[in]offsetOffest from RP(read point) of pHandle.
Returns
  • On success, size of data retrieved.
  • On failure, 0 is returned.

◆ CMN_SimpleFifoClear()

void CMN_SimpleFifoClear ( CMN_SimpleFifoHandle pHandle)

Reset the RP/WP of the FIFO.

FIFO gets empty but all data in the buffer still remain.

Parameters
[in]pHandlePointer to the control block of the FIFO. NULL is NOT allowed.
  • Assertion Failure
    • NULL

◆ CMN_SimpleFifoGetVacantSize()

size_t CMN_SimpleFifoGetVacantSize ( const CMN_SimpleFifoHandle pHandle)

Get vacant size of the FIFO.

The vacant size is the size which is available to store data in the FIFO.

Parameters
[in]pHandlePointer to the control block of the FIFO. NULL is NOT allowed.
  • Assertion Failure
    • NULL
Returns
Vacant size of the FIFO.

◆ CMN_SimpleFifoGetOccupiedSize()

size_t CMN_SimpleFifoGetOccupiedSize ( const CMN_SimpleFifoHandle pHandle)

Get occupied size of the FIFO.

The occupied size is the size of data already stored in the FIFO.

Parameters
[in]pHandlePointer to the control block of the FIFO. NULL is NOT allowed.
  • Assertion Failure
    • NULL
Returns
Occupied size of the FIFO.

◆ CMN_SimpleFifoGetExtInfo()

void* CMN_SimpleFifoGetExtInfo ( const CMN_SimpleFifoHandle pHandle)

Get the value of the ExtInfo set to the FIFO.

Parameters
[in]pHandlePointer to the control block of the FIFO. NULL is NOT allowed.
  • Assertion Failure
    • NULL
Returns
Value of the ExtInfo set to the FIFO.

◆ CMN_SimpleFifoGetDataSizeOfPeekHandle()

size_t CMN_SimpleFifoGetDataSizeOfPeekHandle ( const CMN_SimpleFifoPeekHandle pPeekHandle)

Get total size of data in peek handle.

Parameters
[in]pPeekHandlePointer to the peek handle to calc. NULL is NOT allowed.
  • Assertion Failure
    • NULL
Returns
Size of data in peek handle.

◆ CMN_SimpleFifoCopyFromPeekHandle()

size_t CMN_SimpleFifoCopyFromPeekHandle ( const CMN_SimpleFifoPeekHandle pPeekHandle,
void *  pDest,
size_t  sz 
)

Copy data pointed by PeekHandle using default copier(memcpy like).

Parameters
[in]pPeekHandlePointer to the source peek handle. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[out]pDestPointer to the destination region. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]szMaximum size to copy in byte.
Returns
Number of copied byte.

◆ CMN_SimpleFifoCopyFromPeekHandleWithSpecificCopier()

size_t CMN_SimpleFifoCopyFromPeekHandleWithSpecificCopier ( const CMN_SimpleFifoPeekHandle pPeekHandle,
void *  pDest,
size_t  sz,
CMN_SimpleFifoCopierFunc  copierFunc,
void *  pCopierFuncExtInfo 
)

Copy data pointed by PeekHandle using specific copier.

Specific copier might be special copier function like DMA-controller-involved-copier or special-logic-copier.

Parameters
[in]pPeekHandlePointer to the source peek handle. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[out]pDestPointer to the destination region. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]szMaximum size to copy in byte.
[in]copierFuncPointer to copier function. NULL is NOT allowed.
  • Assertion Failure
    • NULL
[in]pCopierFuncExtInfoAn argument passed to the copierFunc. CMN_SimpleFifo never refer to the pointer.
Returns
Number of copied byte.