From 18ae33837ee1451dddf265198b51ef3483e2029b Mon Sep 17 00:00:00 2001 From: Timo Dritschler Date: Wed, 30 Apr 2014 16:34:59 +0200 Subject: Added documentation to KIRO TRB Header file --- kiro-trb.h | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 174 insertions(+), 22 deletions(-) (limited to 'kiro-trb.h') 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 #include @@ -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 -- cgit v1.2.3