From a0e0e9898a7c1abeb4dbf6ba188a9bcaf523e003 Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Tue, 27 May 2014 04:44:01 +0200
Subject: More documentation

---
 src/buffer.h | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

(limited to 'src/buffer.h')

diff --git a/src/buffer.h b/src/buffer.h
index 489e509..ac1df3d 100644
--- a/src/buffer.h
+++ b/src/buffer.h
@@ -23,21 +23,36 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file buffer.h
+
+   Buffer management
+*/
+
 
 #pragma once
 
 #include "log.h"
 
 
+/** A buffer descriptor */
 struct fastd_buffer {
-	void *base;
-	size_t base_len;
+	void *base;			/**< The beginning of the allocated memory area */
+	size_t base_len;		/**< The size of the allocated memory area */
 
-	void *data;
-	size_t len;
+	void *data;			/**< The beginning of the actual data in the buffer */
+	size_t len;			/**< The data length */
 };
 
 
+/**
+   Allocate a new buffer
+
+   A buffer can have head and tail space which allows changing with data size without moving the data.
+
+   The buffer is always allocated aligned to 16 bytes to allow efficient access for SIMD instructions
+   etc. in crypto implementations
+*/
 static inline fastd_buffer_t fastd_buffer_alloc(const size_t len, size_t head_space, size_t tail_space) {
 	size_t base_len = head_space+len+tail_space;
 	void *ptr;
@@ -48,17 +63,20 @@ static inline fastd_buffer_t fastd_buffer_alloc(const size_t len, size_t head_sp
 	return (fastd_buffer_t){ .base = ptr, .base_len = base_len, .data = ptr+head_space, .len = len };
 }
 
+/** Duplicates a buffer */
 static inline fastd_buffer_t fastd_buffer_dup(const fastd_buffer_t buffer, size_t head_space, size_t tail_space) {
 	fastd_buffer_t new_buffer = fastd_buffer_alloc(buffer.len, head_space, tail_space);
 	memcpy(new_buffer.data, buffer.data, buffer.len);
 	return new_buffer;
 }
 
+/** Frees a buffer */
 static inline void fastd_buffer_free(fastd_buffer_t buffer) {
 	free(buffer.base);
 }
 
 
+/** Pulls the data head (decreases the head space) */
 static inline void fastd_buffer_pull_head(fastd_buffer_t *buffer, size_t len) {
 	if (len > (size_t)(buffer->data - buffer->base))
 		exit_bug("tried to pull buffer across base");
@@ -67,17 +85,20 @@ static inline void fastd_buffer_pull_head(fastd_buffer_t *buffer, size_t len) {
 	buffer->len += len;
 }
 
+/** Pulls the data head and fills with zeroes */
 static inline void fastd_buffer_pull_head_zero(fastd_buffer_t *buffer, size_t len) {
 	fastd_buffer_pull_head(buffer, len);
 	memset(buffer->data, 0, len);
 }
 
+/** Pulls the data head and copies data into the new space */
 static inline void fastd_buffer_pull_head_from(fastd_buffer_t *buffer, const void *data, size_t len) {
 	fastd_buffer_pull_head(buffer, len);
 	memcpy(buffer->data, data, len);
 }
 
 
+/** Pushes the buffer head (increases the head space) */
 static inline void fastd_buffer_push_head(fastd_buffer_t *buffer, size_t len) {
 	if (buffer->len < len)
 		exit_bug("tried to push buffer across tail");
@@ -86,6 +107,7 @@ static inline void fastd_buffer_push_head(fastd_buffer_t *buffer, size_t len) {
 	buffer->len -= len;
 }
 
+/** Pushes the buffer head, copying the removed buffer data somewhere else */
 static inline void fastd_buffer_push_head_to(fastd_buffer_t *buffer, void *data, size_t len) {
 	memcpy(data, buffer->data, len);
 	fastd_buffer_push_head(buffer, len);
-- 
cgit v1.2.3