CMN_SimpleFifo.h

Go to the documentation of this file.

/****************************************************************************
 * modules/include/memutils/simple_fifo/CMN_SimpleFifo.h
 *
 *   Copyright 2018 Sony Semiconductor Solutions Corporation
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 3. Neither the name of Sony Semiconductor Solutions Corporation nor
 *    the names of its contributors may be used to endorse or promote
 *    products derived from this software without specific prior written
 *    permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 ****************************************************************************/
 
#if !defined(CMN_SIMPLE_FIFO_H)
#define CMN_SIMPLE_FIFO_H
 
/* API Documents creater with Doxgen */
 
#ifdef __cplusplus
 extern "C" {
#endif
 
#include <stddef.h>
#include <stdint.h>
 
typedef struct {
    uint8_t* m_pBuf; 
    void* m_pExtInfo; 
    size_t m_size; 
    size_t m_wp; 
    size_t m_rp; 
} CMN_SimpleFifoHandle;
 
typedef struct {
    uint8_t* m_pChunk[2]; 
    size_t m_szChunk[2]; 
} CMN_SimpleFifoPeekHandle;
 
typedef void* (*CMN_SimpleFifoCopierFunc)(
        void* pCopierFuncExtInfo,
        void* pDest,
        const void* pSrc,
        size_t sz);
 
int CMN_SimpleFifoInitialize(
        CMN_SimpleFifoHandle* pHandle,
        void* pFifoBuffer,
        size_t szFifoBuffer,
        void* pExtInfo);
 
 
size_t CMN_SimpleFifoOffer(
        CMN_SimpleFifoHandle* pHandle,
        const void* pElement,
        size_t sz);
 
size_t CMN_SimpleFifoOfferWithSpecificCopier(
        CMN_SimpleFifoHandle* pHandle,
        const void* pElement,
        size_t sz,
        CMN_SimpleFifoCopierFunc copierFunc,
        void* pCopierFuncExtInfo);
 
size_t CMN_SimpleFifoOfferContinuous(
        CMN_SimpleFifoHandle* pHandle,
        const void* pElement,
        size_t sz,
        int fallback,
        size_t* pGap);
 
size_t CMN_SimpleFifoOfferContinuousWithSpecificCopier(
        CMN_SimpleFifoHandle* pHandle,
        const void* pElement,
        size_t sz,
        int fallback,
        size_t* pGap,
        CMN_SimpleFifoCopierFunc copierFunc,
        void* pCopierFuncExtInfo);
 
size_t CMN_SimpleFifoPoll(
        CMN_SimpleFifoHandle* pHandle,
        void* pElement,
        size_t sz);
 
size_t CMN_SimpleFifoPollWithSpecificCopier(
        CMN_SimpleFifoHandle* pHandle,
        void* pElement,
        size_t sz,
        CMN_SimpleFifoCopierFunc copierFunc,
        void* pCopierFuncExtInfo);
 
size_t CMN_SimpleFifoPeekWithOffset(
        const CMN_SimpleFifoHandle* pHandle,
        CMN_SimpleFifoPeekHandle* pPeekHandle,
        size_t sz,
        size_t offset);
 
static inline size_t CMN_SimpleFifoPeek(
        const CMN_SimpleFifoHandle* pHandle,
        CMN_SimpleFifoPeekHandle* pPeekHandle,
        size_t sz) {
    return CMN_SimpleFifoPeekWithOffset(pHandle, pPeekHandle, sz, 0);
}
 
 
void CMN_SimpleFifoClear(
        CMN_SimpleFifoHandle* pHandle);
 
size_t CMN_SimpleFifoGetVacantSize(
        const CMN_SimpleFifoHandle* pHandle);
 
size_t CMN_SimpleFifoGetOccupiedSize(
        const CMN_SimpleFifoHandle* pHandle);
 
void* CMN_SimpleFifoGetExtInfo(
        const CMN_SimpleFifoHandle* pHandle);
 
size_t CMN_SimpleFifoGetDataSizeOfPeekHandle(
        const CMN_SimpleFifoPeekHandle* pPeekHandle);
 
size_t CMN_SimpleFifoCopyFromPeekHandle(
        const CMN_SimpleFifoPeekHandle* pPeekHandle,
        void* pDest,
        size_t sz);
 
size_t CMN_SimpleFifoCopyFromPeekHandleWithSpecificCopier(
        const CMN_SimpleFifoPeekHandle* pPeekHandle,
        void* pDest,
        size_t sz,
        CMN_SimpleFifoCopierFunc copierFunc,
        void* pCopierFuncExtInfo);
 
#ifdef __cplusplus
}
#endif
#endif /* CMN_SIMPLE_FIFO_H */
 
