bertos/mware/fifobuf.h

   1 /**
   2  * \file
   3  * <!--
   4  * This file is part of BeRTOS.
   5  *
   6  * Bertos is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19  *
  20  * As a special exception, you may use this file as part of a free software
  21  * library without restriction.  Specifically, if other files instantiate
  22  * templates or use macros or inline functions from this file, or you compile
  23  * this file and link it with other files to produce an executable, this
  24  * file does not by itself cause the resulting executable to be covered by
  25  * the GNU General Public License.  This exception does not however
  26  * invalidate any other reasons why the executable file might be covered by
  27  * the GNU General Public License.
  28  *
  29  * Copyright 2003, 2004 Develer S.r.l. (http://www.develer.com/)
  30  * Copyright 2001 Bernardo Innocenti <bernie@develer.com>
  31  *
  32  * -->
  33  *
  34  * \version $Id$
  35  *
  36  * \author Bernardo Innocenti <bernie@develer.com>
  37  *
  38  * \brief General pourpose FIFO buffer implemented with a ring buffer
  39  *
  40  * \li \c begin points to the first buffer element;
  41  * \li \c end points to the last buffer element (unlike the STL convention);
  42  * \li \c head points to the element to be extracted next;
  43  * \li \c tail points to the location following the last insertion;
  44  * \li when any of the pointers advances beyond \c end, it is reset
  45  *     back to \c begin.
  46  *
  47  * \code
  48  *
  49  *  +-----------------------------------+
  50  *  |  empty  |   valid data   |  empty |
  51  *  +-----------------------------------+
  52  *  ^         ^                ^        ^
  53  *  begin    head             tail     end
  54  *
  55  * \endcode
  56  *
  57  * The buffer is EMPTY when \c head and \c tail point to the same location:
  58  *              \code head == tail \endcode
  59  *
  60  * The buffer is FULL when \c tail points to the location immediately
  61  * after \c head:
  62  *              \code tail == head - 1 \endcode
  63  *
  64  * The buffer is also FULL when \c tail points to the last buffer
  65  * location and head points to the first one:
  66  *              \code head == begin && tail == end \endcode
  67  */
  68
  69 #ifndef MWARE_FIFO_H
  70 #define MWARE_FIFO_H
  71
  72 #include <cpu/types.h>
  73 #include <cpu/irq.h>
  74 #include <cfg/debug.h>
  75
  76 typedef struct FIFOBuffer
  77 {
  78         unsigned char * volatile head;
  79         unsigned char * volatile tail;
  80         unsigned char *begin;
  81         unsigned char *end;
  82 } FIFOBuffer;
  83
  84
  85 #define ASSERT_VALID_FIFO(fifo) \
  86         ATOMIC( \
  87                 ASSERT((fifo)->head >= (fifo)->begin); \
  88                 ASSERT((fifo)->head <= (fifo)->end); \
  89                 ASSERT((fifo)->tail >= (fifo)->begin); \
  90                 ASSERT((fifo)->tail <= (fifo)->end); \
  91         )
  92
  93
  94 /**
  95  * Check whether the fifo is empty
  96  *
  97  * \note Calling fifo_isempty() is safe while a concurrent
  98  *       execution context is calling fifo_push() or fifo_pop()
  99  *       only if the CPU can atomically update a pointer
 100  *       (which the AVR and other 8-bit processors can't do).
 101  *
 102  * \sa fifo_isempty_locked
 103  */
 104 INLINE bool fifo_isempty(const FIFOBuffer *fb)
 105 {
 106         //ASSERT_VALID_FIFO(fb);
 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         //ASSERT_VALID_FIFO(fb);
 127         return
 128                 ((fb->head == fb->begin) && (fb->tail == fb->end))
 129                 || (fb->tail == fb->head - 1);
 130 }
 131
 132
 133 /**
 134  * Push a character on the fifo buffer.
 135  *
 136  * \note Calling \c fifo_push() on a full buffer is undefined.
 137  *       The caller must make sure the buffer has at least
 138  *       one free slot before calling this function.
 139  *
 140  * \note It is safe to call fifo_pop() and fifo_push() from
 141  *       concurrent contexts, unless the CPU can't update
 142  *       a pointer atomically (which the AVR and other 8-bit
 143  *       processors can't do).
 144  *
 145  * \sa fifo_push_locked
 146  */
 147 INLINE void fifo_push(FIFOBuffer *fb, unsigned char c)
 148 {
 149 #ifdef __MWERKS__
 150 #pragma interrupt called
 151 #endif
 152         //ASSERT_VALID_FIFO(fb);
 153
 154         /* Write at tail position */
 155         *(fb->tail) = c;
 156
 157         if (UNLIKELY(fb->tail == fb->end))
 158                 /* wrap tail around */
 159                 fb->tail = fb->begin;
 160         else
 161                 /* Move tail forward */
 162                 fb->tail++;
 163 }
 164
 165
 166 /**
 167  * Pop a character from the fifo buffer.
 168  *
 169  * \note Calling \c fifo_pop() on an empty buffer is undefined.
 170  *       The caller must make sure the buffer contains at least
 171  *       one character before calling this function.
 172  *
 173  * \note It is safe to call fifo_pop() and fifo_push() from
 174  *       concurrent contexts.
 175  */
 176 INLINE unsigned char fifo_pop(FIFOBuffer *fb)
 177 {
 178 #ifdef __MWERKS__
 179 #pragma interrupt called
 180 #endif
 181         //ASSERT_VALID_FIFO(fb);
 182
 183         if (UNLIKELY(fb->head == fb->end))
 184         {
 185                 /* wrap head around */
 186                 fb->head = fb->begin;
 187                 return *(fb->end);
 188         }
 189         else
 190                 /* move head forward */
 191                 return *(fb->head++);
 192 }
 193
 194
 195 /**
 196  * Make the fifo empty, discarding all its current contents.
 197  */
 198 INLINE void fifo_flush(FIFOBuffer *fb)
 199 {
 200         //ASSERT_VALID_FIFO(fb);
 201         fb->head = fb->tail;
 202 }
 203
 204
 205 #if CPU_REG_BITS >= CPU_BITS_PER_PTR
 206
 207         /*
 208          * 16/32bit CPUs that can update a pointer with a single write
 209          * operation, no need to disable interrupts.
 210          */
 211         #define fifo_isempty_locked(fb) fifo_isempty((fb))
 212         #define fifo_push_locked(fb, c) fifo_push((fb), (c))
 213         #define fifo_pop_locked(fb)     fifo_pop((fb))
 214         #define fifo_flush_locked(fb)   fifo_flush((fb))
 215
 216 #else /* CPU_REG_BITS < CPU_BITS_PER_PTR */
 217
 218         /**
 219          * Similar to fifo_isempty(), but with stronger guarantees for
 220          * concurrent access between user and interrupt code.
 221          *
 222          * \note This is actually only needed for 8-bit processors.
 223          *
 224          * \sa fifo_isempty()
 225          */
 226         INLINE bool fifo_isempty_locked(const FIFOBuffer *fb)
 227         {
 228                 bool result;
 229                 ATOMIC(result = fifo_isempty(fb));
 230                 return result;
 231         }
 232
 233
 234         /**
 235          * Similar to fifo_push(), but with stronger guarantees for
 236          * concurrent access between user and interrupt code.
 237          *
 238          * \note This is actually only needed for 8-bit processors.
 239          *
 240          * \sa fifo_push()
 241          */
 242         INLINE void fifo_push_locked(FIFOBuffer *fb, unsigned char c)
 243         {
 244                 ATOMIC(fifo_push(fb, c));
 245         }
 246
 247         /* Probably not really needed, but hard to prove. */
 248         INLINE unsigned char fifo_pop_locked(FIFOBuffer *fb)
 249         {
 250                 unsigned char c;
 251                 ATOMIC(c = fifo_pop(fb));
 252                 return c;
 253         }
 254
 255         /**
 256          * Similar to fifo_flush(), but with stronger guarantees for
 257          * concurrent access between user and interrupt code.
 258          *
 259          * \note This is actually only needed for 8-bit processors.
 260          *
 261          * \sa fifo_flush()
 262          */
 263         INLINE void fifo_flush_locked(FIFOBuffer *fb)
 264         {
 265                 ATOMIC(fifo_flush(fb));
 266         }
 267
 268 #endif /* CPU_REG_BITS < BITS_PER_PTR */
 269
 270
 271 /**
 272  * Thread safe version of fifo_isfull()
 273  */
 274 INLINE bool fifo_isfull_locked(const FIFOBuffer *_fb)
 275 {
 276         bool result;
 277         ATOMIC(result = fifo_isfull(_fb));
 278         return result;
 279 }
 280
 281
 282 /**
 283  * FIFO Initialization.
 284  */
 285 INLINE void fifo_init(FIFOBuffer *fb, unsigned char *buf, size_t size)
 286 {
 287         /* FIFO buffers have a known bug with 1-byte buffers. */
 288         ASSERT(size > 1);
 289
 290         fb->head = fb->tail = fb->begin = buf;
 291         fb->end = buf + size - 1;
 292 }
 293
 294 /**
 295  * \return Lenght of the FIFOBuffer \a fb.
 296  */
 297 INLINE size_t fifo_len(FIFOBuffer *fb)
 298 {
 299         return fb->end - fb->begin;
 300 }
 301
 302
 303 #if 0
 304
 305 /*
 306  * UNTESTED: if uncommented, to be moved in fifobuf.c
 307  */
 308 void fifo_pushblock(FIFOBuffer *fb, unsigned char *block, size_t len)
 309 {
 310         size_t freelen;
 311
 312         /* Se c'e' spazio da tail alla fine del buffer */
 313         if (fb->tail >= fb->head)
 314         {
 315                 freelen = fb->end - fb->tail + 1;
 316
 317                 /* C'e' abbastanza spazio per scrivere tutto il blocco? */
 318                 if (freelen < len)
 319                 {
 320                         /* Scrivi quello che entra fino alla fine del buffer */
 321                         memcpy(fb->tail, block, freelen);
 322                         block += freelen;
 323                         len -= freelen;
 324                         fb->tail = fb->begin;
 325                 }
 326                 else
 327                 {
 328                         /* Scrivi tutto il blocco */
 329                         memcpy(fb->tail, block, len);
 330                         fb->tail += len;
 331                         return;
 332                 }
 333         }
 334
 335         for(;;)
 336         {
 337                 while (!(freelen = fb->head - fb->tail - 1))
 338                         Delay(FIFO_POLLDELAY);
 339
 340                 /* C'e' abbastanza spazio per scrivere tutto il blocco? */
 341                 if (freelen < len)
 342                 {
 343                         /* Scrivi quello che entra fino alla fine del buffer */
 344                         memcpy(fb->tail, block, freelen);
 345                         block += freelen;
 346                         len -= freelen;
 347                         fb->tail += freelen;
 348                 }
 349                 else
 350                 {
 351                         /* Scrivi tutto il blocco */
 352                         memcpy(fb->tail, block, len);
 353                         fb->tail += len;
 354                         return;
 355                 }
 356         }
 357 }
 358 #endif
 359
 360 #endif /* MWARE_FIFO_H */
 361