Added documentation to KIRO TRB Header file

2 files changed, 180 insertions, 24 deletions

diff --git a/kiro-trb.c b/kiro-trb.c
index ff0291b..e81a4f7 100644
--- a/kiro-trb.c
+++ b/kiro-trb.c
@@ -211,9 +211,9 @@ void* kiro_trb_dma_push (KiroTrb *self)
 {
     KiroTrbPrivate* priv = KIRO_TRB_GET_PRIVATE(self);
     if(priv->initialized != 1)
-        return -1;
+        return NULL;
     if((priv->current + priv->element_size) > (priv->mem + priv->buff_size))
-        return -1;
+        return NULL;
     void *mem_out = priv->current;
     priv->current += priv->element_size;
     if(priv->current >= priv->frame_top + (priv->element_size * priv->max_elements))
@@ -229,6 +229,8 @@ void* kiro_trb_dma_push (KiroTrb *self)
 void kiro_trb_refresh (KiroTrb *self)
 {
     KiroTrbPrivate* priv = KIRO_TRB_GET_PRIVATE(self);
+    if(priv->initialized != 1)
+        return;
     struct KiroTrbInfo *tmp = (struct KiroTrbInfo *)priv->mem;
     priv->buff_size = tmp->buffer_size_bytes;
     priv->element_size = tmp->element_size;
@@ -246,6 +248,7 @@ void kiro_trb_adopt (KiroTrb *self, void *buff_in)
     if(priv->mem)
         free(priv->mem);
     priv->mem = buff_in;
+    priv->initialized = 1;
     kiro_trb_refresh(self);
 }
 
@@ -261,6 +264,7 @@ int kiro_trb_clone (KiroTrb *self, void *buff_in)
     if(priv->mem)
         free(priv->mem);
     priv->mem = newmem;
+    priv->initialized = 1;
     kiro_trb_refresh(self);
     return 0;
 }
diff --git a/kiro-trb.h b/kiro-trb.h
index 33f80c7..b1e95a7 100644
--- a/kiro-trb.h
+++ b/kiro-trb.h
@@ -18,7 +18,7 @@
 
 /**
  * SECTION: kiro-trb
- * @Short_description: KIRO 'Clever Ring Buffer'
+ * @Short_description: KIRO 'Transmittable Ring Buffer'
  * @Title: KiroTrb
  *
  * KiroTrb implements a 'Transmittable Ring Buffer' that holds all necessary information
@@ -27,7 +27,7 @@
  */
  
 #ifndef __KIRO_TRB_H
-#define __KIRO_CBR_H
+#define __KIRO_TBR_H
 
 #include <stdint.h>
 #include <glib-object.h>
@@ -50,9 +50,7 @@ typedef struct _KiroTrbPrivate    KiroTrbPrivate;
 struct _KiroTrb {
     
     GObject parent;
-    
-    /*< private >*/
-    KiroTrbPrivate *priv;
+
 };
 
 
@@ -84,20 +82,50 @@ GType       kiro_trb_get_type           (void);
 
 GObject     kiro_trb_new                (void);
 
+
 /* trb functions */
 
-uint64_t    kiro_trb_get_element_count  (KiroTrb* trb);
+/**
+ * kiro_trb_get_element_size - Returns the element size in bytes
+ * @trb: KIRO TRB to perform the operation on
+ * Description:
+ *   Returns the size of the individual elements in the buffer
+ * See also:
+ *   kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
+ */
+uint64_t kiro_trb_get_element_size (KiroTrb* trb);
 
-uint64_t    kiro_trb_get_element_size   (KiroTrb* trb);
+/**
+ * kiro_trb_get_max_elements - Returns the capacity of the buffer
+ * @trb: KIRO TRB to perform the operation on
+ * Description:
+ *   Returns the mximal number of elements that can be stored in
+ *   the buffer
+ * See also:
+ *   kiro_trb_get_element_size, kiro_trb_reshape, kiro_trb_adopt,
+ *   kiro_trb_clone
+ */
+uint64_t kiro_trb_get_max_elements (KiroTrb* trb);
 
-uint64_t    kiro_trb_get_max_elements   (KiroTrb* trb);
 
