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 points to the first buffer element;
  16  * \li \c end points to the last buffer element (unlike the STL convention);
  17  * \li \c head points to the element to be extracted next;
  18  * \li \c tail points to the location following the last insertion;
  19  * \li when any of the pointers advances beyond \c end, it is reset
  20  *     back to \c begin.
  21  *
  22  * \code
  23  *
  24  *  +-----------------------------------+
  25  *  |  empty  |   valid data   |  empty |
  26  *  +-----------------------------------+
  27  *  ^         ^                ^        ^
  28  *  begin    head             tail     end
  29  *
  30  * \endcode
  31  *
  32  * The buffer is EMPTY when \c head and \c tail point to the same location:
  33  *              \code head == tail \endcode
  34  *
  35  * The buffer is FULL when \c tail points to the location immediately
  36  * after \c head:
  37  *              \code tail == head - 1 \endcode
  38  *
  39  * The buffer is also FULL when \c tail points to the last buffer
  40  * location and head points to the first one:
  41  *              \code head == begin && tail == end \endcode
  42  */
  43
  44 /*#*
  45  *#* $Log$
  46  *#* Revision 1.14  2004/08/25 14:12:09  rasky
  47  *#* Aggiornato il comment block dei log RCS
  48  *#*
  49  *#* Revision 1.13  2004/08/24 13:16:11  bernie
  50  *#* Add type-size definitions for preprocessor.
  51  *#*
  52  *#* Revision 1.12  2004/08/02 20:20:29  aleph
  53  *#* Merge from project_ks
  54  *#*
  55  *#* Revision 1.11  2004/07/30 14:15:53  rasky
  56  *#* Nuovo supporto unificato per detect della CPU
  57  *#*
  58  *#* Revision 1.10  2004/07/29 22:57:09  bernie
  59  *#* Doxygen fix.
  60  *#*
  61  *#* Revision 1.9  2004/07/20 23:54:27  bernie
  62  *#* fifo_flush_locked(): New function;
  63  *#* Revamp documentation.
  64  *#*
  65  *#* Revision 1.8  2004/07/20 23:47:39  bernie
  66  *#* Finally remove redundant protos.
  67  *#*
  68  *#* Revision 1.7  2004/07/20 23:46:29  bernie
  69  *#* Finally remove redundant protos.
  70  *#*
  71  *#* Revision 1.6  2004/06/06 17:18:04  bernie
  72  *#* Remove redundant declaration of fifo_isempty_locked().
  73  *#*
  74  *#* Revision 1.5  2004/06/06 16:50:35  bernie
  75  *#* Import fixes for race conditions from project_ks.
  76  *#*
  77  *#* Revision 1.4  2004/06/06 16:11:17  bernie
  78  *#* Protect MetroWerks specific pragmas with #ifdef's
  79  *#*/
  80
  81 #ifndef MWARE_FIFO_H
  82 #define MWARE_FIFO_H
  83
  84 #include "cpu.h"
  85
  86 typedef struct FIFOBuffer
  87 {
  88         unsigned char * volatile head;
  89         unsigned char * volatile tail;
  90         unsigned char *begin;
  91         unsigned char *end;
  92 } FIFOBuffer;
  93
  94
  95 /*!
  96  * Check whether the fifo is empty
  97  *
  98  * \note Calling fifo_isempty() is safe while a concurrent
  99  *       execution context is calling fifo_push() or fifo_pop()
 100  *       only if the CPU can atomically update a pointer
 101  *       (which the AVR and other 8-bit processors can't do).
 102  *
 103  * \sa fifo_isempty_locked
 104  */
 105 INLINE bool fifo_isempty(const FIFOBuffer *fb)
 106 {
 107         return fb->head == fb->tail;
 108 }
 109
 110
 111 /*!
 112  * Check whether the fifo is full
 113  *
 114  * \note Calling fifo_isfull() is safe while a concurrent
 115  *       execution context is calling fifo_pop() and the
 116  *       CPU can update a pointer atomically.
 117  *       It is NOT safe when the other context calls
 118  *       fifo_push().
 119  *       This limitation is not usually problematic in a
 120  *       consumer/producer scenario because the
 121  *       fifo_isfull() and fifo_push() are usually called
 122  *       in the producer context.
 123  */
 124 INLINE bool fifo_isfull(const FIFOBuffer *fb)
 125 {
 126         return
 127                 ((fb->head == fb->begin) && (fb->tail == fb->end))
 128                 || (fb->tail == fb->head - 1);
 129 }
 130
 131
 132 /*!
 133  * Pop a character from the fifo buffer.
 134  *
 135  * \note Calling \c fifo_push() on a full buffer is undefined.
 136  *       The caller must make sure the buffer has at least
 137  *       one free slot before calling this function.
 138  *
 139  * \note It is safe to call fifo_pop() and fifo_push() from
 140  *       concurrent contexts, unless the CPU can't update
 141  *       a pointer atomically (which the AVR and other 8-bit
 142  *       processors can't do).
 143  *
 144  * \sa fifo_push_locked
 145  */
 146 INLINE void fifo_push(FIFOBuffer *fb, unsigned char c)
 147 {
 148 #ifdef __MWERKS__
 149 #pragma interrupt called
 150 #endif
 151         /* Write at tail position */
 152         *(fb->tail) = c;
 153
 154         if (fb->tail == fb->end)
 155                 /* wrap tail around */
 156                 fb->tail = fb->begin;
 157         else
 158                 /* Move tail forward */
 159                 fb->tail++;
 160 }
 161
 162
 163 /*!
 164  * Pop a character from the fifo buffer.
 165  *
 166  * \note Calling \c fifo_pop() on an empty buffer is undefined.
 167  *       The caller must make sure the buffer contains at least
 168  *       one character before calling this function.
 169  *
 170  * \note It is safe to call fifo_pop() and fifo_push() from
 171  *       concurrent contexts.
 172  */
 173 INLINE unsigned char fifo_pop(FIFOBuffer *fb)
 174 {
 175 #ifdef __MWERKS__
 176 #pragma interrupt called
 177 #endif
 178         if (fb->head == fb->end)
 179         {
 180                 /* wrap head around */
 181                 fb->head = fb->begin;
 182                 return *(fb->end);
 183         }
 184         else
 185                 /* move head forward */
 186                 return *(fb->head++);
 187 }
 188
 189
 190 /*!
 191  * Make the fifo empty, discarding all its current contents.
 192  */
 193 INLINE void fifo_flush(FIFOBuffer *fb)
 194 {
 195         fb->head = fb->tail;
 196 }
 197
 198
 199 #if CPU_REG_BITS >= BITS_PER_PTR
 200
 201         /*
 202          * 16/32bit CPUs that can update a pointer with a single write
 203          * operation, no need to disable interrupts.
 204          */
 205         #define fifo_isempty_locked(fb) fifo_isempty((fb))
 206         #define fifo_push_locked(fb, c) fifo_push((fb), (c))
 207         #define fifo_flush_locked(fb) fifo_flush((fb))
 208
 209 #else /* CPU_REG_BITS < BITS_PER_PTR */
 210
 211         /*!
 212          * Similar to fifo_isempty(), but with stronger guarantees for
 213          * concurrent access between user and interrupt code.
 214          *
 215          * \note This is actually only needed for 8-bit processors.
 216          *
 217          * \sa fifo_isempty()
 218          */
 219         INLINE bool fifo_isempty_locked(const FIFOBuffer *fb)
 220         {
 221                 bool result;
 222                 cpuflags_t flags;
 223
 224                 DISABLE_IRQSAVE(flags);
 225                 result = fifo_isempty(fb);
 226                 ENABLE_IRQRESTORE(flags);
 227
 228                 return result;
 229         }
 230
 231
 232         /*!
 233          * Similar to fifo_push(), but with stronger guarantees for
 234          * concurrent access between user and interrupt code.
 235          *
 236          * \note This is actually only needed for 8-bit processors.
 237          *
 238          * \sa fifo_push()
 239          */
 240         INLINE void fifo_push_locked(FIFOBuffer *fb, unsigned char c)
 241         {
 242                 cpuflags_t flags;
 243                 DISABLE_IRQSAVE(flags);
 244                 fifo_push(fb, c);
 245                 ENABLE_IRQRESTORE(flags);
 246         }
 247
 248
 249         /*!
 250          * Similar to fifo_flush(), but with stronger guarantees for
 251          * concurrent access between user and interrupt code.
 252          *
 253          * \note This is actually only needed for 8-bit processors.
 254          *
 255          * \sa fifo_flush()
 256          */
 257         INLINE void fifo_flush_locked(FIFOBuffer *fb)
 258         {
 259                 cpuflags_t flags;
 260                 DISABLE_IRQSAVE(flags);
 261                 fifo_flush(fb);
 262                 ENABLE_IRQRESTORE(flags);
 263         }
 264
 265 #endif /* CPU_REG_BITS < BITS_PER_PTR */
 266
 267
 268 /*!
 269  * Thread safe version of fifo_isfull()
 270  */
 271 INLINE bool fifo_isfull_locked(const FIFOBuffer *_fb)
 272 {
 273         bool _result;
 274         cpuflags_t _flags;
 275
 276         DISABLE_IRQSAVE(_flags);
 277         _result = fifo_isfull(_fb);
 278         ENABLE_IRQRESTORE(_flags);
 279
 280         return _result;
 281 }
 282
 283
 284 /*!
 285  * FIFO Initialization.
 286  */
 287 INLINE void fifo_init(FIFOBuffer *fb, unsigned char *buf, size_t size)
 288 {
 289         fb->head = fb->tail = fb->begin = buf;
 290         fb->end = buf + size - 1;
 291 }
 292
 293
 294 #if 0
 295
 296 /*
 297  * UNTESTED: if uncommented, to be moved in fifobuf.c
 298  */
 299 void fifo_pushblock(FIFOBuffer *fb, unsigned char *block, size_t len)
 300 {
 301         size_t freelen;
 302
 303         /* Se c'e' spazio da tail alla fine del buffer */
 304         if (fb->tail >= fb->head)
 305         {
 306                 freelen = fb->end - fb->tail + 1;
 307
 308                 /* C'e' abbastanza spazio per scrivere tutto il blocco? */
 309                 if (freelen < len)
 310                 {
 311                         /* Scrivi quello che entra fino alla fine del buffer */
 312                         memcpy(fb->tail, block, freelen);
 313                         block += freelen;
 314                         len -= freelen;
 315                         fb->tail = fb->begin;
 316                 }
 317                 else
 318                 {
 319                         /* Scrivi tutto il blocco */
 320                         memcpy(fb->tail, block, len);
 321                         fb->tail += len;
 322                         return;
 323                 }
 324         }
 325
 326         for(;;)
 327         {
 328                 while (!(freelen = fb->head - fb->tail - 1))
 329                         Delay(FIFO_POLLDELAY);
 330
 331                 /* C'e' abbastanza spazio per scrivere tutto il blocco? */
 332                 if (freelen < len)
 333                 {
 334                         /* Scrivi quello che entra fino alla fine del buffer */
 335                         memcpy(fb->tail, block, freelen);
 336                         block += freelen;
 337                         len -= freelen;
 338                         fb->tail += freelen;
 339                 }
 340                 else
 341                 {
 342                         /* Scrivi tutto il blocco */
 343                         memcpy(fb->tail, block, len);
 344                         fb->tail += len;
 345                         return;
 346                 }
 347         }
 348 }
 349 #endif
 350
 351 #endif /* MWARE_FIFO_H */
 352