summaryrefslogtreecommitdiffstats
path: root/src/kiro-trb.h
blob: 3549a1d85e618818d8cf2804e4e23ec51b31f388 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
/* 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;

};

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);

/**
 * kiro_trb_new:
 *
 *   Creates a new, unshaped #KiroTrb and returns a pointer to it.
 *
 * Returns: (transfer full): A pointer to a new #KiroTrb
 * See also:
 *   kiro_trb_free, kiro_trb_reshape
 */
KiroTrb*    kiro_trb_new                (void);

/**
 * kiro_trb_free:
 * @trb: (transfer none): The #KiroTrb that is to be freed
 *
 *   Clears all underlying memory and frees the object memory.
 *
 * Note:
 *   The internal memory is also freed when calling this function. If you want
 *   to continue using the raw @trb memory after call this function, you need to
 *   memcpy() its content using the information optained from
 *   kiro_trb_get_raw_buffer and kiro_trb_get_raw_size.
 * See also:
 *   kiro_trb_new
 */
void        kiro_trb_free               (KiroTrb *trb);


/* trb functions */

/**
 * kiro_trb_get_element_size:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 *
 *   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:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 *
 *   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:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 *
 *   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:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 *
 *   Returns a pointer to the memory structure of the given buffer.
 *
 * Returns: (transfer none): a pointer to the buffer memory
 * 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:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 * @index: Index of the element in the buffer to access
 *
 *   Returns a pointer to the element in the buffer at the given index.
 *
 * Returns: (transfer none): a pointer to the element 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, glong index);


/**
 * kiro_trb_dma_push:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 *
 *   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.
 *
 * Returns: (transfer none): Pointer to the bginning of element memory
 * 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 *trb);


/**
 * kiro_trb_flush:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 *
 *   Flushes the internal buffer 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_purge:
 * Completely resets the Buffer
 * @trb: (transfer none): #KiroTrb to perform the operation on
 * @free_memory: Decides how to treat intermal memory on purge
 *
 *   Resets all internal structures so the TRB becomes
 *   'uninitialized' again.
 *
 * Notes:
 *   Depending on the 'free_memory' argument, any currently
 *   held internal memory either gets free()'d or is simply
 *   unreferenced and therfore 'orphaned'.
 * See also:
 *   kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
 */
void kiro_trb_purge (KiroTrb *trb, gboolean free_memory);


/**
 * kiro_trb_is_setup:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 *
 *   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:
 * @trb: (transfer none): #KiroTrb 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
 *
 *   (Re)Allocates internal memory for the given ammount of elements
 *   at the given individual size
 *
 * Returns:
 *   integer: < 0 for error, >= 0 for success
 * 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:
 * @trb: (transfer none); #KiroTrb to perform the operation on
 * @source: Pointer to the source memory to clone from
 *
 *   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 consistent 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:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 * @source: Pointer to the memory of the element to add
 *
 *   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:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 *
 *   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:
 * @trb: (transfer none): #KiroTrb to perform the operation on
 * @source: Pointer to the source memory to adopt
 *
 *   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 consistent 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.
 *   Any previously owned memory is freed.
 * See also:
 *   kiro_trb_clone, kiro_trb_reshape
 */
void kiro_trb_adopt (KiroTrb *trb, void *source);

G_END_DECLS

#endif //__KIRO_TRB_H