diff options
Diffstat (limited to 'src/kiro-trb.h')
| -rw-r--r-- | src/kiro-trb.h | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/src/kiro-trb.h b/src/kiro-trb.h new file mode 100644 index 0000000..5c2b462 --- /dev/null +++ b/src/kiro-trb.h @@ -0,0 +1,332 @@ +/* Copyright (C) 2014 Timo Dritschler <timo.dritschler@kit.edu> + (Karlsruhe Institute of Technology) + + This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by the + Free Software Foundation; either version 2.1 of the License, or (at your + option) any later version. + + This library is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS + FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more + details. + + You should have received a copy of the GNU Lesser General Public License along + with this library; if not, write to the Free Software Foundation, Inc., 51 + Franklin St, Fifth Floor, Boston, MA 02110, USA +*/ + +/** + * SECTION: kiro-trb + * @Short_description: KIRO 'Transmittable Ring Buffer' + * @Title: KiroTrb + * + * KiroTrb implements a 'Transmittable Ring Buffer' that holds all necessary information + * about its content inside itself, so its data can be exchanged between different + * instances of the KiroTrb Class and/or sent over a network. + */ + +#ifndef __KIRO_TRB_H +#define __KIRO_TBR_H + +#include <stdint.h> +#include <glib-object.h> + +G_BEGIN_DECLS + +#define KIRO_TYPE_TRB (kiro_trb_get_type()) +#define KIRO_TRB(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), KIRO_TYPE_TRB, KiroTrb)) +#define KIRO_IS_TRB(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), KIRO_TYPE_TRB)) +#define KIRO_TRB_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), KIRO_TYPE_TRB, KiroTrbClass)) +#define KIRO_IS_TRB_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), KIRO_TYPE_TRB)) +#define KIRO_TRB_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), KIRO_TYPE_TRB, KiroTrbClass)) + + +typedef struct _KiroTrb KiroTrb; +typedef struct _KiroTrbClass KiroTrbClass; +typedef struct _KiroTrbPrivate KiroTrbPrivate; + + +struct _KiroTrb { + + GObject parent; + +}; + + +/** + * IbvConnectorInterface: + * + * Base interface for IbvConnectors. + */ + +struct _KiroTrbClass { + + GObjectClass parent_class; + +}; + + +struct KiroTrbInfo { + + /* internal information about the buffer */ + uint64_t buffer_size_bytes; // Size in bytes INCLUDING this header + uint64_t element_size; // Size in bytes of one single element + uint64_t offset; // Current Offset to access the 'oldest' element (in element count!) + +} __attribute__((packed)); + + +/* GObject and GType functions */ +GType kiro_trb_get_type (void); + +GObject kiro_trb_new (void); + + +/* trb functions */ + +/** + * 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); + +/** + * 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); + + +/** + * 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 + * @trb: 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! + * 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); + + +/** + * kiro_trb_get_element - Returns a pointer to the element at the given + * index. + * @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. + * 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! + * 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); + + +/** + * kiro_trb_dma_push - Gives DMA to the next element and pushes the buffer + * @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 + * 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! + * 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*); + + +/** + * 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); + + +/** + * 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); + + +/** + * 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_dma_push, 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); + + +/** + * 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 + +#endif //__KIRO_TRB_H
\ No newline at end of file |