-uint64_t    kiro_trb_get_raw_size       (KiroTrb* trb);
+/**
+ * kiro_trb_get_raw_size - Returns the size of the buffer memory
+ * @trb: KIRO TRB to perform the operation on
+ * Description:
+ *   Returns the size of the buffers internal memory
+ * Notes:
+ *   The returned size is given INCLUDING the header on top of the
+ *   buffers internal memory
+ * See also:
+ *   kiro_trb_reshape, kiro_trb_adopt,
+ *   kiro_trb_clone
+ */
+uint64_t kiro_trb_get_raw_size (KiroTrb* trb);
 
 
 /**
  * kiro_trb_get_raw_buffer - Returns a pointer to the buffer memory
- * @self: KIRO TRB to perform the operation on
+ * @trb: KIRO TRB to perform the operation on
  * Description:
  *   Returns a pointer to the memory structure of the given buffer.
  * Notes:
@@ -111,16 +139,18 @@ uint64_t    kiro_trb_get_raw_size       (KiroTrb* trb);
  *   a new memory block.
  *   Under no circumstances might the memory pointed to by the returned
  *   pointer be 'freed' by the user!
+ *   If this function is called on a buffer that is not yet setup,
+ *   a NULL pointer is returned instead.
  * See also:
  *   kiro_trb_refesh, kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
  */
-void*       kiro_trb_get_raw_buffer     (KiroTrb* trb);
+void* kiro_trb_get_raw_buffer (KiroTrb* trb);
 
 
 /**
  * kiro_trb_get_element - Returns a pointer to the element at the given
  * index.
- * @self: KIRO TRB to perform the operation on
+ * @trb: KIRO TRB to perform the operation on
  * @index: Index of the element in the buffer to access
  * Description:
  *   Returns a pointer to the element in the buffer at the given index.
@@ -133,15 +163,17 @@ void*       kiro_trb_get_raw_buffer     (KiroTrb* trb);
  *   changing the buffer memory entirely.
  *   Under no circumstances might the memory pointed to by the returned
  *   pointer be 'freed' by the user!
+ *   If this function is called on a buffer that is not yet setup,
+ *   a NULL pointer is returned instead.
  * See also:
  *   kiro_trb_get_element_size, kiro_trb_get_raw_buffer
  */
-void*       kiro_trb_get_element        (KiroTrb* trb, uint64_t index);
+void* kiro_trb_get_element (KiroTrb* trb, uint64_t index);
 
 
 /**
  * kiro_trb_dma_push - Gives DMA to the next element and pushes the buffer
- * @self: KIRO TRB to perform the operation on
+ * @trb: KIRO TRB to perform the operation on
  * Description:
  *   Returns a pointer to the next element in the buffer and increases
  *   all internal counters and meta data as if an element was pushed
@@ -155,25 +187,145 @@ void*       kiro_trb_get_element        (KiroTrb* trb, uint64_t index);
  *   changing the buffer memory entirely.
  *   Under no circumstances might the memory pointed to by the returned
  *   pointer be 'freed' by the user!
+ *   If this function is called on a buffer that is not yet setup,
+ *   a NULL pointer is returned instead.
  * See also:
  *   kiro_trb_push, kiro_trb_get_element_size, kiro_trb_get_raw_buffer
  */
-void*       kiro_trb_dma_push           (KiroTrb*);
+void* kiro_trb_dma_push (KiroTrb*);
 
 
-void        kiro_trb_flush              (KiroTrb* trb);
+/**
+ * kiro_trb_flush - Resets the buffer
+ * @trb: KIRO TRB to perform the operation on
+ * Description:
+ *   Resets the internal buffer structures so the buffer is
+ *   'empty' again.
+ * Notes:
+ *   The underlying memory is not cleared, freed or rewritten.
+ *   Only the header is rewritten and the internal pointer and
+ *   counter structures get reset to zero.
+ * See also:
+ *   kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
+ */
+void kiro_trb_flush (KiroTrb* trb);
 
-int         kiro_trb_is_setup           (KiroTrb* trb);
 
-int         kiro_trb_reshape            (KiroTrb* trb, uint64_t element_size, uint64_t element_count);
+/**
+ * kiro_trb_is_setup - Returns the setup status of the buffer
+ * @trb: KIRO TRB to perform the operation on
+ * Description:
+ *   Returns an integer designating of the buffer is ready to
+ *   be used or needs to be 'reshaped' before it can accept data
+ * Notes:
+ *   A return value of 0 designates that the buffer is not ready
+ *   to be used. Values greater than 0 designate that the buffer
+ *   is setup properly and is ready to accept data.
+ * See also:
+ *   kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
+ */
+int kiro_trb_is_setup (KiroTrb* trb);
 
