fifo_flush_locked(): New function;

Revamp documentation.

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@74 38d2e660-2303-0410-9eaa-f027e97ec537

diff --git a/mware/fifobuf.h b/mware/fifobuf.h
index 8d7269f4b1e786f311716d959aec1a2c9be702fa..8da90c20dfa155dbf2af4ea95b175ed41844ab3f 100755 (executable)
--- a/mware/fifobuf.h
+++ b/mware/fifobuf.h
@@ -1,7 +1,7 @@
 /*!
  * \file
  * <!--
- * Copyright 2003,2004 Develer S.r.l. (http://www.develer.com/)
+ * Copyright 2003, 2004 Develer S.r.l. (http://www.develer.com/)
  * Copyright 2001 Bernardo Innocenti <bernie@develer.com>
  * This file is part of DevLib - See devlib/README for information.
  * -->
@@ -12,35 +12,41 @@
  *
  * \brief General pourpose FIFO buffer implemented with a ring buffer
  *
- * \li \c begin punta al primo elemento del buffer,
- * \li \c end punta all'ultimo elemento,
- * \li \c head punta al prossimo elemento che verra' estratto,
- * \li \c tail punta alla posizione successiva all'ultimo elemento inserito.
- * \li quando uno dei due puntatori raggiunge @c end, viene resettato a @c begin.
+ * \li \c begin points to the first buffer element;
+ * \li \c end points to the last buffer element (unlike the STL convention);
+ * \li \c head points to the element to be extracted next;
+ * \li \c tail points to the location following the last insertion;
+ * \li when any of the pointers advances beyond \c end, it is reset
+ *     back to \c begin.
  *
  * \code
  *
  *  +-----------------------------------+
- *  |  vuoto  |   dati validi  |  vuoto |
+ *  |  empty  |   valid data   |  empty |
  *  +-----------------------------------+
  *  ^         ^                ^        ^
  *  begin    head             tail     end
  *
  * \endcode
  *
- * Il buffer e' VUOTO quando head e tail coincidono:
+ * The buffer is EMPTY when \c head and \c tail point to the same location:
  *             \code head == tail \endcode
  *
- * Il buffer e' PIENO quando tail si trova immediatamente dietro a head:
+ * The buffer is FULL when \c tail points to the location immediately
+ * after \c head:
  *             \code tail == head - 1 \endcode
  *
- * Il buffer e' PIENO anche quando tail e' posizionato
- * sull'ultima posizione del buffer e head sulla prima:
+ * The buffer is also FULL when \c tail points to the last buffer
+ * location and head points to the first one:
  *             \code head == begin && tail == end \endcode
  */
 
 /*
  * $Log$
+ * Revision 1.9  2004/07/20 23:54:27  bernie
+ * fifo_flush_locked(): New function;
+ * Revamp documentation.
+ *
  * Revision 1.8  2004/07/20 23:47:39  bernie
  * Finally remove redundant protos.
  *
@@ -55,43 +61,6 @@
  *
  * Revision 1.4  2004/06/06 16:11:17  bernie
  * Protect MetroWerks specific pragmas with #ifdef's
- *
- * Revision 1.3  2004/06/03 15:04:10  aleph
- * Merge improvements from project_ks (mainly inlining)
- *
- * Revision 1.2  2004/06/03 11:27:09  bernie
- * Add dual-license information.
- *
- * Revision 1.1  2004/05/23 15:43:16  bernie
- * Import mware modules.
- *
- * Revision 1.3  2004/05/22 17:55:58  rasky
- * \samp non esiste in doxygen
- *
- * Revision 1.2  2004/04/27 11:13:29  rasky
- * Spostate tutte le definizioni CPU-specific da compiler.h nel nuovo file cpu.h
- *
- * Revision 1.1  2004/04/21 17:38:25  rasky
- * New application
- *
- * Revision 1.4  2004/03/24 15:37:03  bernie
- * Remove Copyright messages from Doxygen output
- *
- * Revision 1.3  2004/03/18 18:11:07  bernie
- * Add thread-safe FIFO handling macros
- *
- * Revision 1.2  2004/03/01 08:00:36  bernie
- * Fixes for Doxygen
- *
- * Revision 1.1  2003/12/07 04:04:20  bernie
- * Initial project_ks framework.
- *
- * Revision 1.1  2003/11/21 16:36:17  aleph
- * Rename from fifo to fifobuf to avoid conflict with BSP fifo.h header
- *
- * Revision 1.1  2003/11/20 22:17:41  aleph
- * Add fifo buffer used by serial
- *
  */
 
 #ifndef MWARE_FIFO_H
@@ -217,6 +186,7 @@ INLINE void fifo_flush(FIFOBuffer *fb)
        /* No tricks needed on 16/32bit CPUs */
 #      define fifo_isempty_locked(fb) fifo_isempty((fb))
 #      define fifo_push_locked(fb, c) fifo_push((fb), (c))
+#      define fifo_flush_locked(fb, c) fifo_flush((fb), (c))
 
 #else /* !__AVR__ */
 
@@ -242,7 +212,8 @@ INLINE void fifo_flush(FIFOBuffer *fb)
        /*!
         * Similar to fifo_push(), but with stronger guarantees for
         * concurrent access between user and interrupt code.
-        * This is actually only needed for 8-bit processors.
+        *
+        * \note This is actually only needed for 8-bit processors.
         *
         * \sa fifo_push()
         */
@@ -254,6 +225,22 @@ INLINE void fifo_flush(FIFOBuffer *fb)
                ENABLE_IRQRESTORE(flags);
        }
 
+       /*!
+        * Similar to fifo_flush(), but with stronger guarantees for
+        * concurrent access between user and interrupt code.
+        *
+        * \note This is actually only needed for 8-bit processors.
+        *
+        * \sa fifo_flush()
+        */
+       INLINE void fifo_flush_locked(FIFOBuffer *fb)
+       {
+               cpuflags_t flags;
+               DISABLE_IRQSAVE(flags);
+               fifo_flush(fb);
+               ENABLE_IRQRESTORE(flags);
+       }
+
 #endif /* !__AVR__ */
 
 
@@ -273,7 +260,6 @@ INLINE bool fifo_isfull_locked(const FIFOBuffer *_fb)
 }
 
 
-
 /*!
  * FIFO Initialization.
  */
@@ -284,7 +270,6 @@ INLINE void fifo_init(FIFOBuffer *fb, unsigned char *buf, size_t size)
 }
 
 
-
 #if 0
 
 /*