KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
databuffer.h
Go to the documentation of this file.
1 /*
2  * KM3NeT CLB v2 Firmware
3  * ----------------------
4  *
5  * Copyright 2013 National Institute for Subatomic Physics Nikhef
6  *
7  * All Rights Reserved.
8  *
9  *
10  * File : databuffer.h
11  * Created : 17 apr. 2013
12  * Author : Vincent van Beveren
13  */
14 
15 
16 #ifndef DATABUFFER_H_
17 #define DATABUFFER_H_
18 
19 /**
20  * @file
21  *
22  * @ingroup util
23  *
24  * DataBuffer reads and writes data into a buffer in the same format as defined in the data
25  * Java DataOutput / DataInput interfaces. Supported are: the 'Write', Byte, Short, Int, Long and
26  * Boolean.
27  */
28 #include <stdint.h>
29 #include <stdbool.h>
30 #include <stddef.h>
31 
32 #include "util/float.h"
33 
34 #define DB_ERR_NONE 0x00 //!< Indicates no error
35 #define DB_ERR_INVALID_BUFFER 0x01 //!< Indicates an invalid buffer
36 #define DB_ERR_END_OF_BUFFER 0x02 //!< Indicates the end of the buffer has been reached
37 #define DB_ERR_NOT_SUPPORTED 0x03 //!< De type is not supported.
38 
39 
40 #define DB_STR_OVERHEAD 2 //!< Overhead for a String
41 
42 /**
43  * Defines a DataBuffer structure
44  */
45 typedef struct
46 {
47  uint8_t * start; //!< Start Pointer
48  uint8_t * end; //!< End Pointer
49  uint8_t * cur; //!< Current Pointer
50  int error; //!< Last error.
51 } DataBuffer;
52 
53 /**
54  * Simple buffer initialization.
55  *
56  * Usage:
57  * char buf[80];
58  * DataBuffer db = DB_BUF_INIT( buf, sizeof(buf) );
59  *
60  * @param PTR The pointer to the start of the buffer.
61  * @param LEN The length of the buffer in bytes.
62  */
63 #define DB_BUF_INIT(PTR, LEN) { .start = PTR, .cur = PTR, .end = PTR + LEN, .error = DB_ERR_NONE }
64 
65 /**
66  * Resets the buffer to its initial state.
67  *
68  * @param buf The buffer to reset.
69  */
70 static inline void dbReset(DataBuffer * buf)
71 {
72  buf->cur = buf->start;
73  buf->error = 0;
74 }
75 
76 /**
77  * Returns the lenght of the current buffer.
78  *
79  * @param buf The buffer to query.
80  *
81  * @return The number of bytes occupied in the buffer.
82  */
83 static inline uint32_t dbLength(DataBuffer * buf)
84 {
85  return (uint32_t) ( buf->cur - buf->start );
86 }
87 
88 /**
89  * Returns the number of bytes still free in the buffer.
90  *
91  * @param buf The buffer to query.
92  *
93  * @return The number of bytes free in the buffer.
94  */
95 static inline uint32_t dbFree(DataBuffer * buf)
96 {
97  return (uint32_t) ( buf->end - buf->cur );
98 }
99 
100 
101 /**
102  * Skips a number of bytes in the buffer.
103  *
104  * @param buf The buffer.
105  * @param skipSize The number of bytes to skip
106  *
107  * @retval true Success
108  * @retval false Failure, check buf.error. Prolly not so many bytes available.
109  */
110 bool dbSkip(DataBuffer * buf, size_t skipSize);
111 
112 /**
113  * Returns the total size of the buffer
114  *
115  * @param buf The buffer to query.
116  *
117  * @return The total size of the buffer.
118  */
119 static inline uint32_t dbSize(DataBuffer * buf)
120 {
121  return (uint32_t) ( buf->end - buf->start );
122 }
123 
124 
125 
126 /**
127  * Writes the given buffer with the specified length.
128  *
129  * @param buffer The buffer to copy
130  * @param len The number of bytes to copy
131  *
132  * @retval true Success
133  * @retval false Failure, check buf.error
134  */
135 bool dbWrite(DataBuffer * buf, uint8_t * buffer, int len);
136 
137 /**
138  * Reads into given buffer with the specified length.
139  *
140  * @param buffer The buffer to copy in to.
141  * @param len The number of bytes to copy
142  *
143  *
144  * @retval true Success
145  * @retval false Failure, check buf.error
146  */
147 bool dbRead(DataBuffer * buf, uint8_t * buffer, int len);
148 
149 /**
150  * Writes a byte.
151  *
152  * @param buf The buffer to write into.
153  * @param byte The byte.
154  *
155  * @retval true Success
156  * @retval false Failure, check buf.error
157  */
158 bool dbWriteI8(DataBuffer * buf, int8_t byte);
159 
160 /**
161  * Reads an byte.
162  *
163  * @param buf The buffer to read from.
164  * @param byte The the byte
165  *
166  * @retval true Success
167  * @retval false Failure, check buf.error
168  */
169 bool dbReadI8(DataBuffer * buf, int8_t * byte);
170 
171 
172 /**
173  * Writes a unsigned byte.
174  *
175  * @param buf The buffer to write into.
176  * @param byte The byte.
177  *
178  * @retval true Success
179  * @retval false Failure, check buf.error
180  */
181 bool dbWriteU8(DataBuffer * buf, uint8_t byte);
182 
183 /**
184  * Reads an unsigned byte.
185  *
186  * @param buf The buffer to read from.
187  * @param byte The the byte
188  *
189  * @retval true Success
190  * @retval false Failure, check buf.error
191  */
192 bool dbReadU8(DataBuffer * buf, uint8_t * byte);
193 
194 /**
195  * Writes a 32-bit floating point
196  *
197  * @param buf The buffer to write into.
198  * @param flt The floating-point number.
199  *
200  * @retval true Success
201  * @retval false Failure, check buf.error
202  */
203 bool dbWriteF32(DataBuffer * buf, f32_t flt);
204 
205 /**
206  * Reads an 32-bit floating point.
207  *
208  * @param buf The buffer to read from.
209  * @param flt The the byte
210  *
211  * @retval true Success
212  * @retval false Failure, check buf.error
213  */
214 bool dbReadF32(DataBuffer * buf, f32_t * flt);
215 
216 /**
217  * Writes a 64-bit floating point
218  *
219  * @param buf The buffer to write into.
220  * @param flt The floating-point number.
221  *
222  * @retval true Success
223  * @retval false Failure, check buf.error
224  */
225 bool dbWriteF64(DataBuffer * buf, f64_t flt);
226 
227 /**
228  * Reads an 64-bit floating point.
229  *
230  * @param buf The buffer to read from.
231  * @param flt The the byte
232  *
233  * @retval true Success
234  * @retval false Failure, check buf.error
235  */
236 bool dbReadF64(DataBuffer * buf, f64_t * flt);
237 
238 
239 
240 /**
241  * Writes a boolean.
242  *
243  * @param buf The buffer to write into.
244  * @param boolean The boolean.
245  *
246  * @retval true Success
247  * @retval false Failure, check buf.error
248  */
249 static inline bool dbWriteBool(DataBuffer * buf, bool boolean)
250 {
251  return dbWriteU8(buf, boolean ? 1 : 0);
252 }
253 
254 /**
255  * Reads a boolean.
256  *
257  * @param buf The buffer to read from.
258  * @param boolean The boolean.
259  *
260  * @retval true Success
261  * @retval false Failure, check buf.error
262  */
263 static inline bool dbReadBool(DataBuffer * buf, bool * boolean)
264 {
265  uint8_t byte;
266  if (dbReadU8(buf, &byte)) {
267  *boolean = byte == 1 ? true : false;
268  return true;
269  }
270  return false;
271 }
272 
273 /**
274  * Writes a short (16 bits signed) integer.
275  *
276  * @param buf The buffer to write into.
277  * @param i The 16 bit signed integer to write.
278  *
279  * @retval true Success
280  * @retval false Failure, check buf.error
281  */
282 bool dbWriteI16(DataBuffer * buf, int16_t i);
283 
284 /**
285  * Writes a unsigned short (16 bits unsigned) integer.
286  *
287  * @param buf The buffer to write into.
288  * @param u The 16 bit unsigned integer to write.
289  *
290  * @retval true Success
291  * @retval false Failure, check buf.error
292  */
293 bool dbWriteU16(DataBuffer * buf, uint16_t u);
294 
295 
296 /**
297  * Reads a short (16 bits signed) integer.
298  *
299  * @param buf The buffer to write into.
300  * @param i Pointer to a 16 bit signed integer. Will write the value to the location
301  * of the pointer.
302  *
303  * @retval true Success
304  * @retval false Failure, check buf.error
305  */
306 bool dbReadI16(DataBuffer * buf, int16_t * i);
307 
308 /**
309  * Reads a unsigned short (16 bits unsigned) integer.
310  *
311  * @param buf The buffer to write into.
312  * @param u Pointer to a 16 bit unsigned integer. Will write the value to the location
313  * of the pointer.
314  *
315  * @retval true Success
316  * @retval false Failure, check buf.error
317  */
318 bool dbReadU16(DataBuffer * buf, uint16_t * u);
319 
320 
321 
322 /**
323  * Writes an 32 bits signed integer.
324  *
325  * @param buf The buffer to write into.
326  * @param i The 32 bit signed integer.
327  *
328  * @retval true Success
329  * @retval false Failure, check buf.error
330  */
331 bool dbWriteI32(DataBuffer * buf, int32_t i);
332 
333 /**
334  * Writes an 32 bits unsigned integer.
335  *
336  * @param buf The buffer to write into.
337  * @param u The 32 bit unsigned integer.
338  *
339  * @retval true Success
340  * @retval false Failure, check buf.error
341  */
342 bool dbWriteU32(DataBuffer * buf, uint32_t u);
343 
344 
345 /**
346  * Reads an 32 bits signed integer.
347  *
348  * @param buf The buffer to write into.
349  * @param i Pointer to the 32 bit signed integer. Will write the value to the location
350  * of the pointer.
351  *
352  * @retval true Success
353  * @retval false Failure, check buf.error
354  */
355 bool dbReadI32(DataBuffer * buf, int32_t * i);
356 
357 
358 /**
359  * Reads an 32 bits unsigned integer.
360  *
361  * @param buf The buffer to write into.
362  * @param u Pointer to the 32 bit unsigned integer. Will write the value to the location
363  * of the pointer.
364  *
365  * @retval true Success
366  * @retval false Failure, check buf.error
367  */
368 bool dbReadU32(DataBuffer * buf, uint32_t * u);
369 
370 
371 /**
372  * Writes an 64 bits signed integer.
373  *
374  * @param buf The buffer to write into.
375  * @param i The 64 bit signed integer.
376  *
377  * @retval true Success
378  * @retval false Failure, check buf.error
379  */
380 bool dbWriteI64(DataBuffer * buf, int64_t i);
381 
382 /**
383  * Reads an 64 bits signed integer.
384  *
385  * @param buf The buffer to write into.
386  * @param i Pointer to the 64 bit signed integer. Will write the value to the location
387  * of the pointer.
388  *
389  * @retval true Success
390  * @retval false Failure, check buf.error
391  */
392 bool dbReadI64(DataBuffer * buf, int64_t * i);
393 
394 /**
395  * Writes an 64 bits unsigned integer.
396  *
397  * @param buf The buffer to write into.
398  * @param i The 64 bit signed integer.
399  *
400  * @retval true Success
401  * @retval false Failure, check buf.error
402  */
403 bool dbWriteU64(DataBuffer * buf, uint64_t i);
404 
405 /**
406  * Reads an 64 bits unsigned integer.
407  *
408  * @param buf The buffer to write into.
409  * @param i Pointer to the 64 bit unsigned integer. Will write the value to the location
410  * of the pointer.
411  *
412  * @retval true Success
413  * @retval false Failure, check buf.error
414  */
415 bool dbReadU64(DataBuffer * buf, uint64_t * i);
416 
417 
418 
419 /**
420  * Writes a String as 'sort of' UTF-8 encoding, as defined in the Java DataOuput and DataInput
421  * writeUTF / readUTF methods. However, it does not write any characters above ASCII value 127.
422  * If these values are encountered, a '@' (at) sign will be inserted instead.
423  *
424  * @see http://docs.oracle.com/javase/6/docs/api/java/io/DataOutput.html#writeUTF(java.lang.String)
425  *
426  * @param buf The buffer to write to
427  * @param s The string to write (must be null-terminated!)
428  * @param max The maximum bytes in buffer it should use. Else string is truncated.
429  *
430  * @retval true Success
431  * @retval false Failure, check buf.error
432  */
433 bool dbWriteString(DataBuffer * buf, const char * s, int max);
434 
435 /**
436  * Reads a string from the stream. Values which are out of the range of this sytems char
437  * type are replaced with a question mark.
438  *
439  * @see http://docs.oracle.com/javase/6/docs/api/java/io/DataOutput.html#writeUTF(java.lang.String)
440  *
441  * @param buf The buffer to read from.
442  * @param s The target string pointer with pre-allocated memory
443  * @param size The size of hte target memory to prevent overflow.
444  *
445  * @retval true Success
446  * @retval false Failure, check buf.error
447  */
448 bool dbReadString(DataBuffer * buf, char * s, int size);
449 
450 #endif /* DATABUFFER_H_ */
bool dbReadF64(DataBuffer *buf, f64_t *flt)
Reads an 64-bit floating point.
Definition: databuffer.c:345
bool dbReadU8(DataBuffer *buf, uint8_t *byte)
Reads an unsigned byte.
Definition: databuffer.c:153
bool dbReadString(DataBuffer *buf, char *s, int size)
Reads a string from the stream.
Definition: databuffer.c:103
bool dbSkip(DataBuffer *buf, size_t skipSize)
Skips a number of bytes in the buffer.
Definition: databuffer.c:179
bool dbWriteI16(DataBuffer *buf, int16_t i)
Writes a short (16 bits signed) integer.
Definition: databuffer.c:173
static bool dbWriteBool(DataBuffer *buf, bool boolean)
Writes a boolean.
Definition: databuffer.h:249
bool dbReadU16(DataBuffer *buf, uint16_t *u)
Reads a unsigned short (16 bits unsigned) integer.
Definition: databuffer.c:186
bool dbWriteI32(DataBuffer *buf, int32_t i)
Writes an 32 bits signed integer.
Definition: databuffer.c:213
bool dbWriteI8(DataBuffer *buf, int8_t byte)
Writes a byte.
Definition: databuffer.c:129
Special library for primitive IEEE 754 floating point handling without dragging all float support alo...
bool dbReadF32(DataBuffer *buf, f32_t *flt)
Reads an 32-bit floating point.
Definition: databuffer.c:340
uint8_t * end
End Pointer.
Definition: databuffer.h:48
uint8_t * start
Start Pointer.
Definition: databuffer.h:47
static void dbReset(DataBuffer *buf)
Resets the buffer to its initial state.
Definition: databuffer.h:70
Defines a DataBuffer structure.
Definition: databuffer.h:45
static uint32_t dbFree(DataBuffer *buf)
Returns the number of bytes still free in the buffer.
Definition: databuffer.h:95
static bool dbReadBool(DataBuffer *buf, bool *boolean)
Reads a boolean.
Definition: databuffer.h:263
static uint32_t dbLength(DataBuffer *buf)
Returns the lenght of the current buffer.
Definition: databuffer.h:83
bool dbReadI64(DataBuffer *buf, int64_t *i)
Reads an 64 bits signed integer.
Definition: databuffer.c:284
int error
Last error.
Definition: databuffer.h:50
bool dbWriteF64(DataBuffer *buf, f64_t flt)
Writes a 64-bit floating point.
Definition: databuffer.c:332
uint32_t f32_t
32 bit representation for float.
Definition: float.h:30
bool dbWriteF32(DataBuffer *buf, f32_t flt)
Writes a 32-bit floating point.
Definition: databuffer.c:318
uint64_t f64_t
642 bit representation for float
Definition: float.h:33
bool dbWriteU8(DataBuffer *buf, uint8_t byte)
Writes a unsigned byte.
Definition: databuffer.c:146
bool dbReadI8(DataBuffer *buf, int8_t *byte)
Reads an byte.
Definition: databuffer.c:136
bool dbWriteU64(DataBuffer *buf, uint64_t i)
Writes an 64 bits unsigned integer.
Definition: databuffer.c:245
bool dbReadU32(DataBuffer *buf, uint32_t *u)
Reads an 32 bits unsigned integer.
Definition: databuffer.c:219
bool dbWrite(DataBuffer *buf, uint8_t *buffer, int len)
Writes the given buffer with the specified length.
Definition: databuffer.c:40
bool dbWriteI64(DataBuffer *buf, int64_t i)
Writes an 64 bits signed integer.
Definition: databuffer.c:269
bool dbWriteString(DataBuffer *buf, const char *s, int max)
Writes a String as &#39;sort of&#39; UTF-8 encoding, as defined in the Java DataOuput and DataInput writeUTF ...
Definition: databuffer.c:74
static uint32_t dbSize(DataBuffer *buf)
Returns the total size of the buffer.
Definition: databuffer.h:119
bool dbReadI32(DataBuffer *buf, int32_t *i)
Reads an 32 bits signed integer.
Definition: databuffer.c:262
bool dbRead(DataBuffer *buf, uint8_t *buffer, int len)
Reads into given buffer with the specified length.
Definition: databuffer.c:48
bool dbReadI16(DataBuffer *buf, int16_t *i)
Reads a short (16 bits signed) integer.
Definition: databuffer.c:194
uint8_t * cur
Current Pointer.
Definition: databuffer.h:49
bool dbWriteU32(DataBuffer *buf, uint32_t u)
Writes an 32 bits unsigned integer.
Definition: databuffer.c:200
bool dbWriteU16(DataBuffer *buf, uint16_t u)
Writes a unsigned short (16 bits unsigned) integer.
Definition: databuffer.c:162
bool dbReadU64(DataBuffer *buf, uint64_t *i)
Reads an 64 bits unsigned integer.
Definition: databuffer.c:230