Projects/XPLAINBridge/Lib/LightweightRingBuff.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2010.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6       www.fourwalledcubicle.com
   7 */
   8
   9 /*
  10   Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *
  33  *  Ultra lightweight ring buffer, for fast insertion/deletion.
  34  */
  35
  36 #ifndef _ULW_RING_BUFF_H_
  37 #define _ULW_RING_BUFF_H_
  38
  39         /* Includes: */
  40                 #include <util/atomic.h>
  41
  42                 #include <stdint.h>
  43                 #include <stdbool.h>
  44
  45         /* Defines: */
  46                 /** Size of each ring buffer, in data elements - must be between 1 and 255. */
  47                 #define BUFFER_SIZE      255
  48
  49                 /** Type of data to store into the buffer. */
  50                 #define RingBuff_Data_t  uint8_t
  51
  52         /* Type Defines: */
  53                 /** Type define for a new ring buffer object. Buffers should be initialized via a call to
  54                  *  \ref RingBuffer_InitBuffer() before use.
  55                  */
  56                 typedef struct
  57                 {
  58                         RingBuff_Data_t  Buffer[BUFFER_SIZE]; /**< Internal ring buffer data, referenced by the buffer pointers. */
  59                         RingBuff_Data_t* In; /**< Current storage location in the circular buffer */
  60                         RingBuff_Data_t* Out; /**< Current retrieval location in the circular buffer */
  61                         uint8_t          Count; /**< Total number of bytes stored in the circular buffer */
  62                 } RingBuff_t;
  63
  64         /* Inline Functions: */
  65                 /** Initializes a ring buffer ready for use. Buffers must be initialized via this function
  66                  *  before any operations are called upon them. Already initialized buffers may be reset
  67                  *  by re-initializing them using this function.
  68                  *
  69                  *  \param[out] Buffer  Pointer to a ring buffer structure to initialize
  70                  */
  71                 static inline void RingBuffer_InitBuffer(RingBuff_t* const Buffer)
  72                 {
  73                         Buffer->In    = Buffer->Buffer;
  74                         Buffer->Out   = Buffer->Buffer;
  75                         Buffer->Count = 0;
  76                 }
  77
  78                 /** Atomically determines if the specified ring buffer contains any free space. This should
  79                  *  be tested before storing data to the buffer, to ensure that no data is lost due to a
  80                  *  buffer overrun.
  81                  *
  82                  *  \param[in,out] Buffer  Pointer to a ring buffer structure to insert into
  83                  *
  84                  *  \return Boolean true if the buffer contains no free space, false otherwise
  85                  */
  86                 static inline bool RingBuffer_IsFull(RingBuff_t* const Buffer)
  87                 {
  88                         bool IsFull;
  89
  90                         ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
  91                         {
  92                                 IsFull = (Buffer->Count == BUFFER_SIZE);
  93                         }
  94
  95                         return IsFull;
  96                 }
  97
  98                 /** Atomically inserts an element into the ring buffer.
  99                  *
 100                  *  \param[in,out] Buffer  Pointer to a ring buffer structure to insert into
 101                  *  \param[in]     Data    Data element to insert into the buffer
 102                  */
 103                 static inline void RingBuffer_AtomicInsert(RingBuff_t* const Buffer,
 104                                                            const RingBuff_Data_t Data)
 105                 {
 106                         ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
 107                         {
 108                                 *Buffer->In = Data;
 109
 110                                 if (++Buffer->In == &Buffer->Buffer[BUFFER_SIZE])
 111                                   Buffer->In = Buffer->Buffer;
 112
 113                                 Buffer->Count++;
 114                         }
 115                 }
 116
 117                 /** Atomically retrieves an element from the ring buffer.
 118                  *
 119                  *  \param[in,out] Buffer  Pointer to a ring buffer structure to retrieve from
 120                  *
 121                  *  \return Next data element stored in the buffer
 122                  */
 123                 static inline RingBuff_Data_t RingBuffer_AtomicRemove(RingBuff_t* const Buffer)
 124                 {
 125                         RingBuff_Data_t Data;
 126
 127                         ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
 128                         {
 129                                 Data = *Buffer->Out;
 130
 131                                 if (++Buffer->Out == &Buffer->Buffer[BUFFER_SIZE])
 132                                   Buffer->Out = Buffer->Buffer;
 133
 134                                 Buffer->Count--;
 135                         }
 136
 137                         return Data;
 138                 }
 139
 140                 /** Inserts an element into the ring buffer.
 141                  *
 142                  *  \param[in,out] Buffer  Pointer to a ring buffer structure to insert into
 143                  *  \param[in]     Data    Data element to insert into the buffer
 144                  */
 145                 static inline void RingBuffer_Insert(RingBuff_t* const Buffer,
 146                                                      const RingBuff_Data_t Data)
 147                 {
 148                         *Buffer->In = Data;
 149
 150                         if (++Buffer->In == &Buffer->Buffer[BUFFER_SIZE])
 151                           Buffer->In = Buffer->Buffer;
 152
 153                         Buffer->Count++;
 154                 }
 155
 156                 /** Retrieves an element from the ring buffer.
 157                  *
 158                  *  \param[in,out] Buffer  Pointer to a ring buffer structure to retrieve from
 159                  *
 160                  *  \return Next data element stored in the buffer
 161                  */
 162                 static inline RingBuff_Data_t RingBuffer_Remove(RingBuff_t* const Buffer)
 163                 {
 164                         RingBuff_Data_t Data = *Buffer->Out;
 165
 166                         if (++Buffer->Out == &Buffer->Buffer[BUFFER_SIZE])
 167                           Buffer->Out = Buffer->Buffer;
 168
 169                         Buffer->Count--;
 170
 171                         return Data;
 172                 }
 173
 174 #endif
 175