/*
 * @mainpage SimpleFifo API manual
 *
 * SimpleFifo is a FIFO library.
 *
 * Basically it supports one-writer and one-reader access without any
 * exclusive control. Some exclusive access control is required to
 * support multi-writer/reader outside of this library.
 *
 * This library supports access from multi-processor inserting proper
 * data-sync-barriers and data-memory-barriers. It makes sure the
 * order of update data contents and WP/RP for the purpose.
 *
 * @section how-to-use How to use
 * To use this API, include header file CMN_SimpleFifo.h. In CXD5602 build system, add the following line in your C/C++ code.
 * @code
 * #include <common/CMN_SimpleFifo.h>
 * @endcode
 * 
 * See \ref sample for more details.
 *
 * @section api API
 * See CMN_SimpleFifo.h.
 *
 * @section sample Sample Code
 * Error check is omitted for explanatory purposes.
 * 
 * @code
 * #include <stdio.h>
 * #include <stdlib.h>
 *
 * #include <common/CMN_SimpleFifo.h>
 * 
 * // This is just for explanation.
 * // If you want to use normal memcpy() for FIFO operations,
 * // do not use WithSpecificCopier version API but use normal
 * //relavant API which includes memcpy() like copier.
 * static void* myOwnCopier(
 *         void* pCopierFuncExtInfo,
 *         void* pDest,
 *         const void* pSrc,
 *         size_t sz) {
 *     return memcpy(pDest, pSrc, sz);
 * }
 * 
 * int main() {
 *     //
 *     // Setup FIFO
 *     //
 *     // We assign 256byte buffer to the FIFO. So we can store 255(= 256-1)byte in maximum.
 *     const size_t SIZE = 256;
 *     CMN_SimpleFifoHandle* pHandle = malloc(sizeof(CMN_SimpleFifoHandle));
 *     void* pFifoBuffer = malloc(SIZE);
 *     if (pHandle == NULL
 *         || pFifoBuffer == NULL
 *         || CMN_SimpleFifoInitialize(pHandle, pFifoBuffer, SIZE, NULL) != 0) {
 *         printf("FIFO create error\n");
 *         return -1;
 *     }
 * 
 *     const uint8_t src[] = {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm'};
 *     uint8_t dst[128];
 * 
 *     //
 *     // The simplest usage example.
 *     //
 *     CMN_SimpleFifoOffer(pHandle, src, 2); // write
 *     CMN_SimpleFifoPoll(pHandle, dst, 2);  // read
 * 
 *     //
 *     // Continuous Region Option usage example.
 *     //
 *     //   write in a continuous region
 *     size_t gap = 0;
 *     CMN_SimpleFifoOfferContinuous(pHandle, src, 2, 0, &gap); 
 *     //   skip gap if any
 *     if (0 < gap) {
 *         CMN_SimpleFifoPoll(pHandle, NULL, gap);
 *     }
 *     //   read 
 *     CMN_SimpleFifoPoll(pHandle, dst, 2);
 * 
 *     //
 *     // Peek usage example.
 *     //
 *     CMN_SimpleFifoOfferContinuous(pHandle, src, 2, 0, &gap);
 *     if (0 < gap) {
 *         CMN_SimpleFifoPoll(pHandle, NULL, gap); // skip gap if any
 *     }
 *     CMN_SimpleFifoPeekHandle peekHandle;
 *     CMN_SimpleFifoPeek(pHandle, &peekHandle, 2);
 *     size_t szPeekData = CMN_SimpleFifoGetDataSizeOfPeekHandle(&peekHandle);
 *     if (sizeof(dst) / sizeof(dst[0]) < szPeekData) {
 *         szPeekData = sizeof(dst) / sizeof(dst[0]);
 *     }
 *     CMN_SimpleFifoCopyFromPeekHandle(&peekHandle, dst, szPeekData);
 * 
 *     //
 *     // Specific copier usage example.
 *     //
 *     CMN_SimpleFifoOfferWithSpecificCopier(pHandle, src, 2, myOwnCopier, NULL); // write
 *     CMN_SimpleFifoPollWithSpecificCopier(pHandle, dst, 2, myOwnCopier, NULL);  // read
 * 
 *     //
 *     //  dispose the FIFO.
 *     //
 *     CMN_SimpleFifoClear(pHandle);
 *     free(pHandle);
 *     free(pFifoBuffer);
 * 
 *     return 0;
 * }
 * @endcode
 * 
 * @section buffer Internal Buffer Status
 * Here is an example of internal buffer status.
 *
 * @image html SimpleFifoBufferStatus.png
 * 
 */