Developer World
Spresense SDK Library v2.0.1-3834d32
CMN_SimpleFifo.h
Go to the documentation of this file.
1 /****************************************************************************
2  * modules/include/memutils/simple_fifo/CMN_SimpleFifo.h
3  *
4  * Copyright 2018 Sony Semiconductor Solutions Corporation
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in
14  * the documentation and/or other materials provided with the
15  * distribution.
16  * 3. Neither the name of Sony Semiconductor Solutions Corporation nor
17  * the names of its contributors may be used to endorse or promote
18  * products derived from this software without specific prior written
19  * permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
28  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  * POSSIBILITY OF SUCH DAMAGE.
33  *
34  ****************************************************************************/
35 
43 #if !defined(CMN_SIMPLE_FIFO_H)
44 #define CMN_SIMPLE_FIFO_H
45 
46 /* API Documents creater with Doxgen */
47 
63 #ifdef __cplusplus
64  extern "C" {
65 #endif
66 
67 #include <stddef.h>
68 #include <stdint.h>
69 
78 typedef struct {
79  uint8_t* m_pBuf;
80  void* m_pExtInfo;
81  size_t m_size;
82  size_t m_wp;
83  size_t m_rp;
85 
101 typedef struct {
102  uint8_t* m_pChunk[2];
103  size_t m_szChunk[2];
105 
123 typedef void* (*CMN_SimpleFifoCopierFunc)(
124  void* pCopierFuncExtInfo,
125  void* pDest,
126  const void* pSrc,
127  size_t sz);
128 
176  CMN_SimpleFifoHandle* pHandle,
177  void* pFifoBuffer,
178  size_t szFifoBuffer,
179  void* pExtInfo);
181 
186 
208 size_t CMN_SimpleFifoOffer(
209  CMN_SimpleFifoHandle* pHandle,
210  const void* pElement,
211  size_t sz);
212 
246  CMN_SimpleFifoHandle* pHandle,
247  const void* pElement,
248  size_t sz,
249  CMN_SimpleFifoCopierFunc copierFunc,
250  void* pCopierFuncExtInfo);
251 
291  CMN_SimpleFifoHandle* pHandle,
292  const void* pElement,
293  size_t sz,
294  int fallback,
295  size_t* pGap);
296 
349  CMN_SimpleFifoHandle* pHandle,
350  const void* pElement,
351  size_t sz,
352  int fallback,
353  size_t* pGap,
354  CMN_SimpleFifoCopierFunc copierFunc,
355  void* pCopierFuncExtInfo);
357 
384 size_t CMN_SimpleFifoPoll(
385  CMN_SimpleFifoHandle* pHandle,
386  void* pElement,
387  size_t sz);
388 
424  CMN_SimpleFifoHandle* pHandle,
425  void* pElement,
426  size_t sz,
427  CMN_SimpleFifoCopierFunc copierFunc,
428  void* pCopierFuncExtInfo);
430 
459  const CMN_SimpleFifoHandle* pHandle,
460  CMN_SimpleFifoPeekHandle* pPeekHandle,
461  size_t sz,
462  size_t offset);
464 
490 static inline size_t CMN_SimpleFifoPeek(
491  const CMN_SimpleFifoHandle* pHandle,
492  CMN_SimpleFifoPeekHandle* pPeekHandle,
493  size_t sz) {
494  return CMN_SimpleFifoPeekWithOffset(pHandle, pPeekHandle, sz, 0);
495 }
496 
498 
513  CMN_SimpleFifoHandle* pHandle);
515 
534  const CMN_SimpleFifoHandle* pHandle);
535 
548  const CMN_SimpleFifoHandle* pHandle);
549 
561  const CMN_SimpleFifoHandle* pHandle);
562 
574  const CMN_SimpleFifoPeekHandle* pPeekHandle);
575 
594  const CMN_SimpleFifoPeekHandle* pPeekHandle,
595  void* pDest,
596  size_t sz);
597 
627  const CMN_SimpleFifoPeekHandle* pPeekHandle,
628  void* pDest,
629  size_t sz,
630  CMN_SimpleFifoCopierFunc copierFunc,
631  void* pCopierFuncExtInfo);
633 
634 #ifdef __cplusplus
635 }
636 #endif
637 
638 #endif /* CMN_SIMPLE_FIFO_H */
639 
640 /*
641  * @mainpage SimpleFifo API manual
642  *
643  * SimpleFifo is a FIFO library.
644  *
645  * Basically it supports one-writer and one-reader access without any
646  * exclusive control. Some exclusive access control is required to
647  * support multi-writer/reader outside of this library.
648  *
649  * This library supports access from multi-processor inserting proper
650  * data-sync-barriers and data-memory-barriers. It makes sure the
651  * order of update data contents and WP/RP for the purpose.
652  *
653  * @section how-to-use How to use
654  * To use this API, include header file CMN_SimpleFifo.h. In CXD5602 build system, add the following line in your C/C++ code.
655  * @code
656  * #include <common/CMN_SimpleFifo.h>
657  * @endcode
658  *
659  * See \ref sample for more details.
660  *
661  * @section api API
662  * See CMN_SimpleFifo.h.
663  *
664  * @section sample Sample Code
665  * Error check is omitted for explanatory purposes.
666  *
667  * @code
668  * #include <stdio.h>
669  * #include <stdlib.h>
670  *
671  * #include <common/CMN_SimpleFifo.h>
672  *
673  * // This is just for explanation.
674  * // If you want to use normal memcpy() for FIFO operations,
675  * // do not use WithSpecificCopier version API but use normal
676  * //relavant API which includes memcpy() like copier.
677  * static void* myOwnCopier(
678  * void* pCopierFuncExtInfo,
679  * void* pDest,
680  * const void* pSrc,
681  * size_t sz) {
682  * return memcpy(pDest, pSrc, sz);
683  * }
684  *
685  * int main() {
686  * //
687  * // Setup FIFO
688  * //
689  * // We assign 256byte buffer to the FIFO. So we can store 255(= 256-1)byte in maximum.
690  * const size_t SIZE = 256;
691  * CMN_SimpleFifoHandle* pHandle = malloc(sizeof(CMN_SimpleFifoHandle));
692  * void* pFifoBuffer = malloc(SIZE);
693  * if (pHandle == NULL
694  * || pFifoBuffer == NULL
695  * || CMN_SimpleFifoInitialize(pHandle, pFifoBuffer, SIZE, NULL) != 0) {
696  * printf("FIFO create error\n");
697  * return -1;
698  * }
699  *
700  * const uint8_t src[] = {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm'};
701  * uint8_t dst[128];
702  *
703  * //
704  * // The simplest usage example.
705  * //
706  * CMN_SimpleFifoOffer(pHandle, src, 2); // write
707  * CMN_SimpleFifoPoll(pHandle, dst, 2); // read
708  *
709  * //
710  * // Continuous Region Option usage example.
711  * //
712  * // write in a continuous region
713  * size_t gap = 0;
714  * CMN_SimpleFifoOfferContinuous(pHandle, src, 2, 0, &gap);
715  * // skip gap if any
716  * if (0 < gap) {
717  * CMN_SimpleFifoPoll(pHandle, NULL, gap);
718  * }
719  * // read
720  * CMN_SimpleFifoPoll(pHandle, dst, 2);
721  *
722  * //
723  * // Peek usage example.
724  * //
725  * CMN_SimpleFifoOfferContinuous(pHandle, src, 2, 0, &gap);
726  * if (0 < gap) {
727  * CMN_SimpleFifoPoll(pHandle, NULL, gap); // skip gap if any
728  * }
729  * CMN_SimpleFifoPeekHandle peekHandle;
730  * CMN_SimpleFifoPeek(pHandle, &peekHandle, 2);
731  * size_t szPeekData = CMN_SimpleFifoGetDataSizeOfPeekHandle(&peekHandle);
732  * if (sizeof(dst) / sizeof(dst[0]) < szPeekData) {
733  * szPeekData = sizeof(dst) / sizeof(dst[0]);
734  * }
735  * CMN_SimpleFifoCopyFromPeekHandle(&peekHandle, dst, szPeekData);
736  *
737  * //
738  * // Specific copier usage example.
739  * //
740  * CMN_SimpleFifoOfferWithSpecificCopier(pHandle, src, 2, myOwnCopier, NULL); // write
741  * CMN_SimpleFifoPollWithSpecificCopier(pHandle, dst, 2, myOwnCopier, NULL); // read
742  *
743  * //
744  * // dispose the FIFO.
745  * //
746  * CMN_SimpleFifoClear(pHandle);
747  * free(pHandle);
748  * free(pFifoBuffer);
749  *
750  * return 0;
751  * }
752  * @endcode
753  *
754  * @section buffer Internal Buffer Status
755  * Here is an example of internal buffer status.
756  *
757  * @image html SimpleFifoBufferStatus.png
758  *
759  */
760 
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.
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.
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. ...
size_t m_size
Size of the internal ring buffer. Available size if m_size - 1 because one element is used as a separ...
Definition: CMN_SimpleFifo.h:81
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.
size_t CMN_SimpleFifoGetOccupiedSize(const CMN_SimpleFifoHandle *pHandle)
Get occupied size of the FIFO.
size_t CMN_SimpleFifoGetVacantSize(const CMN_SimpleFifoHandle *pHandle)
Get vacant size of the FIFO.
void *(* CMN_SimpleFifoCopierFunc)(void *pCopierFuncExtInfo, void *pDest, const void *pSrc, size_t sz)
Definition of data copier function.
Definition: CMN_SimpleFifo.h:123
uint8_t * m_pBuf
Internal ring buffer.
Definition: CMN_SimpleFifo.h:79
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...
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)...
FIFO handle which holds data required to manipulate FIFO.
Definition: CMN_SimpleFifo.h:78
void * m_pExtInfo
Info set to the fifo. CMN_SimpleFifo APIs never refer/modify it. Use CMN_SimpleFifoGetExtInfo() to re...
Definition: CMN_SimpleFifo.h:80
size_t CMN_SimpleFifoCopyFromPeekHandle(const CMN_SimpleFifoPeekHandle *pPeekHandle, void *pDest, size_t sz)
Copy data pointed by PeekHandle using default copier(memcpy like).
int CMN_SimpleFifoInitialize(CMN_SimpleFifoHandle *pHandle, void *pFifoBuffer, size_t szFifoBuffer, void *pExtInfo)
Initialize FIFO.
Data handle used for CMN_SimpleFifoPeek().
Definition: CMN_SimpleFifo.h:101
size_t CMN_SimpleFifoGetDataSizeOfPeekHandle(const CMN_SimpleFifoPeekHandle *pPeekHandle)
Get total size of data in peek handle.
size_t m_rp
Read Pointer. Index of the m_pBuf.
Definition: CMN_SimpleFifo.h:83
size_t m_wp
Write Pointer. Index of the m_pBuf.
Definition: CMN_SimpleFifo.h:82
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)...
void CMN_SimpleFifoClear(CMN_SimpleFifoHandle *pHandle)
Reset the RP/WP of the FIFO.
size_t CMN_SimpleFifoOffer(CMN_SimpleFifoHandle *pHandle, const void *pElement, size_t sz)
Insert data to the FIFO using the default copier(memcpy like).
void * CMN_SimpleFifoGetExtInfo(const CMN_SimpleFifoHandle *pHandle)
Get the value of the ExtInfo set to the FIFO.