-int         kiro_trb_clone              (KiroTrb* trb, void* source);
 
-int         kiro_trb_push               (KiroTrb* trb, void* source);
+/**
+ * kiro_trb_reshape - Reallocates internal memory and structures
+ * @trb: KIRO TRB to perform the operation on
+ * @element_size: Individual size of the elements to store in bytes
+ * @element_count: Maximum number of elements to be stored
+ * Description:
+ *   (Re)Allocates internal memory for the given ammount of elements
+ *   at the given individual size
+ * Notes:
+ *   If this function gets called when the buffer already has internal
+ *   memory (buffer is setup), that memory gets freed automatically.
+ *   If the function fails (Negative return value) none of the old
+ *   memory and data structures get changed.
+ * See also:
+ *   kiro_trb_is_setup, kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
+ */
+int kiro_trb_reshape (KiroTrb* trb, uint64_t element_size, uint64_t element_count);
+
+
+/**
+ * kiro_trb_clone - Clones the given memory into the internal memory
+ * @trb: KIRO TRB to perform the operation on
+ * @source: Pointer to the source memory to clone from
+ * Description:
+ *   Interprets the given memory as a pointer to another KIRO TRB and
+ *   tries to copy that memory into its own.
+ * Notes:
+ *   The given memory is treated as a correct KIRO TRB memory block,
+ *   including a consistend memory header. That header is read and
+ *   then cloned into the internal memory according to the headers
+ *   information.
+ *   If the given memory is not a consistent KIRO TRB memory block,
+ *   the behavior of this function is undefined.
+ *   Returns 0 if the buffer was cloned and -1 if memory allocation
+ *   failed.
+ * See also:
+ *   kiro_trb_reshape, kiro_trb_adopt
+ */
+int kiro_trb_clone (KiroTrb* trb, void* source);
+
+
+/**
+ * kiro_trb_push - Adds an element into the buffer
+ * @trb: KIRO TRB to perform the operation on
+ * @source: Pointer to the memory of the element to add
+ * Description:
+ *   Copies the given element and adds it into the buffer
+ * Notes:
+ *   This function will read n-Bytes from the given address according
+ *   to the setup element_size. The read memory is copied directly
+ *   into the internal memory structure.
+ *   Returns 0 on success, -1 on failure.
+ *   In case of failure, no internal memory will change as if the
+ *   call to kiro_trb_push has never happened.
+ * See also:
+ *   kiro_trb_push_dma, kiro_trb_get_element_size, kiro_trb_clone,
+ *   kiro_trb_adopt
+ */
+int kiro_trb_push (KiroTrb* trb, void* source);
+
+
+/**
+ * kiro_trb_refresh - Re-reads the TRBs memory header
+ * @trb: KIRO TRB to perform the operation on
+ * Description:
+ *   Re-reads the internal memory header and sets up all pointers
+ *   and counters in accordance to these information
+ * Notes:
+ *   This function is used in case the TRBs memory got changed
+ *   directly (For example, by a DMA operation) to make the TRB
+ *   aware of the changes to its memory. Only the buffers memory
+ *   header is examined and changes are made according to these
+ *   informations.
+ * See also:
+ *   kiro_trb_get_raw_buffer, kiro_trb_push_dma, kiro_trb_adopt
+ */
+void kiro_trb_refresh (KiroTrb* trb);
 
-void        kiro_trb_refresh            (KiroTrb* trb);
 
-void        kiro_trb_adopt              (KiroTrb* trb, void* source);
+/**
+ * kiro_trb_adopt - Adopts the given memory into the TRB
+ * @trb: KIRO TRB to perform the operation on
+ * @source: Pointer to the source memory to adopt
+ * Description:
+ *   Interprets the given memory as a pointer to another KIRO TRB and
+ *   takes ownership over the memory.
+ * Notes:
+ *   The given memory is treated as a correct KIRO TRB memory block,
+ *   including a consistend memory header. That header is read and
+ *   the TRB sets up all internal structures in accordance to that
+ *   header.
+ *   If the given memory is not a consistent KIRO TRB memory block,
+ *   the behavior of this function is undefined.
+ *   The TRB takes full ownership of the given memory and may free
+ *   it at will.
+ * See also:
+ *   kiro_trb_clone, kiro_trb_reshape
+ */
+void kiro_trb_adopt (KiroTrb* trb, void* source);
 
 G_END_DECLS