mware/fifobuf.h

   1 /*!
   2  * \file
   3  * <!--
   4  * Copyright 2003,2004 Develer S.r.l. (http://www.develer.com/)
   5  * Copyright 2001 Bernardo Innocenti <bernie@develer.com>
   6  * This file is part of DevLib - See devlib/README for information.
   7  * -->
   8  *
   9  * \version $Id$
  10  *
  11  * \author Bernardo Innocenti <bernie@develer.com>
  12  *
  13  * \brief General pourpose FIFO buffer implemented with a ring buffer
  14  *
  15  * \li \c begin punta al primo elemento del buffer,
  16  * \li \c end punta all'ultimo elemento,
  17  * \li \c head punta al prossimo elemento che verra' estratto,
  18  * \li \c tail punta alla posizione successiva all'ultimo elemento inserito.
  19  * \li quando uno dei due puntatori raggiunge @c end, viene resettato a @c begin.
  20  *
  21  * \code
  22  *
  23  *  +-----------------------------------+
  24  *  |  vuoto  |   dati validi  |  vuoto |
  25  *  +-----------------------------------+
  26  *  ^         ^                ^        ^
  27  *  begin    head             tail     end
  28  *
  29  * \endcode
  30  *
  31  * Il buffer e' VUOTO quando head e tail coincidono:
  32  *              \code head == tail \endcode
  33  *
  34  * Il buffer e' PIENO quando tail si trova immediatamente dietro a head:
  35  *              \code tail == head - 1 \endcode
  36  *
  37  * Il buffer e' PIENO anche quando tail e' posizionato
  38  * sull'ultima posizione del buffer e head sulla prima:
  39  *              \code head == begin && tail == end \endcode
  40  */
  41
  42 /*
  43  * $Log$
  44  * Revision 1.4  2004/06/06 16:11:17  bernie
  45  * Protect MetroWerks specific pragmas with #ifdef's
  46  *
  47  * Revision 1.3  2004/06/03 15:04:10  aleph
  48  * Merge improvements from project_ks (mainly inlining)
  49  *
  50  * Revision 1.2  2004/06/03 11:27:09  bernie
  51  * Add dual-license information.
  52  *
  53  * Revision 1.1  2004/05/23 15:43:16  bernie
  54  * Import mware modules.
  55  *
  56  * Revision 1.3  2004/05/22 17:55:58  rasky
  57  * \samp non esiste in doxygen
  58  *
  59  * Revision 1.2  2004/04/27 11:13:29  rasky
  60  * Spostate tutte le definizioni CPU-specific da compiler.h nel nuovo file cpu.h
  61  *
  62  * Revision 1.1  2004/04/21 17:38:25  rasky
  63  * New application
  64  *
  65  * Revision 1.4  2004/03/24 15:37:03  bernie
  66  * Remove Copyright messages from Doxygen output
  67  *
  68  * Revision 1.3  2004/03/18 18:11:07  bernie
  69  * Add thread-safe FIFO handling macros
  70  *
  71  * Revision 1.2  2004/03/01 08:00:36  bernie
  72  * Fixes for Doxygen
  73  *
  74  * Revision 1.1  2003/12/07 04:04:20  bernie
  75  * Initial project_ks framework.
  76  *
  77  * Revision 1.1  2003/11/21 16:36:17  aleph
  78  * Rename from fifo to fifobuf to avoid conflict with BSP fifo.h header
  79  *
  80  * Revision 1.1  2003/11/20 22:17:41  aleph
  81  * Add fifo buffer used by serial
  82  *
  83  */
  84
  85 #ifndef MWARE_FIFO_H
  86 #define MWARE_FIFO_H
  87
  88 #include "cpu.h"
  89
  90 typedef struct FIFOBuffer
  91 {
  92         unsigned char * volatile head;
  93         unsigned char * volatile tail;
  94         unsigned char *begin;
  95         unsigned char *end;
  96 } FIFOBuffer;
  97
  98
  99 /* Public function prototypes */
 100 INLINE bool fifo_isempty(const FIFOBuffer *fb);
 101 INLINE bool fifo_isempty_locked(const FIFOBuffer *fb);
 102 INLINE bool fifo_isfull(const FIFOBuffer *fb);
 103 INLINE bool fifo_isfull_locked(const FIFOBuffer *fb);
 104 #ifdef __MWERKS__
 105 #pragma interrupt called
 106 #endif
 107 INLINE void fifo_push(FIFOBuffer *fb, unsigned char c);
 108 #ifdef __MWERKS__
 109 #pragma interrupt called
 110 #endif
 111 INLINE unsigned char fifo_pop(FIFOBuffer *fb);
 112 INLINE void fifo_flush(FIFOBuffer *fb);
 113 INLINE void fifo_init(FIFOBuffer *fb, unsigned char *buf, size_t size);
 114
 115
 116 /*!
 117  * Check whether the fifo is empty
 118  *
 119  * \note Calling fifo_isempty() is safe while a concurrent
 120  *       execution context is calling fifo_push() or fifo_pop()
 121  *       only if the CPU can atomically update a pointer.
 122  */
 123 INLINE bool fifo_isempty(const FIFOBuffer *fb)
 124 {
 125         return fb->head == fb->tail;
 126 }
 127
 128
 129 /*!
 130  * Check whether the fifo is full
 131  *
 132  * \note Calling fifo_isfull() is safe while a concurrent
 133  *       execution context is calling fifo_pop() and the
 134  *       CPU can update a pointer atomically.
 135  *       It is NOT safe when the other context calls
 136  *       fifo_push().
 137  *       This limitation is not usually problematic in a
 138  *       consumer/producer scenario because the
 139  *       fifo_isfull() and fifo_push() are usually called
 140  *       in the producer context.
 141  */
 142 INLINE bool fifo_isfull(const FIFOBuffer *fb)
 143 {
 144         return
 145                 ((fb->head == fb->begin) && (fb->tail == fb->end))
 146                 || (fb->tail == fb->head - 1);
 147 }
 148
 149
 150 #if !defined(__AVR__)
 151
 152         /* No tricks needed on 16/32bit CPUs */
 153 #       define fifo_isempty_locked(fb) fifo_isempty((fb))
 154
 155 #else /* !__AVR__ */
 156
 157         INLINE bool fifo_isempty_locked(const FIFOBuffer *fb)
 158         {
 159                 bool result;
 160                 cpuflags_t flags;
 161
 162                 DISABLE_IRQSAVE(flags);
 163                 result = fifo_isempty(fb);
 164                 ENABLE_IRQRESTORE(flags);
 165
 166                 return result;
 167         }
 168
 169 #endif /* !__AVR__ */
 170
 171
 172 /*!
 173  * Thread safe version of fifo_isfull()
 174  */
 175 INLINE bool fifo_isfull_locked(const FIFOBuffer *_fb)
 176 {
 177         bool _result;
 178         cpuflags_t _flags;
 179
 180         DISABLE_IRQSAVE(_flags);
 181         _result = fifo_isfull(_fb);
 182         ENABLE_IRQRESTORE(_flags);
 183
 184         return _result;
 185 }
 186
 187
 188 /*!
 189  * Pop a character from the fifo buffer.
 190  *
 191  * \note Calling \c fifo_push() on a full buffer is undefined.
 192  *       The caller must make sure the buffer has at least
 193  *       one free slot before calling this function.
 194  *
 195  * \note It is safe to call fifo_pop() and fifo_push() from
 196  *       concurrent contexts.
 197  */
 198 INLINE void fifo_push(FIFOBuffer *fb, unsigned char c)
 199 {
 200         /* Write at tail position */
 201         *(fb->tail) = c;
 202
 203         if (fb->tail == fb->end)
 204                 /* wrap tail around */
 205                 fb->tail = fb->begin;
 206         else
 207                 /* Move tail forward */
 208                 fb->tail++;
 209 }
 210
 211
 212 /*!
 213  * Pop a character from the fifo buffer.
 214  *
 215  * \note Calling \c fifo_pop() on an empty buffer is undefined.
 216  *       The caller must make sure the buffer contains at least
 217  *       one character before calling this function.
 218  *
 219  * \note It is safe to call fifo_pop() and fifo_push() from
 220  *       concurrent contexts.
 221  */
 222 INLINE unsigned char fifo_pop(FIFOBuffer *fb)
 223 {
 224         if (fb->head == fb->end)
 225         {
 226                 /* wrap head around */
 227                 fb->head = fb->begin;
 228                 return *(fb->end);
 229         }
 230         else
 231                 /* move head forward */
 232                 return *(fb->head++);
 233 }
 234
 235
 236 /*!
 237  * Make the fifo empty, discarding all its current contents.
 238  */
 239 INLINE void fifo_flush(FIFOBuffer *fb)
 240 {
 241         fb->head = fb->tail;
 242 }
 243
 244
 245 /*!
 246  * FIFO Initialization.
 247  */
 248 INLINE void fifo_init(FIFOBuffer *fb, unsigned char *buf, size_t size)
 249 {
 250         fb->head = fb->tail = fb->begin = buf;
 251         fb->end = buf + size - 1;
 252 }
 253
 254
 255
 256 #if 0
 257
 258 /*
 259  * UNTESTED: if uncommented, to be moved in fifobuf.c
 260  */
 261 void fifo_pushblock(FIFOBuffer *fb, unsigned char *block, size_t len)
 262 {
 263         size_t freelen;
 264
 265         /* Se c'e' spazio da tail alla fine del buffer */
 266         if (fb->tail >= fb->head)
 267         {
 268                 freelen = fb->end - fb->tail + 1;
 269
 270                 /* C'e' abbastanza spazio per scrivere tutto il blocco? */
 271                 if (freelen < len)
 272                 {
 273                         /* Scrivi quello che entra fino alla fine del buffer */
 274                         memcpy(fb->tail, block, freelen);
 275                         block += freelen;
 276                         len -= freelen;
 277                         fb->tail = fb->begin;
 278                 }
 279                 else
 280                 {
 281                         /* Scrivi tutto il blocco */
 282                         memcpy(fb->tail, block, len);
 283                         fb->tail += len;
 284                         return;
 285                 }
 286         }
 287
 288         for(;;)
 289         {
 290                 while (!(freelen = fb->head - fb->tail - 1))
 291                         Delay(FIFO_POLLDELAY);
 292
 293                 /* C'e' abbastanza spazio per scrivere tutto il blocco? */
 294                 if (freelen < len)
 295                 {
 296                         /* Scrivi quello che entra fino alla fine del buffer */
 297                         memcpy(fb->tail, block, freelen);
 298                         block += freelen;
 299                         len -= freelen;
 300                         fb->tail += freelen;
 301                 }
 302                 else
 303                 {
 304                         /* Scrivi tutto il blocco */
 305                         memcpy(fb->tail, block, len);
 306                         fb->tail += len;
 307                         return;
 308                 }
 309         }
 310 }
 311 #endif
 312
 313 #endif /* MWARE_FIFO_H */
 314