Added new function 'kiro_trb_dma_push' that allows the user to directly

write a new element into the buffers memory
Changed the name of 'kiro_trb_ingest' to 'kiro_trb_adopt'
Added new function 'kiro_trb_clone' that copies the pointed memory
before 'adopting' it.
Started to add documentation

5 files changed, 112 insertions, 8 deletions

diff --git a/kiro-client.c b/kiro-client.c
index 253251f..3df870f 100644
--- a/kiro-client.c
+++ b/kiro-client.c
@@ -226,7 +226,7 @@ int kiro_client_sync (KiroClient *self)
     if(!kiro_trb_is_setup(priv->buffer))
     {
         //First time setup
-        kiro_trb_ingest(priv->buffer, ctx->rdma_mr->mem);
+        kiro_trb_adopt(priv->buffer, ctx->rdma_mr->mem);
     }
     else
     {
diff --git a/kiro-server.c b/kiro-server.c
index d4cf7bc..1ed47f8 100644
--- a/kiro-server.c
+++ b/kiro-server.c
@@ -136,6 +136,9 @@ int kiro_server_start (KiroServer *self, char *address, char *port)
     }
     printf("Enpoint listening.\n");
     
+    
+    // ---> *SNIP*
+    
     priv->client = (struct kiro_connection *)calloc(1, sizeof(struct kiro_connection));
     if(!priv->client)
     {
diff --git a/kiro-trb.c b/kiro-trb.c
index b433e38..ff0291b 100644
--- a/kiro-trb.c
+++ b/kiro-trb.c
@@ -163,6 +163,7 @@ void kiro_trb_flush (KiroTrb *self)
     KiroTrbPrivate* priv = KIRO_TRB_GET_PRIVATE(self);
     priv->iteration = 0;
     priv->current = priv->frame_top;
+    write_header(priv);
 }
 
 
@@ -182,7 +183,7 @@ int kiro_trb_reshape (KiroTrb *self, uint64_t element_size, uint64_t element_cou
     ((struct KiroTrbInfo *)newmem)->buffer_size_bytes = new_size;
     ((struct KiroTrbInfo *)newmem)->element_size = element_size;
     ((struct KiroTrbInfo *)newmem)->offset = 0;
-    kiro_trb_ingest(self, newmem);
+    kiro_trb_adopt(self, newmem);
     return 0;
 }
 
@@ -206,6 +207,25 @@ int kiro_trb_push (KiroTrb *self, void *element_in)
 }
 
 
+void* kiro_trb_dma_push (KiroTrb *self)
+{
+    KiroTrbPrivate* priv = KIRO_TRB_GET_PRIVATE(self);
+    if(priv->initialized != 1)
+        return -1;
+    if((priv->current + priv->element_size) > (priv->mem + priv->buff_size))
+        return -1;
+    void *mem_out = priv->current;
+    priv->current += priv->element_size;
+    if(priv->current >= priv->frame_top + (priv->element_size * priv->max_elements))
+    {
+        priv->current = priv->frame_top;
+        priv->iteration++;
+    }
+    write_header(priv);
+    return mem_out;        
+}
+
+
 void kiro_trb_refresh (KiroTrb *self)
 {
     KiroTrbPrivate* priv = KIRO_TRB_GET_PRIVATE(self);
@@ -220,7 +240,7 @@ void kiro_trb_refresh (KiroTrb *self)
 }
 
 
-void kiro_trb_ingest (KiroTrb *self, void *buff_in)
+void kiro_trb_adopt (KiroTrb *self, void *buff_in)
 {
     KiroTrbPrivate* priv = KIRO_TRB_GET_PRIVATE(self);
     if(priv->mem)
@@ -228,3 +248,19 @@ void kiro_trb_ingest (KiroTrb *self, void *buff_in)
     priv->mem = buff_in;
     kiro_trb_refresh(self);
 }
+
+
+int kiro_trb_clone (KiroTrb *self, void *buff_in)
+{
+    KiroTrbPrivate* priv = KIRO_TRB_GET_PRIVATE(self);
+    struct KiroTrbInfo *header = (struct KiroTrbInfo *)buff_in;
+    void *newmem = malloc(header->buffer_size_bytes);
+    if(!newmem)
+        return -1;
+    memcpy(newmem, buff_in, header->buffer_size_bytes);
+    if(priv->mem)
+        free(priv->mem);
+    priv->mem = newmem;
+    kiro_trb_refresh(self);
+    return 0;
+}
diff --git a/kiro-trb.h b/kiro-trb.h
index 0a39a4a..33f80c7 100644
--- a/kiro-trb.h
+++ b/kiro-trb.h
@@ -94,21 +94,86 @@ uint64_t    kiro_trb_get_max_elements   (KiroTrb* trb);
 
 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
