Rev 1145 Rev 1858
1 /*! \file buffer.h \brief Multipurpose byte buffer structure and methods. */ 1 /*! \file buffer.h \brief Multipurpose byte buffer structure and methods. */
2 //***************************************************************************** 2 //*****************************************************************************
3 // 3 //
4 // File Name : 'buffer.h' 4 // File Name : 'buffer.h'
5 // Title : Multipurpose byte buffer structure and methods 5 // Title : Multipurpose byte buffer structure and methods
6 // Author : Pascal Stang - Copyright (C) 2001-2002 6 // Author : Pascal Stang - Copyright (C) 2001-2002
7 // Created : 9/23/2001 7 // Created : 9/23/2001
8 // Revised : 11/16/2002 8 // Revised : 11/16/2002
9 // Version : 1.1 9 // Version : 1.1
10 // Target MCU : any 10 // Target MCU : any
11 // Editor Tabs : 4 11 // Editor Tabs : 4
12 // 12 //
13 /// \ingroup general 13 /// \ingroup general
14 /// \defgroup buffer Circular Byte-Buffer Structure and Function Library (buffer.c) 14 /// \defgroup buffer Circular Byte-Buffer Structure and Function Library (buffer.c)
15 /// \code #include "buffer.h" \endcode 15 /// \code #include "buffer.h" \endcode
16 /// \par Overview 16 /// \par Overview
17 /// This byte-buffer structure provides an easy and efficient way to store 17 /// This byte-buffer structure provides an easy and efficient way to store
18 /// and process a stream of bytes.  You can create as many buffers as you 18 /// and process a stream of bytes.  You can create as many buffers as you
19 /// like (within memory limits), and then use this common set of functions to 19 /// like (within memory limits), and then use this common set of functions to
20 /// access each buffer.  The buffers are designed for FIFO operation (first 20 /// access each buffer.  The buffers are designed for FIFO operation (first
21 /// in, first out).  This means that the first byte you put in the buffer 21 /// in, first out).  This means that the first byte you put in the buffer
22 /// will be the first one you get when you read out the buffer.  Supported 22 /// will be the first one you get when you read out the buffer.  Supported
23 /// functions include buffer initialize, get byte from front of buffer, add 23 /// functions include buffer initialize, get byte from front of buffer, add
24 /// byte to end of buffer, check if buffer is full, and flush buffer.  The 24 /// byte to end of buffer, check if buffer is full, and flush buffer.  The
25 /// buffer uses a circular design so no copying of data is ever necessary. 25 /// buffer uses a circular design so no copying of data is ever necessary.
26 /// This buffer is not dynamically allocated, it has a user-defined fixed 26 /// This buffer is not dynamically allocated, it has a user-defined fixed
27 /// maximum size.  This buffer is used in many places in the avrlib code. 27 /// maximum size.  This buffer is used in many places in the avrlib code.
28 // 28 //
29 // This code is distributed under the GNU Public License 29 // This code is distributed under the GNU Public License
30 // which can be found at http://www.gnu.org/licenses/gpl.txt 30 // which can be found at http://www.gnu.org/licenses/gpl.txt
31 // 31 //
32 //***************************************************************************** 32 //*****************************************************************************
33 //@{ 33 //@{
34   34  
35 #ifndef BUFFER_H 35 #ifndef BUFFER_H
36 #define BUFFER_H 36 #define BUFFER_H
37   37  
38 // structure/typdefs 38 // structure/typdefs
39   39  
40 //! cBuffer structure 40 //! cBuffer structure
41 typedef struct struct_cBuffer 41 typedef struct struct_cBuffer
42 { 42 {
43 unsigned char *dataptr; ///< the physical memory address where the buffer is stored 43 unsigned char *dataptr; ///< the physical memory address where the buffer is stored
44 unsigned short size; ///< the allocated size of the buffer 44 unsigned short size; ///< the allocated size of the buffer
45 unsigned short datalength; ///< the length of the data currently in the buffer 45 unsigned short datalength; ///< the length of the data currently in the buffer
46 unsigned short dataindex; ///< the index into the buffer where the data starts 46 unsigned short dataindex; ///< the index into the buffer where the data starts
47 } cBuffer; 47 } cBuffer;
48   48  
49 // function prototypes 49 // function prototypes
50   50  
51 //! initialize a buffer to start at a given address and have given size 51 //! initialize a buffer to start at a given address and have given size
52 void bufferInit(cBuffer* buffer, unsigned char *start, unsigned short size); 52 void bufferInit(cBuffer* buffer, unsigned char *start, unsigned short size);
53   53  
54 //! get the first byte from the front of the buffer 54 //! get the first byte from the front of the buffer
55 unsigned char bufferGetFromFront(cBuffer* buffer); 55 unsigned char bufferGetFromFront(cBuffer* buffer);
56   56  
57 //! dump (discard) the first numbytes from the front of the buffer 57 //! dump (discard) the first numbytes from the front of the buffer
58 void bufferDumpFromFront(cBuffer* buffer, unsigned short numbytes); 58 void bufferDumpFromFront(cBuffer* buffer, unsigned short numbytes);
59   59  
60 //! get a byte at the specified index in the buffer (kind of like array access) 60 //! get a byte at the specified index in the buffer (kind of like array access)
61 // ** note: this does not remove the byte that was read from the buffer 61 // ** note: this does not remove the byte that was read from the buffer
62 unsigned char bufferGetAtIndex(cBuffer* buffer, unsigned short index); 62 unsigned char bufferGetAtIndex(cBuffer* buffer, unsigned short index);
63   63  
64 //! add a byte to the end of the buffer 64 //! add a byte to the end of the buffer
65 unsigned char bufferAddToEnd(cBuffer* buffer, unsigned char data); 65 unsigned char bufferAddToEnd(cBuffer* buffer, unsigned char data);
66   66  
67 //! check if the buffer is full/not full (returns zero value if full) 67 //! check if the buffer is full/not full (returns zero value if full)
68 unsigned short bufferIsNotFull(cBuffer* buffer); 68 unsigned short bufferIsNotFull(cBuffer* buffer);
69   69  
70 //! flush (clear) the contents of the buffer 70 //! flush (clear) the contents of the buffer
71 void bufferFlush(cBuffer* buffer); 71 void bufferFlush(cBuffer* buffer);
72   72  
73 #endif 73 #endif
74 //@} 74 //@}