components/common/inc/fifo.h

   1 /******************************************************************************
   2  @file fifo.h
   3
   4  @brief TIMAC 2.0 API generic fifo interface
   5
   6  Group: WCS LPC
   7  $Target Devices: Linux: AM335x, Embedded Devices: CC1310, CC1350, CC1352$
   8
   9  ******************************************************************************
  10  $License: BSD3 2016 $
  11
  12    Copyright (c) 2015, Texas Instruments Incorporated
  13    All rights reserved.
  14
  15    Redistribution and use in source and binary forms, with or without
  16    modification, are permitted provided that the following conditions
  17    are met:
  18
  19    *  Redistributions of source code must retain the above copyright
  20       notice, this list of conditions and the following disclaimer.
  21
  22    *  Redistributions in binary form must reproduce the above copyright
  23       notice, this list of conditions and the following disclaimer in the
  24       documentation and/or other materials provided with the distribution.
  25
  26    *  Neither the name of Texas Instruments Incorporated nor the names of
  27       its contributors may be used to endorse or promote products derived
  28       from this software without specific prior written permission.
  29
  30    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  31    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  32    THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  33    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  34    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  35    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  36    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  37    OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  38    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  39    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  40    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41  ******************************************************************************
  42  $Release Name: TI-15.4Stack Linux x64 SDK$
  43  $Release Date: Sept 27, 2017 (2.04.00.13)$
  44  *****************************************************************************/
  45
  46 #if !defined(FIFO_H)
  47 #define FIFO_H
  48
  49 /** ============================================================================
  50  *  Overview
  51  *  ========
  52  *
  53  *  This impliments the classic FIFO data structure.
  54  *
  55  *  ============================================================================
  56  */
  57
  58 #include <stdint.h>
  59 #include <stdbool.h>
  60 #include <stddef.h>
  61
  62 #ifdef __cplusplus
  63 extern "C"
  64 {
  65 #endif
  66
  67 /*!
  68  * @brief create a fifo
  69  *
  70  * @param name       - usable string for debug purposes.
  71  * @param item_size  - size of 1 item in the fifo
  72  * @param fifo_depth - how deep (in items) is the fifo
  73  * @param use_mutex  - if true, a mutex will be allocated to protect this fifo.
  74  *
  75  * @return success: non-zero handle upon success.
  76  */
  77 intptr_t FIFO_create(const char *name,
  78                       size_t item_size,
  79                       size_t fifo_depth,
  80                       bool use_mutex);
  81
  82 /*!
  83  * @brief Destroy a fifo
  84  *
  85  * @param h - handle returned by FIFO_create()
  86  *
  87  */
  88 void FIFO_destroy(intptr_t h);
  89
  90 /*!
  91  * @brief stdio library style fgetc() function for a fifo.
  92  *
  93  * @param h - the fifo handle returned by FIFO_create()
  94  *
  95  * @return EOF (when empty), or the unsigned char returned as an integer
  96  *
  97  * Note: This assumes the underlying item_size is 1 byte
  98  */
  99 int FIFO_fgetc(intptr_t h);
 100
 101 /*!
 102  * @brief stdio library style fputc() function for a fifo.
 103  *
 104  * @param c - the byte to write
 105  * @param h - the fifo handle returned by FIFO_create()
 106  *
 107  * @return -1 on error, or the unsigned byte cast to an integer
 108  *
 109  * Note: This assumes the underlying item_size is 1 byte
 110  */
 111 int FIFO_fputc(int c, intptr_t h);
 112
 113 /*!
 114  * @brief How many items can be put into the FIFO?
 115  *
 116  * @param h - the fifo handle returned by FIFO_create()
 117  *
 118  * @returns negative on error(invalid handle), or 0..fifo_depth
 119  */
 120 int FIFO_getSpaceAvail(intptr_t h);
 121
 122 /*!
 123  * @brief How many items are in the fifo already
 124  *
 125  * @param h - the fifo handle returned by FIFO_create()
 126  *
 127  * @returns negative on error(invalid handle), or 0..fifo_depth
 128  */
 129 int FIFO_getItemsAvail(intptr_t h);
 130
 131 /*!
 132  * @brief Insert items (n) into the fifo
 133  *
 134  * @param h - the fifo handle returned by FIFO_create()
 135  * @param pDdata - pointer to the data to insert
 136  * @param cnt    - number of items
 137  *
 138  * @returns negative on error (invalid handle), or 0..actual inserted
 139  *
 140  * This is equal to: FIFO_insertWithTimeout(h, pData, cnt, 0);
 141  */
 142 int    FIFO_insert(intptr_t h, const void *pData, size_t cnt);
 143
 144 /*!
 145  * @brief Insert items (n) into the fifo with timeout
 146  *
 147  * @param h - the fifo handle returned by FIFO_create()
 148  * @param pDdata - pointer to the data to insert
 149  * @param cnt    - number of items
 150  * @param timeout_mSecs - timeout (wait for spae)
 151  *
 152  * @returns negative on error (invalid handle), or 0..actual inserted
 153  */
 154 int FIFO_insertWithTimeout(intptr_t h,
 155                             const void *pData,
 156                             size_t cnt,
 157                             int timeout_mSecs);
 158
 159 /*!
 160  * @brief Remove items (n) from the fifo
 161  *
 162  * @param h - the fifo handle returned by FIFO_create()
 163  * @param pDdata - items will be placed herepointer to the data to insert
 164  * @param cnt    - number of items
 165  *
 166  * @returns negative on error (invalid handle), or 0..actual removed
 167  *
 168  * This is equal to: FIFO_removeWithTimeout(h, pData, cnt, 0);
 169  */
 170 int    FIFO_remove(intptr_t h, void *pdata, size_t cnt);
 171
 172 /*!
 173  * @brief Remove items (n) from the fifo
 174  *
 175  * @param h - the fifo handle returned by FIFO_create()
 176  * @param pDdata - items will be placed herepointer to the data to insert
 177  * @param cnt    - number of items
 178  * @param timeout_mSecs - timeout in miliseconds
 179  *
 180  * @returns negative on error (invalid handle), or 0..actual removed
 181  *
 182  */
 183 int    FIFO_removeWithTimeout(intptr_t h,
 184                                void *pdata,
 185                                size_t cnt,
 186                                int timeout_mSecs);
 187
 188 /*!
 189  * @brief Get parameters to support zero-copy into fifo (for example DMA usage)
 190  *
 191  * @param h - the fifo handle returned by FIFO_create()
 192  * @param ppData - pointer-pointer for the data transfer pointer
 193  * @param item_count - pointer to the count of items that can be removed
 194  * @param item_size  - how big each item is
 195  *
 196  * @returns negative if handle is invalid.
 197  *
 198  * Example:
 199  * \code
 200  *      // In the DMA start-transfer, do this:
 201  *      FIFO_insertDMA_setup(h, &pBuf, &n, &s);
 202  *
 203  *      // Presumably a DMA hardware would do this
 204  *      nbytes = n * s;
 205  *      while(nbytes){
 206  *         UART_putc(*pBuf);
 207  *         pBuf++;
 208  *         nbytes--;
 209  *      }
 210  *
 211  *      // the dma end-of-transfer interrupt would do this
 212  *      FIFO_insertDMA_update(h, n);
 213  * \endcode
 214  */
 215 int  FIFO_insertDMA_setup(intptr_t h,
 216                            void **pData,
 217                            size_t *item_count,
 218                            size_t *item_size);
 219
 220 /*!
 221  * @brief Called affter DMA insert operation is complete, updates the fifo
 222  *
 223  * @param h - the fifo handle returned by FIFO_create()
 224  * @param actual - the actual count transfered
 225  *
 226  * Note: If the actual count is zero this function can be optionally skipped.
 227  *
 228  */
 229 void FIFO_insertDMA_update(intptr_t h, size_t actual);
 230
 231 /*!
 232  * @brief Get parameters to suppor zero-copy from fifo (for example DMA usage)
 233  *
 234  * @param h - the fifo handle returned by FIFO_create()
 235  * @param ppData - pointer-pointer for the data transfer pointer
 236  * @param item_count - pointer to the count of items that can be inserted
 237  * @param item_size  - how big each item is
 238  *
 239  * @returns negative if handle is invalid.
 240  *
 241  * Example:
 242  * \code
 243  *      // In the DMA start start transfer, do this:
 244  *      FIFO_removeDMA_setup(h, &pBuf, &n, &s);
 245  *
 246  *      // Presumably a DMA hardware would do this
 247  *      nbytes = n * s;
 248  *      while(nbytes){
 249  *         *pBuf = UART_GetByte()
 250  *         pBuf++;
 251  *         nbytes--;
 252  *      }
 253  *
 254  *      // the dma end-of-transfer interrupt would do this
 255  *      FIFO_insertDMA_update(h, n);
 256  * \endcode
 257  */
 258 int  FIFO_removeDMA_setup(intptr_t h,
 259                            void **pData,
 260                            size_t *item_count,
 261                            size_t *item_size);
 262
 263 /*!
 264  * @brief Called affter DMA Remove operation is complete; updates the fifo
 265  *
 266  * @param h - the fifo handle returned by FIFO_create()
 267  * @param actual - the actual count transfered
 268  *
 269  * Note: If the actual count is zero this function can be optionally skipped.
 270  */
 271 void FIFO_removeDMA_update(intptr_t h, size_t actual);
 272
 273 /*!
 274  * @brief Wait for data to inserted into the fifo
 275  * @param h - fifo handle from FIFO_create() with mutex = true
 276  * @param mSec_timeout - how long to wait.
 277  * @returns negative on error, 0(timeout) postive you should check the fifo.
 278  */
 279 int FIFO_waitForInsert(intptr_t h, int mSec_timeout);
 280
 281 /*!
 282  * @brief Wait for data to be removed
 283  * @param h - fifo handle from FIFO_create() with mutex = true
 284  * @param mSec_timeout - how long to wait.
 285  * @returns negative on error, 0(timeout) postive you should check the fifo.
 286  */
 287 int FIFO_waitForRemove(intptr_t h, int mSec_timeout);
 288
 289 #ifdef __cplusplus
 290 }
 291 #endif
 292
 293 #endif
 294
 295 /*
 296  *  ========================================
 297  *  Texas Instruments Micro Controller Style
 298  *  ========================================
 299  *  Local Variables:
 300  *  mode: c
 301  *  c-file-style: "bsd"
 302  *  tab-width: 4
 303  *  c-basic-offset: 4
 304  *  indent-tabs-mode: nil
 305  *  End:
 306  *  vim:set  filetype=c tabstop=4 shiftwidth=4 expandtab=true
 307  */
 308