+ * Description:
+ *   Returns a pointer to the memory structure of the given buffer.
+ * Notes:
+ *   The returned pointer points to the beginning of the internal
+ *   memory of the buffer, including all header information. The
+ *   user is responsible to ensure the consistency of any data
+ *   written to the memory and should call 'kiro_trb_refesh' in
+ *   case any header information was changed.
+ *   The pointed to memory might become invalid at any time by
+ *   concurrent access to the TRB, reshaping, adopting or cloning
+ *   a new memory block.
+ *   Under no circumstances might the memory pointed to by the returned
+ *   pointer be 'freed' by the user!
+ * See also:
+ *   kiro_trb_refesh, kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
+ */
 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
+ * @index: Index of the element in the buffer to access
+ * Description:
+ *   Returns a pointer to the element in the buffer at the given index.
+ * Notes:
+ *   The returned pointer to the element is only guaranteed to be valid
+ *   immediately after the function call. The user is responsible to
+ *   ensure that no data is written to the returned memory. The
+ *   element pointed to might become invalid at any time by any concurrent
+ *   access to the buffer wraping around and overwriting the element or
+ *   changing the buffer memory entirely.
+ *   Under no circumstances might the memory pointed to by the returned
+ *   pointer be 'freed' by the user!
+ * See also:
+ *   kiro_trb_get_element_size, kiro_trb_get_raw_buffer
+ */
 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
+ * 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
+ *   onto the buffer.
+ * Notes:
+ *   The returned pointer to the element is only guaranteed to be valid
+ *   immediately after the function call. The user is responsible to
+ *   ensure that no more data is written than 'element_size'. The
+ *   element pointed to might become invalid at any time by any concurrent
+ *   access to the buffer wraping around and overwriting the element or
+ *   changing the buffer memory entirely.
+ *   Under no circumstances might the memory pointed to by the returned
+ *   pointer be 'freed' by the user!
+ * See also:
+ *   kiro_trb_push, kiro_trb_get_element_size, kiro_trb_get_raw_buffer
+ */
+void*       kiro_trb_dma_push           (KiroTrb*);
+
+
 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);
 
+int         kiro_trb_clone              (KiroTrb* trb, void* source);
+
 int         kiro_trb_push               (KiroTrb* trb, void* source);
 
 void        kiro_trb_refresh            (KiroTrb* trb);
 
-void        kiro_trb_ingest             (KiroTrb* trb, void* source);
+void        kiro_trb_adopt              (KiroTrb* trb, void* source);
 
 G_END_DECLS
 
diff --git a/test.c b/test.c
index 56ed5cf..4aac2f5 100644
--- a/test.c
+++ b/test.c
@@ -31,16 +31,16 @@ int main(void)
     void *buffer = kiro_trb_get_raw_buffer(rb);
     uint64_t foo = 0xAFFED00F;
     uint64_t bar = 0x1337BEEF;
-    kiro_trb_push(rb, &foo);
-    kiro_trb_push(rb, &foo);
-    kiro_trb_push(rb, &foo);
+    memcpy(kiro_trb_dma_push(rb), &foo, sizeof(foo));
+    memcpy(kiro_trb_dma_push(rb), &foo, sizeof(foo));
+    memcpy(kiro_trb_dma_push(rb), &foo, sizeof(foo));
     kiro_trb_push(rb, &bar);
     kiro_trb_push(rb, &foo);
     kiro_trb_push(rb, &foo);
     uint64_t *maman = kiro_trb_get_element(rb, 3);
     printf("Stored in old: %x\n", *maman);
     KiroTrb *rb2 = g_object_new(KIRO_TYPE_TRB, NULL);
-    kiro_trb_ingest(rb2, kiro_trb_get_raw_buffer(rb));
+    kiro_trb_clone(rb2, kiro_trb_get_raw_buffer(rb));
     maman = kiro_trb_get_element(rb2, 3);
     printf("Stored in New: %x\n", *maman);
     sleep(1);