diff options
| -rw-r--r-- | kiro-trb.c | 8 | ||||
| -rw-r--r-- | kiro-trb.h | 196 |
2 files changed, 180 insertions, 24 deletions
@@ -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; } @@ -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 |