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