Revision 1:490224f41c09, committed 2013-05-23

Comitter:

sam_grove

Date:

Thu May 23 19:26:31 2013 +0000

Parent:

0:5e4bca1bd5f7

Child:

2:d13a72146516

Child:

3:c2de0ddfe65b

Commit message:

Added documentation

Changed in this revision

--- a/Buffer.cpp	Fri May 10 18:34:16 2013 +0000
+++ b/Buffer.cpp	Thu May 23 19:26:31 2013 +0000
@@ -1,4 +1,26 @@
 
+/**
+ * @file    Buffer.cpp
+ * @brief   Software Buffer - Templated Ring Buffer for most data types
+ * @author  sam grove
+ * @version 1.0
+ * @see     
+ *
+ * Copyright (c) 2013
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
 #include "Buffer.h"
 
 template <class T>
@@ -48,9 +70,9 @@
 template <class T>
 void Buffer<T>::clear(void)
 {
-    memset(_buf, 0, _size);
     _wloc = 0;
     _rloc = 0;
+    memset(_buf, 0, _size);
     
     return;
 }
@@ -61,6 +83,7 @@
     return (_wloc == _rloc) ? 0 : 1;
 }
 
+// make the linker aware of some possible types
 template class Buffer<uint8_t>;
 template class Buffer<int8_t>;
 template class Buffer<uint16_t>;

--- a/Buffer.h	Fri May 10 18:34:16 2013 +0000
+++ b/Buffer.h	Thu May 23 19:26:31 2013 +0000
@@ -1,32 +1,125 @@
 
+/**
+ * @file    Buffer.h
+ * @brief   Software Buffer - Templated Ring Buffer for most data types
+ * @author  sam grove
+ * @version 1.0
+ * @see     
+ *
+ * Copyright (c) 2013
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
 #ifndef BUFFER_H
 #define BUFFER_H
 
 #include <stdint.h>
 #include <string.h>
 
+/** A templated software ring buffer
+ *
+ * Example:
+ * @code
+ *  #include "mbed.h"
+ *  #include "Buffer.h"
+ *
+ *  Buffer <char> buf;
+ *
+ *  int main()
+ *  {
+ *      buf = 'a';
+ *      buf.put('b');
+ *      char *head = buf.head();
+ *      puts(head);
+ *
+ *      char whats_in_there[2] = {0};
+ *      int pos = 0;
+ *
+ *      while(buf.available())
+ *      {   
+ *          whats_in_there[pos++] = buf;
+ *      }
+ *      printf("%c %c\n", whats_in_there[0], whats_in_there[1]);
+ *      buf.clear();
+ *      error("done\n\n\n");
+ *  }
+ * @endcode
+ */
+
 template <typename T>
 class Buffer
 {
 private:
-    T           *_buf;
-    uint32_t     _wloc;
-    uint32_t     _rloc;
-    uint32_t     _size;
+    T   *_buf;
+    volatile uint32_t   _wloc;
+    volatile uint32_t   _rloc;
+    uint32_t            _size;
     
     enum BUFFER_SIZE{SMALL = 0x100, MEDIUM = 0x400, LARGE = 0x1000};
 
 public:
+    /** Create a Buffer and allocate memory for it
+     *  @param size An enum from BUFFER_SIZE.
+     */
     Buffer(BUFFER_SIZE size = Buffer::SMALL);
+    
+    /** Destry a Buffer and release it's allocated memory
+     */
     ~Buffer();
     
+    /** Add a data element into the buffer
+     *  @param data Something to add to the buffer
+     */
     void put(T data);
+    
+    /** Remove a data element from the buffer
+     *  @return Pull the oldest element from the buffer
+     */
     T get(void);
+    
+    /** Get the address to the head of the buffer
+     *  @return The address of element 0 in the buffer
+     */
     T *head(void);
+    
+    /** Reset the buffer to 0. Useful if using head() to parse packeted data
+     */
     void clear(void);
-    Buffer &operator= (T data){put(data);return *this;}
+    
+    /** Determine if anything is readable in the buffer
+     *  @return 1 if something can be read, 0 otherwise
+     */
     uint32_t available(void);
     
+    /** Overloaded operator for writing to the buffer
+     *  @param data Something to put in the buffer
+     *  @return
+     */
+    Buffer &operator= (T data)
+    {
+        put(data);
+        return *this;
+    }
+    
+    /** Overloaded operator for reading from the buffer
+     *  @return Pull the oldest element from the buffer 
+     */  
+    operator int(void)
+    {
+        return get();
+    }
+    
 };
 
 #endif