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.6  2004/06/06 17:18:04  bernie
  45  * Remove redundant declaration of fifo_isempty_locked().
  46  *
  47  * Revision 1.5  2004/06/06 16:50:35  bernie
  48  * Import fixes for race conditions from project_ks.
  49  *
  50  * Revision 1.4  2004/06/06 16:11:17  bernie
  51  * Protect MetroWerks specific pragmas with #ifdef's
  52  *
  53  * Revision 1.3  2004/06/03 15:04:10  aleph
  54  * Merge improvements from project_ks (mainly inlining)
  55  *
  56  * Revision 1.2  2004/06/03 11:27:09  bernie
  57  * Add dual-license information.
  58  *
  59  * Revision 1.1  2004/05/23 15:43:16  bernie
  60  * Import mware modules.
  61  *
  62  * Revision 1.3  2004/05/22 17:55:58  rasky
  63  * \samp non esiste in doxygen
  64  *
  65  * Revision 1.2  2004/04/27 11:13:29  rasky
  66  * Spostate tutte le definizioni CPU-specific da compiler.h nel nuovo file cpu.h
  67  *
  68  * Revision 1.1  2004/04/21 17:38:25  rasky
  69  * New application
  70  *
  71  * Revision 1.4  2004/03/24 15:37:03  bernie
  72  * Remove Copyright messages from Doxygen output
  73  *
  74  * Revision 1.3  2004/03/18 18:11:07  bernie
  75  * Add thread-safe FIFO handling macros
  76  *
  77  * Revision 1.2  2004/03/01 08:00:36  bernie
  78  * Fixes for Doxygen
  79  *
  80  * Revision 1.1  2003/12/07 04:04:20  bernie
  81  * Initial project_ks framework.
  82  *
  83  * Revision 1.1  2003/11/21 16:36:17  aleph
  84  * Rename from fifo to fifobuf to avoid conflict with BSP fifo.h header
  85  *
  86  * Revision 1.1  2003/11/20 22:17:41  aleph
  87  * Add fifo buffer used by serial
  88  *
  89  */
  90
  91 #ifndef MWARE_FIFO_H
  92 #define MWARE_FIFO_H
  93
  94 #include "cpu.h"
  95
  96 typedef struct FIFOBuffer
  97 {
  98         unsigned char * volatile head;
  99         unsigned char * volatile tail;
 100         unsigned char *begin;
 101         unsigned char *end;
 102 } FIFOBuffer;
 103
 104
 105 /* Public function prototypes */
 106 INLINE bool fifo_isempty(const FIFOBuffer *fb);
 107 INLINE bool fifo_isfull(const FIFOBuffer *fb);
 108 INLINE bool fifo_isfull_locked(const FIFOBuffer *fb);
 109 #ifdef __MWERKS__
 110 #pragma interrupt called
 111 #endif
 112 INLINE void fifo_push(FIFOBuffer *fb, unsigned char c);
 113 #ifdef __MWERKS__
 114 #pragma interrupt called
 115 #endif
 116 INLINE unsigned char fifo_pop(FIFOBuffer *fb);
 117 INLINE void fifo_flush(FIFOBuffer *fb);
 118 INLINE void fifo_init(FIFOBuffer *fb, unsigned char *buf, size_t size);
 119
 120
 121 /*!
 122  * Check whether the fifo is empty
 123  *
 124  * \note Calling fifo_isempty() is safe while a concurrent
 125  *       execution context is calling fifo_push() or fifo_pop()
 126  *       only if the CPU can atomically update a pointer
 127  *       (which the AVR and other 8-bit processors can't do).
 128  *
 129  * \sa fifo_isempty_locked
 130  */
 131 INLINE bool fifo_isempty(const FIFOBuffer *fb)
 132 {
 133         return fb->head == fb->tail;
 134 }
 135
 136
 137 /*!
 138  * Check whether the fifo is full
 139  *
 140  * \note Calling fifo_isfull() is safe while a concurrent
 141  *       execution context is calling fifo_pop() and the
 142  *       CPU can update a pointer atomically.
 143  *       It is NOT safe when the other context calls
 144  *       fifo_push().
 145  *       This limitation is not usually problematic in a
 146  *       consumer/producer scenario because the
 147  *       fifo_isfull() and fifo_push() are usually called
 148  *       in the producer context.
 149  */
 150 INLINE bool fifo_isfull(const FIFOBuffer *fb)
 151 {
 152         return
 153                 ((fb->head == fb->begin) && (fb->tail == fb->end))
 154                 || (fb->tail == fb->head - 1);
 155 }
 156
 157
 158 /*!
 159  * Pop a character from the fifo buffer.
 160  *
 161  * \note Calling \c fifo_push() on a full buffer is undefined.
 162  *       The caller must make sure the buffer has at least
 163  *       one free slot before calling this function.
 164  *
 165  * \note It is safe to call fifo_pop() and fifo_push() from
 166  *       concurrent contexts, unless the CPU can't update
 167  *       a pointer atomically (which the AVR and other 8-bit
 168  *       processors can't do).
 169  *
 170  * \sa fifo_push_locked
 171  */
 172 INLINE void fifo_push(FIFOBuffer *fb, unsigned char c)
 173 {
 174         /* Write at tail position */
 175         *(fb->tail) = c;
 176
 177         if (fb->tail == fb->end)
 178                 /* wrap tail around */
 179                 fb->tail = fb->begin;
 180         else
 181                 /* Move tail forward */
 182                 fb->tail++;
 183 }
 184
 185
 186 /*!
 187  * Pop a character from the fifo buffer.
 188  *
 189  * \note Calling \c fifo_pop() on an empty buffer is undefined.
 190  *       The caller must make sure the buffer contains at least
 191  *       one character before calling this function.
 192  *
 193  * \note It is safe to call fifo_pop() and fifo_push() from
 194  *       concurrent contexts.
 195  */
 196 INLINE unsigned char fifo_pop(FIFOBuffer *fb)
 197 {
 198         if (fb->head == fb->end)
 199         {
 200                 /* wrap head around */
 201                 fb->head = fb->begin;
 202                 return *(fb->end);
 203         }
 204         else
 205                 /* move head forward */
 206                 return *(fb->head++);
 207 }
 208
 209
 210 /*!
 211  * Make the fifo empty, discarding all its current contents.
 212  */
 213 INLINE void fifo_flush(FIFOBuffer *fb)
 214 {
 215         fb->head = fb->tail;
 216 }
 217
 218
 219 #if !defined(__AVR__)
 220
 221         /* No tricks needed on 16/32bit CPUs */
 222 #       define fifo_isempty_locked(fb) fifo_isempty((fb))
 223 #       define fifo_push_locked(fb, c) fifo_push((fb), (c))
 224
 225 #else /* !__AVR__ */
 226
 227         /*!
 228          * Similar to fifo_isempty(), but with stronger guarantees for
 229          * concurrent access between user and interrupt code.
 230          * This is actually only needed for 8-bit processors.
 231          *
 232          * \sa fifo_isempty()
 233          */
 234         INLINE bool fifo_isempty_locked(const FIFOBuffer *fb);
 235         INLINE bool fifo_isempty_locked(const FIFOBuffer *fb)
 236         {
 237                 bool result;
 238                 cpuflags_t flags;
 239
 240                 DISABLE_IRQSAVE(flags);
 241                 result = fifo_isempty(fb);
 242                 ENABLE_IRQRESTORE(flags);
 243
 244                 return result;
 245         }
 246
 247         /*!
 248          * Similar to fifo_push(), but with stronger guarantees for
 249          * concurrent access between user and interrupt code.
 250          * This is actually only needed for 8-bit processors.
 251          *
 252          * \sa fifo_push()
 253          */
 254         INLINE void fifo_push_locked(FIFOBuffer *fb, unsigned char c);
 255         INLINE void fifo_push_locked(FIFOBuffer *fb, unsigned char c)
 256         {
 257                 cpuflags_t flags;
 258                 DISABLE_IRQSAVE(flags);
 259                 fifo_push(fb, c);
 260                 ENABLE_IRQRESTORE(flags);
 261         }
 262
 263 #endif /* !__AVR__ */
 264
 265
 266 /*!
 267  * Thread safe version of fifo_isfull()
 268  */
 269 INLINE bool fifo_isfull_locked(const FIFOBuffer *_fb)
 270 {
 271         bool _result;
 272         cpuflags_t _flags;
 273
 274         DISABLE_IRQSAVE(_flags);
 275         _result = fifo_isfull(_fb);
 276         ENABLE_IRQRESTORE(_flags);
 277
 278         return _result;
 279 }
 280
 281
 282
 283 /*!
 284  * FIFO Initialization.
 285  */
 286 INLINE void fifo_init(FIFOBuffer *fb, unsigned char *buf, size_t size)
 287 {
 288         fb->head = fb->tail = fb->begin = buf;
 289         fb->end = buf + size - 1;
 290 }
 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