Developer World
Spresense SDK Library v3.2.0-ebc0364
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
78typedef 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
101typedef struct {
102 uint8_t* m_pChunk[2];
103 size_t m_szChunk[2];
105
123typedef 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
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
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
490static 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
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_SimpleFifoGetDataSizeOfPeekHandle(const CMN_SimpleFifoPeekHandle *pPeekHandle)
Get total size of data in peek handle.
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_SimpleFifoCopyFromPeekHandleWithSpecificCopier(const CMN_SimpleFifoPeekHandle *pPeekHandle, void *pDest, size_t sz, CMN_SimpleFifoCopierFunc copierFunc, void *pCopierFuncExtInfo)
Copy data pointed by PeekHandle using specific copier.
void *(* CMN_SimpleFifoCopierFunc)(void *pCopierFuncExtInfo, void *pDest, const void *pSrc, size_t sz)
Definition of data copier function.
Definition: CMN_SimpleFifo.h:123
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)...
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_SimpleFifoCopyFromPeekHandle(const CMN_SimpleFifoPeekHandle *pPeekHandle, void *pDest, size_t sz)
Copy data pointed by PeekHandle using default copier(memcpy like).
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_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.
void CMN_SimpleFifoClear(CMN_SimpleFifoHandle *pHandle)
Reset the RP/WP of the FIFO.
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).
int CMN_SimpleFifoInitialize(CMN_SimpleFifoHandle *pHandle, void *pFifoBuffer, size_t szFifoBuffer, void *pExtInfo)
Initialize FIFO.
size_t CMN_SimpleFifoGetVacantSize(const CMN_SimpleFifoHandle *pHandle)
Get vacant size of the FIFO.
size_t CMN_SimpleFifoGetOccupiedSize(const CMN_SimpleFifoHandle *pHandle)
Get occupied size of the FIFO.
void * CMN_SimpleFifoGetExtInfo(const CMN_SimpleFifoHandle *pHandle)
Get the value of the ExtInfo set to 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).
size_t m_rp
Read Pointer. Index of the m_pBuf.
Definition: CMN_SimpleFifo.h:83
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
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
uint8_t * m_pBuf
Internal ring buffer.
Definition: CMN_SimpleFifo.h:79
size_t m_wp
Write Pointer. Index of the m_pBuf.
Definition: CMN_SimpleFifo.h:82
FIFO handle which holds data required to manipulate FIFO.
Definition: CMN_SimpleFifo.h:78
Data handle used for CMN_SimpleFifoPeek().
Definition: CMN_SimpleFifo.h:101